Add DocFX documentation

.config/dotnet-tools.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.78.5",
+      "commands": [
+        "docfx"
+      ]
+    }
+  }
+}

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Publish documentation
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 9.0.x
+
+      - name: Configure GitHub Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Restore documentation tools
+        run: dotnet tool restore
+
+      - name: Build documentation
+        run: dotnet docfx docs/docfx.json --basePath "${{ steps.pages.outputs.base_path }}"
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    name: Deploy documentation
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -41,3 +41,7 @@ node_modules/
 
 /Directory.Build.targets
 
+# Generated DocFX output and API metadata
+/docs/_site/
+/docs/api/*
+!/docs/api/index.md

README.md

@@ -517,7 +517,11 @@ its children using `innerHTML`.
 `HtmxSwap.TextContent` is also handled by the `ramstack-morph` extension and does not require Idiomorph. It is supported natively
 by HTMX 2.x and 4.x; only HTMX 1.9.x needs the extension.
 
-## Sample
+## Running Locally
+
+Run the following commands from the repository root.
+
+### Demo
 
 The [`samples/Ramstack.HtmxToolkit.Demo`](samples/Ramstack.HtmxToolkit.Demo) project demonstrates request detection,
 response headers and events, MVC attributes, Tag Helpers, polling, boosted navigation, and antiforgery integration.
@@ -528,6 +532,20 @@ Run it with:
 dotnet run --project samples/Ramstack.HtmxToolkit.Demo
 ```
 
+The application is available at <https://localhost:5001> and <http://localhost:5000>.
+
+### Documentation
+
+Restore the repository-local DocFX tool, then start the documentation preview server:
+
+```console
+dotnet tool restore
+dotnet docfx docs/docfx.json --serve
+```
+
+Open <http://localhost:8080> after DocFX finishes the initial build. See
+[`docs/README.md`](docs/README.md) for standalone builds and information about API examples.
+
 ## Contributing
 
 Bug reports and pull requests are welcome. To validate a change locally:

docs/README.md

@@ -0,0 +1,31 @@
+# Building the documentation locally
+
+Restore the repository-local DocFX version:
+
+```console
+dotnet tool restore
+```
+
+Build the static site:
+
+```console
+dotnet docfx docs/docfx.json
+```
+
+Run a local preview server and open <http://localhost:8080>:
+
+```console
+dotnet docfx docs/docfx.json --serve
+```
+
+DocFX writes generated HTML to `docs/_site` and generated API metadata to `docs/api`;
+both directories are ignored by Git.
+
+## API examples
+
+API examples are maintained outside the library source code. Markdown overwrite files in
+`docs/api-overwrites` attach an `example` to an API page by its DocFX `uid`, while the
+referenced source snippets live in `docs/snippets`.
+
+To add an example, find the generated UID in `docs/api/*.yml`, add an overwrite section,
+and reference a snippet with DocFX's `[!code-csharp[](...)]` or `[!code-razor[](...)]` syntax.

docs/api-overwrites/requests.md

@@ -0,0 +1,34 @@
+---
+uid: Ramstack.HtmxToolkit.HttpRequestExtensions.IsHtmxRequest(Microsoft.AspNetCore.Http.HttpRequest)
+example:
+  - |-
+    [!code-csharp[](../snippets/requests/ReturnPartialForHtmx.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HttpRequestExtensions.IsHtmxRequest(Microsoft.AspNetCore.Http.HttpRequest,Ramstack.HtmxToolkit.HtmxRequestHeaders@)
+example:
+  - |-
+    [!code-csharp[](../snippets/requests/InspectHtmxHeaders.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HttpRequestExtensions.IsHtmxBoosted(Microsoft.AspNetCore.Http.HttpRequest)
+example:
+  - |-
+    [!code-csharp[](../snippets/requests/HandleBoostedNavigation.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxRequestAttribute
+example:
+  - |-
+    [!code-csharp[](../snippets/requests/HtmxRequestAttributeExample.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxRequestAttribute.Boosted
+example:
+  - |-
+    [!code-csharp[](../snippets/requests/BoostedRequestAttributeExample.cs)]
+---

docs/api-overwrites/responses.md

@@ -0,0 +1,48 @@
+---
+uid: Ramstack.HtmxToolkit.HttpResponseExtensions.Htmx(Microsoft.AspNetCore.Http.HttpResponse,System.Action{Ramstack.HtmxToolkit.HtmxResponse})
+example:
+  - |-
+    [!code-csharp[](../snippets/responses/ConfigureHttpResponse.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxResponse.Location(System.String,Ramstack.HtmxToolkit.HtmxLocationOptions)
+example:
+  - |-
+    [!code-csharp[](../snippets/responses/LocationWithOptions.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxLocationOptions
+example:
+  - |-
+    [!code-csharp[](../snippets/responses/LocationWithOptions.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxResponse.Redirect(System.String)
+example:
+  - |-
+    [!code-csharp[](../snippets/responses/RedirectAfterLogin.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxResponse.Reswap(Ramstack.HtmxToolkit.HtmxSwap)
+example:
+  - |-
+    [!code-csharp[](../snippets/responses/RetargetValidationErrors.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxResponse.TriggerEvent(System.String,System.Object,Ramstack.HtmxToolkit.HtmxTriggerTiming)
+example:
+  - |-
+    [!code-csharp[](../snippets/responses/TriggerClientEvent.cs)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmxResponseAttribute
+example:
+  - |-
+    [!code-csharp[](../snippets/responses/HtmxResponseAttributeExample.cs)]
+---

docs/api-overwrites/tag-helpers.md

@@ -0,0 +1,48 @@
+---
+uid: Ramstack.HtmxToolkit.TagHelpers.HtmxUrlTagHelper
+example:
+  - |-
+    [!code-razor[](../snippets/tag-helpers/UrlTagHelper.cshtml)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.TagHelpers.HtmxHeaderTagHelper
+example:
+  - |-
+    [!code-razor[](../snippets/tag-helpers/HeaderTagHelper.cshtml)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.TagHelpers.HtmxValsTagHelper
+example:
+  - |-
+    [!code-razor[](../snippets/tag-helpers/ValsTagHelper.cshtml)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.TagHelpers.HtmxRequestTagHelper
+example:
+  - |-
+    [!code-razor[](../snippets/tag-helpers/RequestTagHelper.cshtml)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.TagHelpers.HtmxConfigTagHelper
+example:
+  - |-
+    [!code-razor[](../snippets/tag-helpers/ConfigTagHelper.cshtml)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.HtmlHelperExtensions.HtmxToolkitScriptPath(Microsoft.AspNetCore.Mvc.Rendering.IHtmlHelper,System.Boolean)
+example:
+  - |-
+    [!code-razor[](../snippets/tag-helpers/ToolkitScript.cshtml)]
+---
+
+---
+uid: Ramstack.HtmxToolkit.Hosting.EndpointRouteBuilderExtensions.MapHtmxToolkitScript(Microsoft.AspNetCore.Routing.IEndpointRouteBuilder)
+example:
+  - |-
+    [!code-csharp[](../snippets/tag-helpers/MapToolkitScriptEndpoint.cs)]
+---

docs/api/index.md

@@ -0,0 +1,3 @@
+# API reference
+
+This reference is generated from the public API and XML documentation comments in `Ramstack.HtmxToolkit`.