Skip to content

Contributing

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.

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 main, 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.