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. It is superseded because two scopes — tierpoint-prodtech and the AzureLocal community portal — already require Docusaurus for reasons that are sound in their own context (see below). Forbidding a generator that is already load-bearing in production does not serve anyone. This document replaces the prohibition with an explicit, scoped policy.

A third, narrower exception exists as of 2026-07: the platform repo itself — the repo this standard lives in — runs VitePress, not MkDocs Material. This is a one-off exception scoped to this single repo, not a change to the HCS-wide default: every other repo still defaults to MkDocs Material. See VitePress — sanctioned for one repo 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 two scopes

Docusaurus is sanctioned, not merely tolerated, in these two scopes:

1. tierpoint-prodtech scope — the entire TierPoint Product Technology documentation estate is built on Docusaurus (tp-docs-docs, the canonical ProdTech portal, plus tp-azure-local-anywhere-pdp). .mdx content, required frontmatter blocks, a badge library, and MDX-specific components (<Tabs>, <DocCardList>) are standard there. This scope stays off the public HCS site — see Real environment names below.
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 in either of these two scopes should use Docusaurus. New repositories outside these scopes should default to MkDocs Material.

VitePress — sanctioned for one repo: the platform repo itself

VitePress is sanctioned for exactly one repo: platform (this repo), serving platform.hybridsolutions.cloud. It is not a general-purpose alternative to MkDocs Material — do not pick it for a new repo without the same kind of explicit, scoped sign-off this exception got.

Why an exception here specifically: this repo is the reference implementation and authoring surface for every standard in this document — Kris wanted its own site off MkDocs Material, and because it publishes through the same ADO + Azure Static Web Apps pipeline as every other exception in this file (.ado/docs-deploy.yml), swapping the build step (npm run docs:build → docs/.vitepress/dist) for the deploy step (mkdocs build --strict → ./site) was a contained, low-risk change with no branch-based versioning (mike/gh-pages) plumbing to fight, unlike the AzureLocal org's GitHub Pages sites.

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's admonition guidance is unchanged and still describes the MkDocs Material syntax every other repo should use — it does not apply to this repo's own rendered site.
• 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 in tierpoint-prodtech scope	Docusaurus
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 only — do not extend it to other repos)
Repo is tp-haas-hyperv-as-a-service	VitePress (sanctioned exception — the HaaS docs portal runs VitePress by design)
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 scope	Docusaurus	2 (tp-docs-docs, tp-azure-local-anywhere-pdp, plus growth)	.mdx, required frontmatter, badge library
tp-haas-hyperv-as-a-service	VitePress	1	Sanctioned exception — HaaS docs portal runs VitePress by design (confirmed 2026-07-05)
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 documentation is real production content for TierPoint's internal environments and references real environment names (see examples.md for the boundary between real environment names and fictional documentation examples). Because of this, tierpoint-prodtech-scoped Docusaurus content is not published to the public HCS standards site (platform.hybridsolutions.cloud) — it stays internal to the tp-docs-docs portal. AzureLocal-scoped content, by contrast, uses only fictional examples and can be public. See _scopes/README.md for the full three-way scope model.

---

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