Documentation platforms standard

Standard scope

Applies to: All HCS-governed repositories that publish a browsable documentation site Domain: docs-platforms Status: Active

This standard defines which static-site generators are sanctioned for HCS-governed repositories, when to use each one, and where a repo's choice is recorded. It complements documentation.md, which covers platform-agnostic Markdown, diagram, and commit conventions that apply regardless of generator.

---

Why this file exists

HCS previously stated a single rule: use MkDocs Material, and "do not use Docusaurus unless there is a compelling reason approved by Kris." That rule no longer reflects reality. An audit of the estate found five documentation frameworks in active, working use across HCS-governed and HCS-adjacent repositories: MkDocs Material, Docusaurus, Hugo, Jekyll, and plain hand-written HTML (or no generator at all).

The old "no Docusaurus" prohibition is retired. Docusaurus remains load-bearing for the TierPoint official documentation portal and the AzureLocal community portal. TierPoint's wider documentation estate now uses a mixed, purpose-based framework policy defined by its private scope overlay. This document records the base policy and delegates the internal assignment matrix to that overlay.

VitePress has two explicit assignments: the platform repo itself and documentation sites in the private tierpoint-prodtech scope. This does not change the HCS-wide MkDocs Material default outside those assignments. See VitePress below.

---

Sanctioned generators

MkDocs Material — HCS default

Use MkDocs Material for any new repository unless the repo falls into one of the scoped exceptions below.

• Reference implementation: azurelocal-ranger (org: azure-local-cloud)
• mkdocs.yml at the repo root, docs/ folder with index.md as the landing page
• Dark mode toggle enabled, search plugin enabled, navigation tabs for top-level sections
• mike for versioned documentation when the project has public releases and is hosted on GitHub Pages (most of the AzureLocal org). mike works by committing each version's build to a persistent branch (conventionally gh-pages) with a versions.json tracking what exists — it is built around that branch-based hosting model. It does not drop cleanly into this repo's own ADO + Azure Static Web Apps pipeline (.ado/docs-deploy.yml: mkdocs build --strict → deploy the build output as a stateless artifact) without custom branch-management plumbing. For a repo on that pipeline, prefer Docusaurus if you genuinely need built-in versioning — its docusaurus docs:version bakes every version into the single build output tree, which composes with an artifact-deploy pipeline with no extra work.

This is also the default across the AzureLocal org — 25 of its repositories use MkDocs Material, including the AzureLocal platform repo itself.

Docusaurus — sanctioned for specific portals

Docusaurus is sanctioned, not merely tolerated, for these portals:

1. TierPoint Product Technology official documentation portal — the canonical portal remains Docusaurus because it uses .mdx, independent product versioning, required frontmatter, and MDX components. Other TierPoint documentation sites default to VitePress under the private tierpoint-prodtech overlay; interactive portals and configuration builders retain their application framework.
2. AzureLocal community portal (azurelocal.github.io) — the AzureLocal org's public-facing standards portal is Docusaurus 3.9, confirmed via docusaurus.config.js and the @docusaurus/core dependency. This is a deliberate choice distinct from the org's internal MkDocs default: the community portal serves a different audience (external contributors) and needed Docusaurus's versioning and community-doc features.

New repositories outside the explicitly sanctioned portals should follow their scope default. For tierpoint-prodtech, that means VitePress for documentation sites and the existing application framework for interactive applications. Other scopes continue to default to MkDocs Material unless their overlay says otherwise.

VitePress — sanctioned for Platform and TierPoint documentation sites

VitePress is sanctioned for platform (this repo), serving platform.hybridsolutions.cloud, and as the default documentation framework in the private tierpoint-prodtech scope. It is not a general-purpose replacement for MkDocs Material in other HCS or AzureLocal repositories.

The Platform exception remains intentionally narrow outside TierPoint. This repo is the reference implementation and authoring surface for every standard in this document and publishes through ADO to Azure Static Web Apps. TierPoint independently standardized on VitePress for lightweight documentation sites that share a protected Azure Static Web Apps routing and authentication layer.

What's different in this repo's docs/ tree versus the MkDocs default:

• docs/.vitepress/config.mts replaces mkdocs.yml — nav, sidebar, and search (local provider) are declared there instead.
• package.json + npm run docs:build replaces pip install mkdocs-material + mkdocs build --strict.
• Content uses VitePress's fenced custom containers (::: info Title … :::) instead of MkDocs Material's indented admonitions (!!! info "Title"). The documentation standard remains generator-aware and applies the syntax appropriate to each repository's registered framework.
• docs/standards/_scopes/** is excluded from the build via srcExclude (VitePress's equivalent of MkDocs's exclude_docs).

Hugo and Jekyll — existing, not recommended for new repos

Two more generators are live and working in the estate:

• Hugo — thisismydemo.github.io (Kris's personal blog). Confirmed via config.toml, archetypes/, and a Hugo build pipeline.
• Jekyll — cloudsmith-docs (GitHub Pages default for the cloudsmith-cloud org).

Neither is prohibited — both sites work and are not being migrated. But neither is recommended for a new repository. If you are standing up a new documentation site, choose MkDocs Material (default) or Docusaurus (if your repo is in one of the two sanctioned scopes above). Only continue with Hugo or Jekyll if you are extending an existing site that already uses one.

No generator (plain Markdown or plain HTML)

Most automation, application, and library repos across the estate have no documentation site at all — README.md and files under docs/ are the primary documentation surface, rendered natively by GitHub/GitLab/ADO. This is the correct choice for repos that don't need a browsable multi-page site. A handful of small marketing sites (cloudsmith-cloud.github.io, cloudsmith-app.github.io, cloudsmith-blog) are hand-written plain HTML with no generator — also acceptable for a small, static, rarely-changed site.

---

Decision guide for a new repo

Situation	Use
New repo, no scope override	MkDocs Material
Repo is the TierPoint official documentation portal	Docusaurus
Repo is a TierPoint documentation, lab, POC, product-project, or customer site	VitePress
Repo is a TierPoint interactive portal or configuration builder	Existing application framework
Repo is a public-facing AzureLocal community resource	Docusaurus (match azurelocal.github.io)
Repo is in azurelocal scope but not the community portal	MkDocs Material
Repo is the platform repo itself	VitePress (existing exception outside TierPoint)
Repo needs no multi-page doc site	No generator — README.md + docs/*.md
Extending thisismydemo.github.io	Hugo (existing site only)
Extending cloudsmith-docs	Jekyll (existing site only)

Do not introduce a seventh generator without a compelling reason and sign-off — the point of this standard is to bound the number of toolchains the estate has to maintain, not to eliminate the exceptions that already have production reasons to exist.

---

master-registry.db — docs_platform field

Every repository entry in master-registry.db carries a docs_platform field:

docs_platform: mkdocs | docusaurus | vitepress | hugo | jekyll | astro | none

This is the field any AI client, script, or human should check to know which documentation framework a given repo uses — the same way standards_scope answers "which standards apply here" and type answers "what kind of repo is this." Detection is based on the presence of a generator config file: mkdocs.yml → mkdocs; docusaurus.config.js/.ts → docusaurus; docs/.vitepress/config.mts/.ts/.js (or a .vitepress/ directory) → vitepress; config.toml + archetypes/ → hugo; _config.yml → jekyll; astro.config.mjs/.ts/.js → astro; none of the above → none.

astro is in the enum because several existing sites are built with it (the personal-org .github.io sites and holdfast-press.github.io). Like Hugo and Jekyll it is existing-only: it is recorded where it is already in production, and is not a sanctioned generator for new documentation sites.

The backfill of this field across all registry entries was completed 2026-07-05 (detection run against every repo's local working copy).

---

Per-repo assignment (condensed)

The full per-repo list lives in master-registry.db. This table summarizes the current state by scope; treat it as a snapshot, not a live source.

Scope / group	Framework	Repo count (observed)	Notes
AzureLocal org (general)	MkDocs Material	~25	Org default; includes the AzureLocal platform repo
azurelocal.github.io	Docusaurus	1	Public community portal — deliberate exception to the org default
tierpoint-prodtech official docs	Docusaurus	1 canonical portal	.mdx, independent product versioning, required frontmatter
tierpoint-prodtech documentation sites	VitePress	Scope default	Lab, POC, product-project, and customer documentation
tierpoint-prodtech interactive applications	Existing application framework	As required	Portal and configuration-builder experiences
platform (this repo)	VitePress	1	HCS platform repo only — one-off exception, not extended elsewhere
thisismydemo.github.io	Hugo	1	Personal blog — existing, not a template for new repos
cloudsmith-docs, WhatTheHack	Jekyll	2	GitHub Pages default / upstream fork — existing, not a template for new repos
Personal-org sites, holdfast-press.github.io	Astro	4	Existing sites only — not sanctioned for new documentation repos
CloudSmith marketing sites	None (plain HTML)	3	Small, static, hand-written
Automation / app / lab repos	None	Majority of the estate	README.md is the primary surface

---

The tierpoint-prodtech exception

tierpoint-prodtech-scoped standards contain TierPoint-specific platform and publishing rules. They are not published to the public HCS standards site (platform.hybridsolutions.cloud); the canonical source stays in the protected Product Technology documentation portal and is synchronized into the MCP image at build time. Published examples still use Infinite Improbability Corp values, and real credentials, customer data, internal collaboration links, and infrastructure identifiers remain prohibited. See examples.md and _scopes/README.md for the boundaries.

---

Related

• Documentation standard — Markdown, diagrams, commit prose, admonitions (generator-agnostic)
• Naming standard — resource and file naming, including per-scope overlays
• _scopes/README.md — three-way scope reconciliation matrix