Repository navigation
Docs site: publish docs/ to GitHub Pages, one build per line, the stable line by default #417
Description
Problem
The consumer docs can only be read as Markdown on GitHub, and there are three problems with that:
- Wrong line by default. GitHub shows
main, which is the 11 preview line, whiledotnet add packageinstalls 10.x. Someone evaluating the library reads docs for a line they don't have. - Two audiences mixed.
docs/holds consumer guides (getting-started,why,ranges,value-sets,efcore,serialization,migration) next to contributor ones (architecture,testing,oracles,discard-triage), with no navigation that separates them. - No way in. There's no table of contents and no search across the guides, which run to about 6,000 lines.
A GitHub wiki is ruled out. It's a separate repository whose edits bypass PRs, so claims.json couldn't hold its sentences, and GitHub doesn't index the wikis of repositories with fewer than 500 stars.
Change
- Build from
docs/*.mdas they are. A workflow publishes them to GitHub Pages without copying or transforming the source, soOracleCatalogueTestskeeps holding the same text. Navigation comes from the site's config, not from splitting or merging pages. If a page has to change for the site, its claims follow in the same PR. - One build per supported line.
release/10.xandmaineach publish their own docs. The stable line is the default URL, and 11.x is labelled preview untilv11.0.0, when the default moves. Both are built by one workflow withmain's config. A push torelease/10.xpublishes throughworkflow_runon the .NET workflow, so that branch needs no copy ofsite/or the workflow, and nothing is cherry-picked. - Separate the audiences. Consumer guides form the main navigation; the contributor pages go under a "Contributing" section, or stay on GitHub only.
- Repository links. The docs link to
README.md,CHANGELOG.md, the package READMEs,CONTRIBUTING.mdand contributor pages. Those files become pages, and whatever is left is rewritten to a GitHub URL on the build's branch, never by editing the sources. - README. Links to the site and stays the GitHub landing page.
- Tool: DocFX (decided by the spike in the comments). It reads the API from the published assemblies, and the root README, the package READMEs, the changelog and the contributor docs become pages too, so the docs' relative links resolve without rewriting.
Done when
- The site serves 10.x by default and 11.x under its own path, each rebuilt by CI on a push to its branch.
- Every consumer page is reachable from the navigation, and no link is broken: a link check runs in the publish job.
- CONTRIBUTING.md says how the docs are published, and the release steps cover moving the default at
v11.0.0.
Activity
CaffeinatedCoder commentedon Oct 25, 2026
Spike result: DocFX 2.81.0
I ran it locally on
main(c0c95ee) with the RC2 SDK, against the seven consumer guides and the four package assemblies.It builds: 0 errors, 201 API pages, about 107 s. Tables, code blocks, the in-page outline and search all render. The API pages list extension methods on the type they extend (for example
DateRangeshows everyRangeExtensionsmember), and no extension blocks exist insrc/, so C# 14 isn't a concern.Read the API from published DLLs, not from the csproj files. One
dotnet publishofCodoMetis.ValueRanges.EFCore.PostgreSQL.NodaTimeyields all four assemblies, their XML docs and their dependencies. Pointing DocFX at a plainbinfolder can't resolve EF Core, Npgsql or NodaTime, and pointing it at a csproj makes DocFX load the preview SDK through MSBuild itself.The config has to sit in the repo. DocFX rejects a content source outside its base directory unless the path is relative, so it goes in
site/docfx.jsonwith../docs.18 broken-link warnings, all pointing outside the consumer set:
../README.md(7),architecture.md(4),../CHANGELOG.md(2), the NodaTime package README (2),CONTRIBUTING.mdand a skill file. All of them disappear if those files become site pages too, with no rewriting: the root README as the landing page, the package READMEs, the changelog, and the contributor docs under "Contributing". Anything left over is rewritten to a GitHub URL on the build's branch.No tool has a version switcher worth adopting.
With two lines, subdirectories are enough:
/10.x/and/11.x/, a root page that redirects to/10.x/untilv11.0.0, and a link in the header to the other line.Decided
.config/dotnet-tools.json.release/10.xwith its ownglobal.json(10.0.100) andmainwith RC2, each published and run through DocFX. It assembles/10.x/and/11.x/and deploys withactions/deploy-pages. It's triggered by a push to either branch (the workflow file exists on both) and checks out both refs, so every run produces the whole site.--warningsAsErrors.docs: publish the docs on GitHub Pages, one build per line (#417) (#419)