docs(infra): set up DocFX site with multi-version GitHub Pages deployment by Pomdapis · Pull Request #17 · sassy-solutions/compendium

Pomdapis · 2026-04-25T08:06:24Z

Summary

Stands up the documentation infrastructure for Compendium. Closes POM-180.

DocFX at docs/ consuming all src/**/*.csproj (excluding Compendium.Adapters.Shared per its IsPackable=false status).
GitHub Pages workflow (docs-deploy.yml) that builds on push main and on release published, publishing to a gh-pages branch with versioned subdirectories:
- gh-pages/main/ — preview from main
- gh-pages/v<MAJOR>.<MINOR>/ — release versions
- gh-pages/latest/ — alias of newest release
- gh-pages/versions.json — manifest for any future version switcher
- gh-pages/index.html — root redirect (latest > main fallback)
Skeleton content (placeholders) for Concepts (4 pages), Adapters (8 pages), Getting Started — the actual content lands in POM-182, POM-183, POM-184.
ADR navigation (docs/adr/toc.yml) wires up the 5 ADRs already merged via POM-185.
Roadmap page placeholder; the workflow inlines ROADMAP.md automatically when present (works after POM-181 merges).

Validation

DocFX build verified locally with docfx 2.78.5:

Build succeeded with warning.
    1 warning(s)
    0 error(s)

The remaining warning is on the ADR template's placeholder [####](####.md) link from POM-185 — intentional template syntax.

API reference is generated from the existing XML docs (<GenerateDocumentationFile>true</GenerateDocumentationFile> from Directory.Build.props).

Post-merge actions

The Deploy Docs workflow runs on push to main → creates gh-pages branch on first run.

GitHub Pages must be activated on the gh-pages branch:

gh api repos/sassy-solutions/compendium/pages \
  -X POST \
  -f 'source[branch]=gh-pages' \
  -f 'source[path]=/'

Or via Settings → Pages UI.

Site will be available at https://sassy-solutions.github.io/compendium/main/ (with root redirect from https://sassy-solutions.github.io/compendium/).

Test plan

docfx metadata docs/docfx.json succeeds locally
docfx build docs/docfx.json succeeds locally (0 errors)
All API namespaces appear under _site/api/
All TOCs (root, concepts, adapters, adr) link correctly
Workflow runs green on push to main
Pages activated and https://sassy-solutions.github.io/compendium/main/ returns 200

Notes

Permissions kept minimal (contents: write only — no pages:write since we publish via the gh-pages branch, not via actions/deploy-pages).
Concurrency: cancel-in-progress: false so two simultaneous deploys queue rather than collide.
The 7 existing OpenTelemetry vulnerability warnings on integration/load test projects are unrelated to this PR (Dependabot PR Bump the opentelemetry group with 7 updates #10 already opens fixes).

…ment (POM-180) - Adds docs/ directory with DocFX configuration consuming all src/**/*.csproj - Adds skeleton placeholders for Concepts (4), Adapters (8), Getting Started, Roadmap - Adds top-level navigation toc.yml and ADR navigation toc.yml - Adds docs-deploy.yml workflow that builds on push main / release tag and publishes to gh-pages with versioned subdirectories (main/, vX.Y/, latest/), versions.json manifest, and a top-level redirect index.html - Permissions block scoped to contents:write only DocFX build verified locally: 0 errors. The single remaining warning is on the ADR template's placeholder [####](####.md) link, intentional. Site will be served at https://sassy-solutions.github.io/compendium/ once the workflow runs and Pages is activated on the gh-pages branch.

Copilot

Pull request overview

Sets up the initial DocFX documentation site for Compendium and automates multi-version publishing to GitHub Pages (preview from main, versioned releases, and a latest alias).

Changes:

Added DocFX configuration and skeleton docs structure (home, getting started, concepts, adapters, ADRs, roadmap, API ref entry points).
Introduced a GitHub Actions workflow to build DocFX docs and publish them to gh-pages under versioned subdirectories.
Wired navigation TOCs for the main docs area, concepts, adapters, and ADRs.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/toc.yml	Root navigation for the documentation site
docs/roadmap.md	Roadmap placeholder page (optionally inlined from root `ROADMAP.md` during CI)
docs/index.md	Landing page content for the docs site
docs/images/.gitkeep	Ensures `docs/images/` exists in the repo
docs/getting-started.md	Getting started placeholder page
docs/docfx.json	DocFX metadata + build configuration for site and API docs
docs/concepts/toc.yml	Concepts section navigation
docs/concepts/result-pattern.md	Concepts placeholder page
docs/concepts/multi-tenancy.md	Concepts placeholder page
docs/concepts/hexagonal-architecture.md	Concepts placeholder page
docs/concepts/event-sourcing.md	Concepts placeholder page
docs/adr/toc.yml	ADR section navigation wiring existing ADRs
docs/adapters/zitadel.md	Adapter placeholder page
docs/adapters/toc.yml	Adapters section navigation
docs/adapters/stripe.md	Adapter placeholder page
docs/adapters/redis.md	Adapter placeholder page
docs/adapters/postgresql.md	Adapter placeholder page
docs/adapters/openrouter.md	Adapter placeholder page
docs/adapters/listmonk.md	Adapter placeholder page
docs/adapters/lemonsqueezy.md	Adapter placeholder page
docs/adapters/aspnetcore.md	Adapter placeholder page
docs/.gitignore	Ignores generated DocFX outputs (`_site`, `api`, `obj`, etc.)
.github/workflows/docs-deploy.yml	Builds DocFX docs and deploys to `gh-pages` with `main/`, `vX.Y/`, `latest/`, and manifest/redirect files

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-25T08:09:51Z

+          "src": "../src",
+          "exclude": ["**/Compendium.Adapters.Shared.csproj"]


exclude removes Compendium.Adapters.Shared.csproj from API metadata generation, but that project currently does not opt out of packing (no <IsPackable>false</IsPackable>), so it looks like a public package that will end up undocumented. Either include it in DocFX metadata, or explicitly mark the project as non-packable/internal so the exclusion matches the project intent.

Suggested change

"src": "../src",

"exclude": ["**/Compendium.Adapters.Shared.csproj"]

"src": "../src"

Copilot · 2026-04-25T08:09:51Z

+      "_appLogoPath": "images/logo.svg",
+      "_appFaviconPath": "images/favicon.ico",


_appLogoPath/_appFaviconPath point to images/logo.svg and images/favicon.ico, but docs/images/ currently only contains .gitkeep. This will produce broken assets in the generated site (and may cause template warnings). Add the referenced files (even placeholders) or remove/adjust these metadata values.

Suggested change

"_appLogoPath": "images/logo.svg",

"_appFaviconPath": "images/favicon.ico",

Copilot · 2026-04-25T08:09:51Z

+    "disableGitFeatures": false,
+    "sitemap": {
+      "baseUrl": "https://sassy-solutions.github.io/compendium/",
+      "priority": 0.5,
+      "changefreq": "weekly"
+    }


DocFX sitemap baseUrl is set to https://sassy-solutions.github.io/compendium/, but this workflow deploys the site under versioned subpaths like /main/ and /vX.Y/. As a result, generated sitemap URLs will not match the actual published URLs. Consider setting baseUrl dynamically per deploy target (e.g., replace during workflow) or disabling sitemap generation until a per-version base URL is supported.

Suggested change

"disableGitFeatures": false,

"sitemap": {

"baseUrl": "https://sassy-solutions.github.io/compendium/",

"priority": 0.5,

"changefreq": "weekly"

}

"disableGitFeatures": false

Copilot · 2026-04-25T08:09:51Z

+        run: dotnet restore Compendium.sln
+
+      - name: Install DocFX
+        run: dotnet tool install -g docfx


The workflow installs DocFX without pinning a version. Since the PR was validated against DocFX 2.78.5, using whatever the current latest tool is can introduce unexpected build breaks or output changes. Pin the tool version (e.g., dotnet tool install -g docfx --version <tested-version>) to make deployments reproducible.

Suggested change

run: dotnet tool install -g docfx

run: dotnet tool install -g docfx --version 2.78.5

## Summary PR #23 incorrectly bumped CHANGELOG to `[1.0.0-preview.2] - 2026-04-26` with the quality-sweep entries — but tag `v1.0.0-preview.2` was already cut on **2026-04-25** from a different commit set (PRs #1-7) and **already published to nuget.org** (`Compendium.Core 1.0.0-preview.2` is live). Reusing that version was a mistake. This PR reconciles the CHANGELOG with the published reality and rolls today's work into a new **preview.3**: ### `[1.0.0-preview.2] - 2026-04-25` — rewritten retroactively Now matches the auto-generated GitHub release notes for `v1.0.0-preview.2`: - **Added** — `Compendium.Adapters.Shared` (PII masking utilities, introduced in #3). - **Changed** — Dependabot bumps #4-7, OSS governance scaffolding. - **Security** — workflow `permissions:` block (#1), tenant log sanitization (#2), email removal from adapter logs / GDPR (#3). ### `[1.0.0-preview.3] - 2026-04-26` — new Everything since `v1.0.0-preview.2`: - **Added** — DocFX site (#17), 5 ADRs (#14), public ROADMAP (#15), getting-started guide (#20), 4 concept pages (#21), 8 adapter how-to guides (#22). - **Changed** — CodeQL Default Setup → `extended` query suite. - **Security** — `softprops/action-gh-release` pinned to commit SHA (#16, alert #28 closed). ## Test plan - [ ] CI green on this PR. - [ ] After merge, tag `v1.0.0-preview.3` triggers Release workflow successfully. - [ ] `Compendium.* @ 1.0.0-preview.3` published on nuget.org. - [ ] GitHub Release `v1.0.0-preview.3` created with auto-generated notes. VK: POM-186 (Code Quality sweep parent). Co-authored-by: sacha <sacha@scojhconsult.com>

Copilot AI review requested due to automatic review settings April 25, 2026 08:06

Copilot started reviewing on behalf of Pomdapis April 25, 2026 08:06 View session

Pomdapis merged commit fe1ab5b into main Apr 25, 2026
8 checks passed

Pomdapis deleted the pom-180-docs-docfx branch April 25, 2026 08:09

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Pomdapis mentioned this pull request Apr 26, 2026

docs(changelog): correct preview.2 retroactively + cut preview.3 #24

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(infra): set up DocFX site with multi-version GitHub Pages deployment#17

docs(infra): set up DocFX site with multi-version GitHub Pages deployment#17
Pomdapis merged 1 commit intomainfrom
pom-180-docs-docfx

Pomdapis commented Apr 25, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		"src": "../src",
		"exclude": ["**/Compendium.Adapters.Shared.csproj"]

	"src": "../src",
	"exclude": ["**/Compendium.Adapters.Shared.csproj"]
	"src": "../src"

		"_appLogoPath": "images/logo.svg",
		"_appFaviconPath": "images/favicon.ico",

	run: dotnet tool install -g docfx
	run: dotnet tool install -g docfx --version 2.78.5

Conversation

Pomdapis commented Apr 25, 2026

Summary

Validation

Post-merge actions

Test plan

Notes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants