linkdotnet · Nov 7, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,61 @@
+name: docs
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - "docs/**"
+      - "assets/**"
+      - "MIGRATION.md"
+      - "docfx.json"
+      - "dotnet-tools.json"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [ master ]
+    paths:
+      - "docs/**"
+      - "assets/**"
+      - "MIGRATION.md"
+      - "docfx.json"
+      - "dotnet-tools.json"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v7
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v6
+      with:
+        dotnet-version: |
+          10.0.x
+    - name: Restore tools
+      run: dotnet tool restore
+    - name: Build documentation
+      run: dotnet docfx docfx.json --warningsAsErrors
+    - name: Upload site
+      if: github.event_name != 'pull_request'
+      uses: actions/upload-pages-artifact@v5
+      with:
+        path: _site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v5
diff --git a/.gitignore b/.gitignore
@@ -38,3 +38,7 @@ backups/
 
 # Local image storage provider uploads
 src/LinkDotNet.Blog.Web/wwwroot/uploads/
+
+# DocFX output
+/_site/
+/obj/
diff --git a/Readme.md b/Readme.md
@@ -38,6 +38,8 @@ This also includes source code snippets. Highlighting is done via [highlight.js]
 
 ## Documentation
 
+The documentation is published at **[linkdotnet.github.io/Blog](https://linkdotnet.github.io/Blog/)**. The sources live in [`docs`](./docs) and are rendered with [DocFX](https://dotnet.github.io/docfx/). To preview changes locally run `dotnet tool restore` once, followed by `dotnet docfx docfx.json --serve`.
+
 -   [Authorization](./docs/Authorization/Readme.md)
 -   [Comments](./docs/Comments/Readme.md)
 -   [Storage Provider](./docs/Storage/Readme.md)

diff --git a/docfx.json b/docfx.json
@@ -0,0 +1,34 @@
+{
+  "$schema": "https://github.com/raw/dotnet/docfx/main/schemas/docfx.schema.json",
+  "build": {
+    "content": [
+      {
+        "src": "docs",
+        "files": ["**/*.md", "toc.yml"],
+        "dest": "."
+      },
+      {
+        "files": ["MIGRATION.md"]
+      }
+    ],
+    "resource": [
+      {
+        "src": "docs",
+        "files": ["**/images/**"],
+        "dest": "."
+      },
+      {
+        "files": ["assets/overview.gif"]
+      }
+    ],
+    "output": "_site",
+    "template": ["default", "modern"],
+    "globalMetadata": {
+      "_appName": "LinkDotNet.Blog",
+      "_appTitle": "LinkDotNet.Blog",
+      "_appFooter": "Released under the MIT License.",
+      "_enableSearch": true,
+      "pdf": false
+    }
+  }
+}
diff --git a/docs/Authorization/Auth0.md b/docs/Authorization/Auth0.md
@@ -1,4 +1,4 @@
-### Auth0
+# Auth0
 
 Auth0 is a prominent provider of OpenID Connect (OIDC) services, which is an authentication protocol built on top of OAuth 2.0. OpenID Connect is specifically designed for identity layer applications and provides a standardized way for users to authenticate and authorize themselves on websites or applications while allowing third-party applications to access limited user information in a secure manner.
 

diff --git a/docs/Authorization/AzureAD.md b/docs/Authorization/AzureAD.md
@@ -1,4 +1,4 @@
-### Azure Active Directory
+# Azure Active Directory
 
 Microsoft Entra ID (old Azure AD) is Microsoft's cloud-based identity and access management service. It supports various identity protocols, including OpenID Connect (OIDC), a standard protocol built on top of OAuth 2.0 for authentication and identity verification.
 

diff --git a/docs/Authorization/Readme.md b/docs/Authorization/Readme.md
@@ -1,4 +1,4 @@
-### Authentication and Authorization
+# Authentication and Authorization
 
 When it comes to authentication and authorization, we employ [OpenID Connect](https://openid.net/developers/how-connect-works/) as our preferred method. The primary benefit of an OpenID Connect-based provider is the conveniently customizable dashboard accessible through their website. For the sake of testing, you have the option to employ the `UseDummyAuthentication();` service. This grants every user who clicks "Login" immediate access, effectively logging them in. Here are the platforms we support:
 

diff --git a/docs/Comments/Disqus.md b/docs/Comments/Disqus.md
@@ -1,4 +1,4 @@
-### Disqus
+# Disqus
 
 For disqus you only need the short name (site-name) which you can find for example under your [home-tab](https://disqus.com/home/).
 

diff --git a/docs/Comments/Giscus.md b/docs/Comments/Giscus.md
@@ -1,4 +1,4 @@
-### Giscus
+# Giscus
 
 To provide the necessary values head over to https://giscus.app/ and go to the configuration section.
 There you can enter all the information. You will find a detailed guide on the site.

diff --git a/docs/Comments/Readme.md b/docs/Comments/Readme.md
@@ -1,4 +1,4 @@
-### Comment Section
+# Comment Section
 
 Kindly ensure to register just a single service or offer the configuration for a single node. The provided configuration illustrates both elements solely for demonstration purposes. Should multiple comment plugins be set up concurrently, a cautionary message will appear beneath the blog post.
 

diff --git a/docs/Donations/Readme.md b/docs/Donations/Readme.md
@@ -1,4 +1,4 @@
-## Donations
+# Donations
 
 The blog software allows you to integrate via different micro-transaction services. The following chapter will show you how to set up donations.
 

diff --git a/docs/Features/AdvancedFeatures.md b/docs/Features/AdvancedFeatures.md
@@ -1,4 +1,4 @@
-## Advanced Features
+# Advanced Features
 
 - [Advanced Features](#advanced-features)
 - [Shortcodes](#shortcodes)

diff --git a/docs/Features/Styling.md b/docs/Features/Styling.md
@@ -1,4 +1,4 @@
-## Styling
+# Styling
 
 - [Styling](#styling)
 - [Colors \& Fonts](#colors--fonts)

diff --git a/docs/Migrations/UpgradeAssistant.md b/docs/Migrations/UpgradeAssistant.md
@@ -360,7 +360,7 @@ fi
 
 - [MIGRATION.md](../../MIGRATION.md) - Complete migration guide with manual steps
 - [Configuration Documentation](../Setup/Configuration.md) - All configuration options
-- [Tool README](../../tools/LinkDotNet.Blog.UpgradeAssistant/README.md) - Developer documentation
+- [Tool README](https://github.com/linkdotnet/Blog/blob/master/tools/LinkDotNet.Blog.UpgradeAssistant/README.md) - Developer documentation
 
 ## Getting Help
 

diff --git a/docs/SEO/Readme.md b/docs/SEO/Readme.md
@@ -1,4 +1,4 @@
-## Search Engine Optimization (SEO)
+# Search Engine Optimization (SEO)
 
 The blog includes some of the most important tags to get indexed by a crawler. Furthermore, some aspects of the Open Graph specification are implemented.
 

diff --git a/docs/Setup/Configuration.md b/docs/Setup/Configuration.md
@@ -1,4 +1,4 @@
-### Configurations
+# Configurations
 
 ### appsettings.json
 

diff --git a/docs/Setup/Docker.md b/docs/Setup/Docker.md
@@ -1,4 +1,4 @@
-## Host the blog in Docker containers
+# Host the blog in Docker containers
 
 ### Server configuration
 

diff --git a/docs/Setup/Readme.md b/docs/Setup/Readme.md
@@ -1,4 +1,4 @@
-## Setup
+# Setup
 
 There are two main ways of using this blog:
 * Latest development build: Just clone this repository and you are good to go (aka you are using the `master` branch).

diff --git a/docs/Storage/Readme.md b/docs/Storage/Readme.md
@@ -1,4 +1,4 @@
-## Storage Provider
+# Storage Provider
 
 The blog currently supports six storage providers:
 

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,31 @@
+# LinkDotNet.Blog
+
+A blog engine written completely in C# / Blazor, built to be as configurable as possible.
+
+Authors write posts in markdown, which is rendered to HTML (including syntax-highlighted code snippets) for readers.
+
+![overview](../assets/overview.gif)
+
+## Where to start
+
+- [Setup](Setup/Readme.md) - get the blog running locally or from a release
+- [Configuration](Setup/Configuration.md) - all `appsettings.json` options
+- [Docker](Setup/Docker.md) - host the blog in containers
+- [Upgrading from an older version](Migrations/Readme.md) - breaking changes and the Upgrade Assistant
+
+## Guides
+
+- [Storage Provider](Storage/Readme.md)
+- [Authorization](Authorization/Readme.md)
+- [Comments](Comments/Readme.md)
+- [Media Upload](Media/Readme.md)
+- [Search Engine Optimization (SEO)](SEO/Readme.md)
+- [Donations](Donations/Readme.md)
+- [Advanced Features](Features/AdvancedFeatures.md) including [bookmarks, drafts, and scheduled publishing](Features/AdvancedFeatures.md#bookmarks-drafts-and-scheduled-publishing)
+- [Styling](Features/Styling.md)
+
+## Links
+
+- [Source code](https://github.com/linkdotnet/Blog)
+- [Releases](https://github.com/linkdotnet/Blog/releases)
+- [Migration guide](../MIGRATION.md)
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -0,0 +1,48 @@
+- name: Home
+  href: index.md
+- name: Setup
+  href: Setup/Readme.md
+  items:
+    - name: Configuration
+      href: Setup/Configuration.md
+    - name: Docker
+      href: Setup/Docker.md
+- name: Features
+  items:
+    - name: Advanced Features
+      href: Features/AdvancedFeatures.md
+    - name: Styling
+      href: Features/Styling.md
+    - name: Media Upload
+      href: Media/Readme.md
+    - name: SEO
+      href: SEO/Readme.md
+    - name: Donations
+      href: Donations/Readme.md
+- name: Integrations
+  items:
+    - name: Storage Provider
+      href: Storage/Readme.md
+    - name: Authorization
+      href: Authorization/Readme.md
+      items:
+        - name: Auth0
+          href: Authorization/Auth0.md
+        - name: Microsoft Entra ID
+          href: Authorization/AzureAD.md
+    - name: Comments
+      href: Comments/Readme.md
+      items:
+        - name: Giscus
+          href: Comments/Giscus.md
+        - name: Disqus
+          href: Comments/Disqus.md
+- name: Upgrading
+  href: Migrations/Readme.md
+  items:
+    - name: Upgrade Assistant
+      href: Migrations/UpgradeAssistant.md
+    - name: Migration Guide
+      href: ../MIGRATION.md
+- name: GitHub
+  href: https://github.com/linkdotnet/Blog
diff --git a/dotnet-tools.json b/dotnet-tools.json
@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.81.0",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
+    }
+  }
+}