Skip to content

Publish documentation on the hub

PCA enables its working groups, communities, and content owners to publish and maintain documentation on the PCA Documentation Hub. Publishing is distributed so that each contributor can work flexibly within a shared set of technical and editorial boundaries.

This page describes the requirements for PCA to publish documentation on the PCA Documentation Hub.

How distributed publishing works

To ensure quality, trust, and maintainable synchronization, all published documentation should follow a small set of common technical requirements.

Meeting these requirements helps PCA onboard and synchronize documentation efficiently while keeping the hub consistent for users.

Publishing Requirements

To be accepted for publication on this hub, documentation should meet all of the following.

Official PCA GitHub repository

  • The source should live in an official PCA GitHub repository.
  • This ensures the source is trusted and endorsed by PCA.
  • PCA can provide a starter repository based on an approved template that already satisfies the core Documentation Hub requirements.
  • If you need a new documentation repository, send a request to support@posccaesar.org.

MkDocs and Markdown

  • Documentation should be authored in Markdown and built with MkDocs.
  • Repositories that do not use MkDocs are currently not supported in this hub.

Dedicated documentation scope when a repository contains more than documentation

  • If a repository includes code, tools, or other non-documentation material, the MkDocs documentation should be organized in a dedicated folder structure.
  • The documentation section should be clearly isolated so it can be synchronized reliably into the Documentation Hub.

Non-technical users should be able to contribute

  • Non-technical users can contribute through Pages CMS.
  • Pages CMS must be granted access to the specific repository.
  • Access can be requested by emailing support@posccaesar.org.

Repository structure

Keep the MkDocs project boundary and all published files simple and predictable:

  • the repository should keep all published documentation inside a docs/ folder
  • the repository should include a root docs/index.md page
  • if you want a folder to appear as a section in navigation, that folder should include its own index.md
  • folders act as sections and Markdown files act as pages
  • the MkDocs project boundary should remain simple and predictable, typically with mkdocs.yml at the repository root and docs_dir: docs
  • media and content paths should remain stable within the boundaries of the docs/ folder

Important Stability Rules

To keep synchronization with the PCA Documentation Hub reliable:

  • do not rename or remove the docs/ folder
  • do not delete docs/index.md
  • do not make unnecessary structural changes to mkdocs.yml or .pages.yml

These requirements are intentionally simple. The goal is to make documentation easy to maintain, easy to synchronize, and safe for both technical and non-technical contributors.