mkdocs-starter
A template repository for a MkDocs site with best practices baked in.
Theme
This site uses Material for MkDocs theme.
Run just serve to check it out locally.
Structure
It's recommended that projects adhere to the Divio System for Documentation.
| Oriented To | Must | Form | |
|---|---|---|---|
| Concepts | understanding | explain | an article |
| Reference | information | describe specifics | no-fluff specifications |
| Tutorials | learning | help new users get started | a hands-on lesson |
| How-To Guides | a goal | solve a specific problem | a step-by-step walkthrough |
Within the docs directory you'll find subdirectories for each of these types of documentation.
Tooling
| Capability | Tool | Description |
|---|---|---|
| Site Generator | MkDocs | Generates the HTML site from the docs directory |
| Prose Linting | Vale | Enforces consistent writing style in alignment with the Microsoft Writing Style Guide |
| Markdown Linting | markdownlint | Enforces consistent markdown structure and syntax |