Add comprehensive link handling and serializer documentation

[Copilot]

Documentation Expansion Plan

• Create /docs/link-handling/relative-uris.md - Document hard-coded relative URIs and the ./ prefix pattern
• Create /docs/link-handling/uri-templates.md - Document URI templates with RFC 6570 reference
• Create /docs/link-handling/link-header.md - Document HTTP Link Header with RFC 8288 reference
• Create /docs/link-handling/hal.md - Document HAL links support
• Create serializer documentation in separate files
  • /docs/serializers/json.md - JSON serializers (Newtonsoft.Json, System.Text.Json, native TypeScript)
  • /docs/serializers/xml.md - XML serializer (.NET only)
  • /docs/serializers/bson.md - BSON serializer (.NET only)
  • /docs/serializers/index.md - Overview with links to all serializer types
• Create /docs/link-handling/.pages - Navigation configuration file
• Create /docs/serializers/.pages - Navigation configuration file
• Update /docs/link-handling/index.md - Expand overview with links to all new pages
• Update /docs/endpoints/index.md - Add "Navigating Between Endpoints" section
• Build and verify documentation renders correctly
• Distribute serializer content into language-specific tabbed format
• Fix consistency issues in code examples

Original prompt

Overview

Extend the TypedRest documentation with additional pages covering link handling features and serializers. The documentation should cover multiple language implementations (.NET and TypeScript) using the existing tabbed code example format.

New Pages to Create

1. docs/link-handling/relative-uris.md

Document hard-coded relative URIs between endpoints, including:

• Basic usage of relative URIs
• The non-standard ./ prefix pattern for appending trailing slashes to parent URIs before resolving relative URIs
• Examples showing the difference between "subresource" and "./subresource"
• When to use the ./ prefix
• Default links via SetDefaultLink

2. docs/link-handling/uri-templates.md

Document URI templates:

• Link to RFC 6570 for template syntax details (don't duplicate RFC content)
• Focus on how to use templates in TypedRest
• Server-provided templates via Link header and HAL
• Resolving templates with LinkTemplate() method
• Default link templates via SetDefaultLinkTemplate
• Built-in defaults in Collection/Indexer endpoints

3. docs/link-handling/link-header.md

Document links transmitted via HTTP Link Header:

• Link header format per RFC 8288
• Extracting links with GetLinks() and Link() methods
• The non-standard templated=true extension for URI templates in headers
• Supported link header attributes (rel, title, templated)

4. docs/link-handling/hal.md

Document links encoded in resources via HAL:

• Link to HAL specification (don't duplicate spec content)
• Focus on how to use HAL in TypedRest
• Content type application/hal+json
• Using HAL links with standard link resolution methods
• Multiple links and templated links in HAL
• Combining with header links via AggregateLinkExtractor

5. docs/link-handling/serializers.md

Document serializers with a table showing which formats are supported by which TypedRest version:

Format	.NET	TypeScript
JSON (Newtonsoft.Json)	✅ Default	❌
JSON (System.Text.Json)	✅ Separate NuGet	❌
JSON (Native)	❌	✅ Default
XML	✅	❌
BSON	✅	❌

Include:

• Configuration options for each serializer
• How to use System.Text.Json via TypedRest.SystemTextJson NuGet package
• Custom serializers in TypeScript
• Custom JSON media types (+json suffix handling)

Files to Update

docs/link-handling/index.md

Expand the current brief list into a proper overview with:

• Links to all new pages
• Brief description of link resolution methods (GetLinks, Link, LinkTemplate)
• Reference to serializers page

docs/link-handling/.pages

Create navigation file:

nav:
  - index.md
  - relative-uris.md
  - uri-templates.md
  - link-header.md
  - hal.md
  - serializers.md

docs/endpoints/index.md

Add a new section "Navigating Between Endpoints" at the end that:

• Explains the referrer parameter inherits configuration including serializers
• Lists the different ways to link endpoints (relative URIs, URI templates, Link headers, HAL)
• Links to the link-handling documentation

Code Examples

All code examples should use the existing tabbed format with both C# and TypeScript versions:

=== "C#"

    ```csharp
    // C# example
    ```

=== "TypeScript"

    ```typescript
    // TypeScript example
    ```

Reference Implementation Details

Relative URI ./ Pattern

From .NET UriExtensions.cs:

=> new(relativeUri.StartsWith("./") ? baseUri.EnsureTrailingSlash() : baseUri, relativeUri);

From TypeScript Endpoint.ts:

protected join(relativeUri: string): URL {
    return new URL(
        relativeUri,
        relativeUri.startsWith("./") ? Endpoint.ensureTrailingSlash(this.uri) : this.uri);
}

Link Template Support in Headers

The HeaderLinkExtractor in both implementations parses templated=true from Link headers - this is a non-standard extension.

HAL Link Extraction

Both implementations use HalLinkExtractor that looks for application/hal+json content type and parses _links objects.

Serializers

• .NET: NewtonsoftJsonSerializer (default), SystemTextJsonSerializer (separate package), XmlSerializer, BsonSerializer
• TypeScript: JsonSerializer (default, uses native JSON.parse/stringify)

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[bastianeicher]

Distribute the content from serializers/index.md into serializers/json.md, serializers/bson.md and serializers/xml.md as appropriate.

Use the same pattern of language-specific tabs (=== "C#") used in the link-handling/*.md files.

[Copilot]

Distribute the content from serializers/index.md into serializers/json.md, serializers/bson.md and serializers/xml.md as appropriate.

Use the same pattern of language-specific tabs (`=== "C#"...

Distributed the serializer content into separate files with language-specific tabs in commit 2a47243.

The serializers section now includes:

• serializers/index.md - Overview with format support table and links to individual serializer pages
• serializers/json.md - JSON serialization for .NET (Newtonsoft.Json and System.Text.Json) and TypeScript
• serializers/xml.md - XML serialization for .NET
• serializers/bson.md - BSON serialization for .NET

All code examples use the === "C#" and === "TypeScript" tabbed format.

Serializers overview page:

JSON serializer page with tabbed examples: