Docs Maintenance

This page defines coverage expectations for audience-oriented documentation.

Publication

The public documentation lives at https://docs.bucketreef.ksperis.com/. Sources remain in this repository. GitLab CI builds MkDocs with Python 3.11 and complete Git history (GIT_DEPTH: 0), checks screenshot references, and publishes doc/site/ to the bucketreef-docs Cloudflare Pages Direct Upload project. Other branches and merge requests only validate. The separate product website lives at https://bucketreef.ksperis.com/.

Publication runs for documentation or deployment changes pushed to protected main, or a pipeline started manually on main. Documentation jobs have their own validation dependencies; container image publishing remains separate. Site artifacts are retained for 30 days and the commit SHA is sent to Cloudflare. Record the Cloudflare deployment ID alongside each published revision.

Configure protected CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN variables in GitLab, scoped to docs-production. Mask and hide the token, disable variable expansion, and restrict it to Cloudflare Pages Edit on the deployment account. Never commit or print credentials. Wrangler is locked in ops/cloudflare/.

Create the Pages project with production branch main. Associate the custom domain in Cloudflare before configuring the docs.bucketreef CNAME at Gandi, using the actual Pages hostname and TTL 300. Gandi remains the DNS provider. Check certificate activation for the complete hostname, including the nested docs subdomain. GitHub Pages publication is retired.

Deployments are serialized and refuse commits that are no longer the tip of main. Keep GitLab's Prevent outdated deployment jobs setting enabled. For immediate recovery, restore a previously successful production deployment in Cloudflare Pages, then commit the equivalent source revert before the next pipeline. A normal git revert and deployment is the preferred lasting rollback; no DNS change is needed.

Coverage matrix (routes/features)

Route / Feature	Target doc page	Status
First-run user orientation and workspace selection	user/start-here.md	Covered
Workspace profile routes (/*/profile)	user/profile.md	Covered
User/admin task journeys	user/common-tasks-storage-user.md + user/common-tasks-storage-admin.md	Covered
Storage admin rollout and handover journey	user/admin-runbook-storage-admin.md	Covered
Feature visibility and missing actions	user/feature-availability.md + user/troubleshooting.md	Covered
Product vocabulary and search terms	user/glossary.md	Covered
/admin dashboard and admin nav	user/workspace-admin.md	Covered
/admin/s3-accounts	user/workspace-admin.md	Covered
/admin/s3-users + keys page	user/workspace-admin.md	Covered
/admin/s3-connections	user/workspace-admin.md	Covered
/admin/storage-endpoints	user/workspace-admin.md + ops/configuration.md	Covered
/admin/endpoint-status	user/feature-endpoint-status-admin.md + ops/operations-healthchecks.md	Covered
/admin/audit	user/workspace-admin.md + ops/operations-observability.md	Covered
/admin/metrics	user/feature-admin-metrics.md + ops/operations-observability.md	Covered
/admin/billing	user/feature-billing-admin.md + ops/operations-billing.md	Covered
/admin/usage-history	user/feature-usage-history-admin.md + ops/operations-quota-monitoring.md	Covered
API tokens (profile page tab and admin route)	ops/operations-api-tokens.md	Covered
/admin/*-settings	ops/configuration.md	Covered
/admin/key-rotation	user/feature-key-rotation-admin.md + ops/operations-security.md	Covered
/ceph-admin and children	user/workspace-ceph-admin.md	Covered
/ceph-admin/buckets advanced drawer	user/howto-ceph-advanced-filter.md	Covered
/ceph-admin/buckets UI tags operations	user/howto-ceph-ui-tags.md	Covered
/storage-ops and children	user/workspace-storage-ops.md	Covered
/storage-ops/buckets UI tags operations	user/howto-storage-ops-ui-tags.md	Covered
/manager dashboard/nav	user/workspace-manager.md	Covered
/manager/buckets and detail	user/feature-buckets.md	Covered
/manager/buckets/:bucket configuration flow	user/howto-manager-bucket-configuration.md	Covered
/manager/browser	user/feature-objects-browser.md	Covered
/manager/users|groups|roles|iam/policies	user/feature-iam.md	Covered
/manager/ceph/keys	user/feature-manager-ceph-keys.md	Covered
/manager/topics	user/feature-topics.md	Covered
/manager/feature-rules	user/feature-buckets.md + developer/listings-feature-matrix.md	Covered
/manager/bucket-compare	user/feature-bucket-compare.md	Covered
/manager/bucket-integrity	user/feature-bucket-integrity-check.md	Covered
/manager/bucket-purge, /ceph-admin/buckets purge action, /storage-ops/buckets purge action	user/feature-bucket-purge.md	Covered
/manager/metrics, /ceph-admin/metrics, and bucket usage stats tabs/actions	user/feature-bucket-usage-stats.md	Covered
/manager/migrations*	user/feature-bucket-migration.md	Covered
/portal and children	user/workspace-portal.md + Portal task pages	Covered
/portal/storage-spaces*	user/portal-storage-spaces.md + user/portal-files.md	Covered
/portal/shares* and public-link/collaboration concepts	user/portal-sharing.md	Covered
/portal/access-keys	user/portal-access-keys.md	Covered
/portal/usage and Portal alerts	user/portal-usage-alerts.md	Covered
/portal/history governance activity and access-log views	user/portal-activity.md	Covered
/admin/audit control-plane and security audit	user/admin-audit.md + developer/audit-boundary.md	Covered
/portal/settings	user/portal-settings.md	Covered
/browser	user/workspace-browser.md + user/feature-objects-browser.md	Covered
/browser object versions modal	user/feature-object-versions-browser.md	Covered
Feature flags in app settings	ops/configuration.md + user pages limits blocks	Covered
Destructive and bulk operation safety	user/safe-destructive-operations.md + tool pages	Covered
Production readiness and recovery	ops/production-readiness.md + ops/backup-restore.md	Covered
First contribution path	developer/first-contribution.md + developer/contributing.md	Covered

Maintenance rule

When adding or changing routes/features:

1. Update user-facing page in doc/docs/user/.
2. Update ops/developer pages when runtime behavior or architecture changed.
3. Keep this matrix in sync with frontend/src/router.tsx and workspace layouts.
4. Run the strict docs build and screenshot reference check before publishing:

python3 -m mkdocs build --strict --config-file doc/mkdocs.yml --site-dir /tmp/bucketreef-docs-build
npm --prefix frontend run docs:screenshots:check

Visual theme maintenance

The documentation uses a classic reading layout with a white article, a light gray navigation panel, and restrained BucketReef blue accents. Its density and neutral surfaces are independent of the application workspace theme.

1. Use the shared --docs-* tokens in doc/docs/assets/stylesheets/docs-theme.css for the theme and screenshot controls. Keep both the default and slate palettes coherent.
2. Keep Arial/Helvetica system fonts without remote font requests, 16px body text with 24px line height, 32/24/20px headings, and 14px navigation at the standard browser font size. Use regular text and restrained heading weights.
3. Keep desktop navigation at 288px, the right table of contents at 208px, and the overall layout at most 1440px. Preserve Material's mobile drawers, nested navigation, search, and anchor behavior.
4. Use subtle borders, 4px corner radii, and no decorative shadows. Preserve semantic callout colors and visible keyboard focus. Wide tables and code scroll within their own regions instead of scrolling the whole article.
5. After a theme change, compare Home, Start Here, Configuration, Quickstart, and the screenshot gallery at 1440, 1280, 768, and 390px. Check both themes, contrast, search results, instant navigation, anchors, mobile menus, and keyboard opening/closing of screenshots. Fix visible defects and repeat affected checks before committing.

Material stores data-md-color-scheme on body. Both screenshot CSS and the gallery observer must read that same element so inline images, thumbnails, and the fullscreen viewer use the selected light/dark variant.

Run the strict build and screenshot reference check above. Keep temporary browser captures and reports outside the repository; a docs-only theme change does not require regenerating the application screenshots.

User screenshot workflow

User pages in doc/docs/user/*.md normally include exactly one themed screenshot block:

<div class="docs-themed-shot" data-docs-themed-shot>
  <img class="docs-themed-shot__image docs-themed-shot__image--light" data-docs-shot-variant="light" src="../../assets/screenshots/user/<page-screenshot>.light.png" alt="..." loading="lazy">
  <img class="docs-themed-shot__image docs-themed-shot__image--dark" data-docs-shot-variant="dark" src="../../assets/screenshots/user/<page-screenshot>.dark.png" alt="..." loading="lazy">
</div>

Use ../../assets/... for published user pages under /user/<slug>/. Only doc/docs/user/index.md stays on ../assets/... because it renders at /user/.

Published docs automatically enhance screenshots under assets/screenshots/ so a click opens them in a fullscreen viewer.

Exception:

• user/screenshots-gallery.md is a curated gallery page and may include multiple themed screenshot blocks inside HTML <figure> tags.

Most screenshots are generated with synthetic/mock data using Playwright:

npm --prefix frontend run docs:screenshots

The generator writes both variants for each logical screenshot:

• basename.light.png
• basename.dark.png

Validate references and dimensions (1728x972 for both variants) before merging:

npm --prefix frontend run docs:screenshots:check

If you add a new standard user page:

1. Add a scenario in frontend/scripts/docs-screenshots/scenarios.ts with route, storage seed, mocks, and output basename.
2. Generate screenshots.
3. Add one themed screenshot block to the new markdown page.
4. Run the screenshot check script.

If a new task page reuses an existing validated screenshot, document why that screenshot is the best visual anchor and still run the screenshot check script.

If you update the gallery page:

1. Add or update the required screenshot scenarios in frontend/scripts/docs-screenshots/scenarios.ts.
2. Generate screenshots.
3. Reference the curated screenshots from user/screenshots-gallery.md using themed screenshot blocks.
4. Run the screenshot check script.

Portal screenshot note:

• workspace-portal follows the same .light.png / .dark.png convention as other active workspace screenshots.