APTrust Documentation

Unified documentation site for APTrust, combining four previously separate doc repos into a single site using mkdocs-monorepo-plugin.

Live site: https://docs.aptrust.org

---

What's in this repo

This repo contains only the scaffolding for the unified site. It does not contain the actual documentation content — that lives in the four source repos below.

Tab	Source repo	URL path
User Guide	APTrust/userguide	/user-guide/
DART	APTrust/dart-docs	/dart-docs/
Preservation Services	APTrust/preserv-docs	/preservation-services-docs/
Registry	APTrust/registry-docs	/registry-docs/

One tab is a direct content page that lives in docs/ in this repo:

Tab	File	Notes
API	docs/api.md	Embeds the Member API v3 OpenAPI spec via Swagger UI (mkdocs-swagger-ui-tag)

Two additional tabs are bridge pages — they live in docs/ in this repo and link out to content on the APTrust website:

Tab	File	Links to
Other Documentation	docs/documentation.md	https://aptrust.org/documentation/
Policies	docs/policies.md	https://aptrust.org/resources/policies/

Files in this repo:

mkdocs.yml          # Root MkDocs config — theme, plugins, nav with !include entries
requirements.txt    # Python dependencies for building the site
docs/
├── index.md              # Landing page
├── api.md                # Member API v3 interactive reference (Swagger UI)
├── member_api_v3.yml     # OpenAPI spec — auto-refreshed from registry repo on every build, synced nightly
├── documentation.md      # Bridge page → aptrust.org/documentation/
├── policies.md           # Bridge page → aptrust.org/resources/policies/
└── stylesheets/
    └── extra.css         # Search result site-label badges, external link indicators
overrides/
├── main.html             # Theme extension — Matomo analytics, WCAG 2.2 AA patches
└── partials/             # Overridden template partials (forked from mkdocs-material)
tools/
└── a11y-check/           # Accessibility regression check — see its README
.github/
└── workflows/
    └── build-and-deploy.yml

How the build works

At build time, each sub-repo is cloned into repos/ at the project root. The mkdocs-monorepo-plugin reads each sub-repo's mkdocs.yml to get its navigation tree, then merges all four into a single site. Sub-repos live in repos/ rather than docs/ so MkDocs's own file scanner doesn't pick them up as a second copy of the content.

The monorepo plugin reads only nav and docs_dir from a sub-repo's config — it never runs that sub-repo's plugins: block. Anything a sub-repo declares there has to be re-declared in this repo's mkdocs.yml instead, rewritten against the merged tree (so paths carry the sub-repo's URL prefix). The redirects entries for /user-guide/bagging/ are the current example.

repos/               ← created at build time, not committed
├── preserv/         ← clone of APTrust/preserv-docs
├── registry/        ← clone of APTrust/registry-docs
├── dart/            ← clone of APTrust/dart-docs
└── userguide/       ← clone of APTrust/userguide

Automatic deploys

The build-and-deploy workflow runs on four triggers:

1. Push to main in this repo — for changes to the landing page, bridge pages, mkdocs.yml, or requirements.txt.

2. Push to master in any sub-repo — each sub-repo has a .github/workflows/notify-parent-docs.yml that sends a repository_dispatch event here when content changes. This requires a secret named DOCS_DISPATCH_TOKEN in each sub-repo: a fine-grained PAT with Contents: Read and write permission on this repo (APTrust/aptrust-docs).

3. Manual run — from the Actions tab → Build and Deploy Documentation → Run workflow.

4. Nightly at 07:00 UTC (3:00 AM EDT / 2:00 AM EST) — picks up changes to the Member API OpenAPI spec, which lives in APTrust/registry and sends no dispatch event here. The nightly run also commits the refreshed spec back to main when it has changed upstream. Note that GitHub disables scheduled workflows after 60 days of no commit activity in a repo; if that happens, re-enable it from the Actions tab.

The workflow clones the four sub-repos, runs mkdocs build, and deploys the output to the gh-pages branch via peaceiris/actions-gh-pages. GitHub Pages serves from that branch.

docs.aptrust.org is then proxied through Cloudflare, which terminates TLS in front of GitHub Pages. Two consequences worth knowing:

• GitHub Pages' Enforce HTTPS setting cannot be turned on for this site — GitHub can't validate a certificate for a hostname it doesn't answer for directly, and the API returns The certificate does not exist yet.
• The http → https redirect is a Cloudflare Single Redirect rule (Rules → Redirect Rules), scoped to http://docs.aptrust.org/* so the rest of the aptrust.org zone is unaffected. It isn't configured anywhere in this repo, so that's where to look if http ever stops redirecting.

Building locally

pip install -r requirements.txt

# Clone the sub-repos into repos/
git clone --depth 1 https://github.com/APTrust/preserv-docs  repos/preserv
git clone --depth 1 https://github.com/APTrust/registry-docs  repos/registry
git clone --depth 1 https://github.com/APTrust/dart-docs      repos/dart
git clone --depth 1 https://github.com/APTrust/userguide      repos/userguide

mkdocs serve     # live preview at http://127.0.0.1:8000
mkdocs build     # write static site to ./site/

Note: mkdocs serve does not watch overrides/. If you edit a template there, touch a file under docs/ or restart the server to see the change.

Accessibility

The site is audited externally against WCAG 2.2 AA. The sidebar and header chrome are rendered by forked Material partials in overrides/partials/ so that visual headings are real heading elements and controls are real buttons — Material's stock templates build both out of <label> + hidden-checkbox pairs, which announce to screen readers as unnamed "clickable" elements.

Because those partials are forks, requirements.txt pins mkdocs-material to the exact version they were taken from. Re-diff them against the installed theme before bumping it; each file's header comment carries the upstream checksum.

Before shipping a change that touches the header, sidebar, or overrides/, run:

cd tools/a11y-check && npm run a11y

It sweeps 7 pages at 4 viewport states (including the mobile drawer open at 320px, the width WCAG 1.4.10 Reflow names) with axe-core plus assertions read from Chrome's real accessibility tree, and writes an evidence pack to report/. See tools/a11y-check/README.md, and the Accessibility section of CLAUDE.md for the design rationale and the manual VoiceOver checklist that automation cannot replace.

Adding a sub-repo

1. Add an !include entry to the nav: block in mkdocs.yml.
2. Add a matching git clone line to the Clone step in .github/workflows/build-and-deploy.yml.
3. Add notify-parent-docs.yml to the new sub-repo and configure DOCS_DISPATCH_TOKEN in its secrets.
4. Add a badge selector to docs/stylesheets/extra.css so search results show the section label.

Adding a Swagger/API page

1. Copy the OpenAPI spec file into docs/ (serving it locally avoids cross-origin fetch errors).
2. Add the markdown file in docs/ using the <swagger-ui src="../your-spec.yml"/> tag.
3. Add it to the nav: block in mkdocs.yml.
4. The mkdocs-swagger-ui-tag plugin (already in requirements.txt) handles the rest.
5. If the spec is hosted in another repo, add a curl step to the build workflow (see Step 4 in build-and-deploy.yml) to pull the latest version on every build.

The member_api_v3.yml spec is refreshed automatically on every build — no manual update needed. The copy committed in docs/ is only used when running mkdocs serve locally without internet access, and the nightly run commits an updated copy back to main whenever the spec changes upstream, so it stays current rather than drifting. Don't hand-edit that file: the next build overwrites it.

Adding a bridge page

1. Create a markdown file in docs/ describing the external content and linking to it.
2. Add it to the nav: block in mkdocs.yml.

Known issues

• Internal absolute links: preserv-docs and registry-docs contain links written as root-relative paths (e.g., /workers/ingest/bucket-reader) that worked on their standalone sites but don't resolve correctly in the unified site. These need to be fixed in the source repos.
• URL namespaces: The monorepo plugin derives URL path prefixes from each sub-repo's site_name. To change the URL prefix, change site_name in the sub-repo's mkdocs.yml, then update the matching href*= selector in docs/stylesheets/extra.css.
• Bridge page content drift: The descriptions in documentation.md and policies.md are static and will need occasional manual updates if APTrust.org reorganises those pages.