Documentation

pt-ekklesia-docs is the platform documentation site, published at docs.osinfra.io.

Tech stack

Built on Docusaurus 3 with the following features enabled:

• Mermaid diagrams — architecture and workflow diagrams rendered inline
• Local search — full-text search with highlighted results, no external service
• Syntax highlighting — HCL and Bash in addition to Docusaurus defaults
• Edit on GitHub — every page has a direct link to edit the source on GitHub
• Mantine UI — shared cards, responsive grids, onboarding form controls, schema accordions, invocation tabs, and static timelines use a single dark/gold theme, with Tabler outline icons and no icon backgrounds

The site-wide Mantine provider lives in src/theme/Root/index.jsx. Import only the styles needed by each component (including dependency styles such as Paper.css for Card); do not import Mantine's global reset or full stylesheet, which can override Docusaurus styling. The provider emits the base CSS variables explicitly, so component-only imports retain correct sizing and spacing.

Markdown tables use the shared Mantine table mapping in src/theme/MDXComponents/: left-aligned headers, subtle row separators, and native horizontal scrolling on narrow screens. Keep writing ordinary Markdown tables; no per-page JSX is needed.

Cards use named Tabler outline icons from src/components/CardIcon/ instead of emoji (for example, icon: 'rocket', icon: 'world', or icon: 'book'). Keep icons muted and background-free.

Deployment

• Pull requests — a test build runs on every PR to catch broken links and build errors before merge
• Merge to main — the site is built and deployed to GitHub Pages automatically; the custom domain docs.osinfra.io is served via CNAME

Contributing

Every page has an Edit this page link that opens its source on GitHub. Keep content task-oriented: state who owns the capability, what a consumer provides, what the platform returns, and where the lifecycle is managed.

Write for two audiences and keep them apart. Consumer guides live under docs/getting-started/ and own the declaration contract (fields, examples, validation, verification) exactly once. Owner pages under docs/platform-grouping/<team>/ describe how the capability is built and operated, link to the consumer guide instead of repeating its fields or examples, and keep their ADRs at the bottom.

Avoid duplicating module inputs or implementation details that are already clear in a repository README.

Changes follow standard GitHub Flow. When adding a page:

1. Create the Markdown file under docs/
2. Register it in sidebars.js — the page will not appear in navigation until it is added there
3. Run yarn build
4. Open a pull request — the test workflow validates the production build before merge

Components

Component	Description
doc-page	A Markdown page in the Docusaurus site, organized by team and capability
adr	An Architecture Decision Record embedded in a doc page, capturing context, decision, alternatives, and consequences