Documentation Site

The documentation is written in Markdown and built with MkDocs Material. All source files live in the docs/ directory of the ansible-epic repository. Builds are handled automatically by Cloudflare Pages — no local build tooling is required to contribute.

Workflow

Previewing Locally

The local preview works best when the repository is cloned directly on a Windows machine rather than inside a remote development container, where the browser and the dev server are on different hosts and livereload is unreliable.

Prerequisites (Windows)

Install Python and Git if not already present:

winget install python3
winget install Git.Git

Clone the repository:

git clone https://github.com/Sapphire-Health/ansible-epic.git
cd ansible-epic

Install the MkDocs dependencies:

pip install mkdocs-material mkdocs-table-reader-plugin

Serve

python -m mkdocs serve -a 0.0.0.0:8000 --livereload

The site will be available at http://localhost:8000. The --livereload flag automatically refreshes the browser whenever a file is saved.

Zensical Migration Status (Blocked)

MkDocs 1.x is unmaintained (no releases in 18+ months) and MkDocs 2.0 is a breaking, ground-up rewrite with no migration path — plugins and theme overrides stop working entirely. Material for MkDocs is now in maintenance mode; the same team's recommended successor is Zensical, which natively reads mkdocs.yml.

We tested migrating this site (installed Zensical 0.0.50 in an isolated venv, built the actual docs/ + mkdocs.yml unmodified). Everything works out of the box: pymdownx.tabbed, pymdownx.tasklist, admonitions, search, extra_javascript/extra_css, the theme palette toggle, and the nav structure all render identically to the current MkDocs build.

The one blocker: docs/capabilities.md uses the mkdocs-table-reader-plugin's {{ read_yaml(...) }} macro to render capabilities-*.yml as tables. Zensical doesn't support this plugin yet, and it fails silently — even zensical build --strict reports "No issues found" while the page just shows the literal {{ read_yaml(...) }} text instead of a table. We also tried Zensical's own documented zensical.extensions.macros extension (which is supposed to provide an equivalent read_yaml function) via both the mkdocs.yml compatibility layer and native zensical.toml config — neither actually rendered a table in our testing, so this isn't yet a usable workaround either.

Zensical's roadmap explicitly does not commit to dates ("items on this roadmap do not have a strict ordering or implied dates of completion"), so there's no ETA to plan around. We're holding off on migrating until table support actually works end to end.

To test this yourself:

pip install zensical
zensical serve -a 0.0.0.0:8000

This mirrors the mkdocs serve command above — same port, same live-reload behavior. Everything will look correct except /capabilities/, which will show literal {{ read_yaml(...) }} text instead of tables.

Editing Existing Pages

1. Open a pull request with your changes to any .md file under docs/.
2. Cloudflare Pages automatically builds a preview of the site and posts a link as a comment on the PR.
3. Review the preview to confirm formatting and links look correct.
4. Once the PR is approved and merged into master, Cloudflare Pages rebuilds the production site at https://ansible-docs.sapphirehealth.org.

Adding New Pages

1. Create the .md file in the appropriate subdirectory under docs/.
2. Add an entry for it in the nav section of mkdocs.yml at the root of the repository. Pages not listed in nav are built but will not appear in the sidebar.
3. Open a PR as above.

Formatting Reference

The following MkDocs Material extensions are enabled:

Admonitions

Callout blocks for notes, tips, warnings, and similar:

!!! note
    This is a note.

!!! tip
    This is a tip.

!!! warning
    This is a warning.

Add ??? instead of !!! to make a block collapsible.

Code Blocks

Fenced code blocks with syntax highlighting:

```bash
echo "hello"
```

Add a title with:

```bash title="startup.sh"
echo "hello"
```

Content Tabs

Side-by-side tab groups — used throughout this documentation for Bash / PowerShell examples:

=== "Bash"
    ```bash
    echo "hello"
    ```

=== "PowerShell"
    ```powershell
    Write-Output "hello"
    ```

Note

The indentation under each === tab label must be exactly four spaces.

Tables

Standard Markdown tables are supported. Columns are sortable in the browser via the tablesort plugin included in the site.