dotnet · commonsensesoftware · Aug 6, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -0,0 +1,47 @@
+name: Deploy
+
+# REF: https://github.com/rust-lang/mdBook/wiki/Automated-Deployment%3A-GitHub-Actions
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'wiki/**'
+      - '.github/workflows/gh-pages.yml'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+
+    - name: Install Latest mdBook
+      run: |
+        tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+        url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+        mkdir mdbook
+        curl -sSL $url | tar -xz --directory=./mdbook
+        echo `pwd`/mdbook >> $GITHUB_PATH
+
+    - name: Deploy GitHub Pages
+      run: |
+        cd wiki
+        mdbook build
+        git worktree add gh-pages
+        git config user.name "GitHub Pages from CI"
+        git config user.email ""
+        cd gh-pages
+        # Delete the ref to avoid keeping history
+        git update-ref -d refs/heads/gh-pages
+        rm -rf *
+        mv ../book/* .
+        git add .
+        git commit -m "Deploy $GITHUB_SHA to gh-pages"
+        git push --force --set-upstream origin gh-pages
diff --git a/.gitignore b/.gitignore
@@ -51,4 +51,7 @@ _ReSharper*/
 # NCrunch folders and files
 _NCrunch_*/
 _NCrunch_*
-*.ncrunch*
+*.ncrunch*
+
+# mdBook generated output (built by CI; see .github/workflows/gh-pages.yml)
+wiki/book/
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-[![.NET Foundation](https://img.shields.io/badge/.NET%20Foundation-blueviolet.svg)](https://dotnetfoundation.org/projects/aspnet-api-versioning)
+[![.NET Foundation](https://img.shields.io/badge/.NET%20Foundation-blueviolet.svg)](https://dotnetfoundation.org/projects/project-detail/asp.net-api-versioning)
 [![MIT License](https://img.shields.io/github/license/dotnet/aspnet-api-versioning?color=%230b0&style=flat-square)](https://github.com/dotnet/aspnet-api-versioning/blob/main/LICENSE.txt)
 [![Build Status](https://dev.azure.com/aspnet-api-versioning/build/_apis/build/status/dotnet.aspnet-api-versioning?branchName=main)](https://dev.azure.com/aspnet-api-versioning/build/_build/latest?definitionId=1&branchName=main)
 
@@ -21,85 +21,99 @@ versioning in the past or supported API versioning with semantics that are diffe
 The supported flavors of ASP.NET are:
 
 * **ASP.NET Core**
-  <div>Adds API versioning to your ASP.NET Core <i>Minimal API</i> applications</div>
+  <div>Adds API versioning to your ASP.NET Core Minimal API applications</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.Http.svg)](https://www.nuget.org/packages/Asp.Versioning.Http)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.Http.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.Http)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/New-Services-Quick-Start#aspnet-core)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/quick-starts/new-services.html#minimal-api)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/WebApi)
 
-* **ASP.NET Core MVC**
+* **ASP.NET Core with MVC (Core)**
   <div>Adds API versioning to your ASP.NET Core MVC (Core) applications</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.Mvc.svg)](https://www.nuget.org/packages/Asp.Versioning.Mvc)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.Mvc.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.Mvc)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/New-Services-Quick-Start#aspnet-core)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/quick-starts/new-services.html#mvc-core)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/WebApi)
 
-* **ASP.NET Core and OData**
+* **ASP.NET Core with gRPC**
+  <div>Adds API versioning to your ASP.NET Core gRPC applications</div>
+
+  [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.Grpc.svg)](https://www.nuget.org/packages/Asp.Versioning.Grpc)
+  [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.Grpc.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.Grpc)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/grpc/overview.html)
+  [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/WebApi/GrpcOpenApiExample)
+
+* **ASP.NET Core with OData**
   <div>Adds API versioning to your ASP.NET Core applications using OData v4.0</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.OData.svg)](https://www.nuget.org/packages/Asp.Versioning.OData)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.OData.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.OData)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/New-Services-Quick-Start#aspnet-core-with-odata-v40)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/quick-starts/new-services.html#odata)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/OData)
 
 * **ASP.NET Web API**
-  <div>Adds API versioning to your Web API applications</div>
+  <div>Adds API versioning to your classic Web API applications</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.WebApi.svg)](https://www.nuget.org/packages/Asp.Versioning.WebApi)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.WebApi.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.WebApi)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/New-Services-Quick-Start#aspnet-web-api)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet/quick-starts/new-services.html#web-api)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNet/WebApi)
 
-* **ASP.NET Web API and OData**
-  <div>Adds API versioning to your Web API applications using OData v4.0</div>
+* **ASP.NET Web API with OData**
+  <div>Adds API versioning to your classic Web API applications using OData v4.0</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.WebApi.OData.svg)](https://www.nuget.org/packages/Asp.Versioning.WebApi.OData)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.WebApi.OData.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.WebApi.OData)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/New-Services-Quick-Start#aspnet-web-api-with-odata-v40)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet/quick-starts/new-services.html#odata)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNet/OData)
 
-This is also the home of the ASP.NET API versioning API explorers that you can use to easily document your REST APIs with OpenAPI:
-
-* **ASP.NET Core Versioned API Explorer**
-  <div>Adds additional API explorer support to your ASP.NET Core applications</div>
-
-  [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.Mvc.ApiExplorer.svg)](https://www.nuget.org/packages/Asp.Versioning.Mvc.ApiExplorer)
-  [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.Mvc.ApiExplorer.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.Mvc.ApiExplorer)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/API-Documentation#aspnet-core)
-  [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/WebApi/OpenApiSample)
+This is also the home of the ASP.NET API versioning API explorers that you can use to easily document your APIs with OpenAPI:
 
 * **ASP.NET Core Versioned OpenAPI**
   <div>Adds additional OpenAPI support to your ASP.NET Core applications</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.OpenApi.svg)](https://www.nuget.org/packages/Asp.Versioning.OpenApi)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.OpenApi.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.OpenApi)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/API-Documentation#aspnet-core)
+
+* **ASP.NET Core Versioned API Explorer and OpenAPI**
+  <div>Adds additional API explorer and OpenAPI support to your ASP.NET Core applications</div>
+
+  [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.Mvc.ApiExplorer.svg)](https://www.nuget.org/packages/Asp.Versioning.Mvc.ApiExplorer)
+  [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.Mvc.ApiExplorer.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.Mvc.ApiExplorer)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/docs/overview.html#minimal-api-or-mvc-core)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/WebApi/OpenApiSample)
 
+* **ASP.NET Core Versioned API Explorer and OpenAPI with gRPC**
+  <div>Adds API versioning to your ASP.NET Core gRPC applications</div>
+
+  [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.Grpc.ApiExplorer.svg)](https://www.nuget.org/packages/Asp.Versioning.Grpc.ApiExplorer)
+  [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.Grpc.ApiExplorer.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.Grpc.ApiExplorer)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/docs/overview.html#grpc)
+  [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/WebApi/GrpcOpenApiExample)
+
 * **ASP.NET Core with OData API Explorer**
   <div>Adds additional API explorer support to your ASP.NET Core applications using OData v4.0</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.OData.ApiExplorer.svg)](https://www.nuget.org/packages/Asp.Versioning.OData.ApiExplorer)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.OData.ApiExplorer.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.OData.ApiExplorer)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/API-Documentation#aspnet-core-with-odata)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/docs/overview.html#odata)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNetCore/OData/OpenApiODataSample)
 
 * **ASP.NET Web API Versioned API Explorer**
-  <div>Replaces the default API explorer in your Web API applications</div>
+  <div>Replaces the default API explorer in your classic Web API applications</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.WebApi.ApiExplorer.svg)](https://www.nuget.org/packages/Asp.Versioning.WebApi.ApiExplorer)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.WebApi.ApiExplorer.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.WebApi.ApiExplorer)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/API-Documentation#aspnet-web-api)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet/docs/overview.html#web-api)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNet/WebApi/OpenApiWebApiSample)
 
 * **ASP.NET Web API with OData API Explorer**
-  <div>Adds an API explorer to your Web API applications using OData v4.0</div>
+  <div>Adds an API explorer to your classic Web API applications using OData v4.0</div>
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.WebApi.OData.ApiExplorer.svg)](https://www.nuget.org/packages/Asp.Versioning.WebApi.OData.ApiExplorer)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.WebApi.OData.ApiExplorer.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.WebApi.OData.ApiExplorer)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/API-Documentation#aspnet-web-api-with-odata)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet/docs/overview.html#odata)
   [![Examples](https://img.shields.io/badge/example-code-2B91AF)](../../tree/main/examples/AspNet/OData/OpenApiODataWebApiSample)
 
 The client-side libraries make it simple to create API version-aware HTTP clients.
@@ -109,11 +123,11 @@ The client-side libraries make it simple to create API version-aware HTTP client
 
   [![NuGet Package](https://img.shields.io/nuget/v/Asp.Versioning.Http.Client.svg)](https://www.nuget.org/packages/Asp.Versioning.Http.Client)
   [![NuGet Downloads](https://img.shields.io/nuget/dt/Asp.Versioning.Http.Client.svg?color=green)](https://www.nuget.org/packages/Asp.Versioning.Http.Client)
-  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](../../wiki/API-Documentation#http-client)
+  [![Quick Start](https://img.shields.io/badge/quick-start-9B6CD1)](https://dotnet.github.io/aspnet-api-versioning/aspnet-core/ext/clients.html)
 
 ## Documentation
 
-You can find additional examples, documentation, and getting started instructions in the [wiki](../../wiki).
+You can find additional examples, documentation, and getting started instructions in the [wiki](https://dotnet.github.io/aspnet-api-versioning).
 
 ## Discussion
 

diff --git a/asp.slnx b/asp.slnx
@@ -21,6 +21,7 @@
   </Folder>
   <Folder Name="/.github/workflows/">
     <File Path=".github/workflows/codeql-analysis.yml" />
+    <File Path=".github/workflows/gh-pages.yml" />
   </Folder>
   <Folder Name="/.vscode/">
     <File Path=".vscode/extensions.json" />
@@ -96,6 +97,19 @@
   <Folder Name="/src/Abstractions/test/">
     <Project Path="src/Abstractions/test/Asp.Versioning.Abstractions.Tests/Asp.Versioning.Abstractions.Tests.csproj" />
   </Folder>
+  <Folder Name="/src/Analyzers/">
+    <File Path="src/Analyzers/Directory.Build.props" />
+  </Folder>
+  <Folder Name="/src/Analyzers/src/">
+    <File Path="src/Analyzers/src/Directory.Build.props" />
+    <File Path="src/Analyzers/src/Directory.Build.targets" />
+    <Project Path="src/Analyzers/src/Asp.Versioning.Analyzers/Asp.Versioning.Analyzers.csproj" />
+    <Project Path="src/Analyzers/src/Asp.Versioning.Api.Analyzers/Asp.Versioning.Api.Analyzers.csproj" />
+  </Folder>
+  <Folder Name="/src/Analyzers/test/">
+    <Project Path="src/Analyzers/test/Asp.Versioning.Analyzers.Tests/Asp.Versioning.Analyzers.Tests.csproj" />
+    <Project Path="src/Analyzers/test/Asp.Versioning.Api.Analyzers.Tests/Asp.Versioning.Api.Analyzers.Tests.csproj" />
+  </Folder>
   <Folder Name="/src/AspNet/" />
   <Folder Name="/src/AspNet/src/">
     <Project Path="src/AspNet/OData/src/Asp.Versioning.WebApi.OData.ApiExplorer/Asp.Versioning.WebApi.OData.ApiExplorer.csproj" />
@@ -115,6 +129,7 @@
     <Project Path="src/AspNetCore/OData/src/Asp.Versioning.OData.ApiExplorer/Asp.Versioning.OData.ApiExplorer.csproj" />
     <Project Path="src/AspNetCore/OData/src/Asp.Versioning.OData/Asp.Versioning.OData.csproj" />
     <Project Path="src/AspNetCore/WebApi/src/Asp.Versioning.Grpc.ApiExplorer/Asp.Versioning.Grpc.ApiExplorer.csproj" />
+    <Project Path="src/AspNetCore/WebApi/src/Asp.Versioning.Grpc/Asp.Versioning.Grpc.csproj" />
     <Project Path="src/AspNetCore/WebApi/src/Asp.Versioning.Http/Asp.Versioning.Http.csproj" />
     <Project Path="src/AspNetCore/WebApi/src/Asp.Versioning.Mvc.ApiExplorer/Asp.Versioning.Mvc.ApiExplorer.csproj" />
     <Project Path="src/AspNetCore/WebApi/src/Asp.Versioning.Mvc/Asp.Versioning.Mvc.csproj" />
@@ -155,4 +170,5 @@
     <Project Path="src/Common/test/Common.OData.Tests/Common.OData.Tests.shproj" />
     <Project Path="src/Common/test/Common.Tests/Common.Tests.shproj" />
   </Folder>
+  <Project Path="wiki/wiki.msbuildproj" Type="13b669be-bb05-4ddf-9536-439f39a36129" />
 </Solution>
diff --git a/build/analyzers.targets b/build/analyzers.targets
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+ <!--
+ this file is packed into every package that ships an analyzer, renamed to the package that ships it, which is the
+ name NuGet imports a package's build logic by. it is packed under 'buildTransitive' rather than 'build' because a
+ package that ships an analyzer is usually reached through another package rather than referenced directly
+
+ the analyzer cannot be turned off with ExcludeAssets="analyzers" on the package reference. the package is also
+ reached through the dependencies of other packages, and NuGet combines the assets from every path that reaches it,
+ so an exclusion on one path is undone by another that has none. the item is removed after it has been resolved
+ instead, which no path can put back
+ -->
+ <Target Name="DisableApiVersioningAnalyzers"
+         BeforeTargets="CoreCompile"
+         Condition=" '$(EnableApiVersioningAnalyzers)' == 'false' ">
+
+  <!--
+  a target name cannot be composed from the package this file was renamed to, so a project that reaches more than one
+  package defines this target more than once and only the last one imported survives. every analyzer this product
+  ships is removed rather than only the one this package ships, so that the surviving target does the same work as
+  all of them together. the package a resolved analyzer came from is the only way to tell them apart, because the
+  compiler is handed a path into the package cache rather than anything naming the package
+  -->
+  <ItemGroup>
+   <Analyzer Remove="@(Analyzer)"
+             Condition=" '%(Analyzer.NuGetPackageId)' != '' and
+                         $([System.String]::Copy('%(Analyzer.NuGetPackageId)').StartsWith('Asp.Versioning')) " />
+  </ItemGroup>
+
+ </Target>
+
+</Project>