Working with Documentation¶
This guide explains how to work with Tach's documentation system, which uses MkDocs with the Material theme.
Prerequisites¶
You need Python installed on your system and the documentation dependencies:
Local Development¶
To work on the documentation locally, run:
This will start a local server at http://127.0.0.1:8000/ with live reloading.
Documentation Structure¶
The documentation is organized as follows:
docs/index.md
- Home pagedocs/getting-started/
- Getting started guidesdocs/usage/
- Usage documentationdocs/contributing/
- Contributing guidesdocs/assets/
- Images and other assets
Adding New Pages¶
To add a new page:
- Create a new Markdown file (
.md
) in the appropriate directory - Add an entry to the
nav
section inmkdocs.yml
Example:
nav:
- Home: index.md
- Getting Started:
- Overview: getting-started/introduction.md
- # Add your new page here
- My New Page: getting-started/my-new-page.md
Formatting¶
MkDocs uses Markdown for formatting. Some useful features with Material for MkDocs include:
Code Blocks¶
Admonitions¶
Note
This is a note admonition.
Warning
This is a warning admonition.
Tip
This is a tip admonition.
Tabs¶
Content for tab 1
Content for tab 2
Images¶
Place images in the docs/assets/
directory and reference them like this:
Deployment¶
The documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch. The deployment is handled by the GitHub Actions workflow in .github/workflows/docs.yml
.