Skip to content

Example

Overview

This is a quickstart template for creating technical documentation using the docs-as-code approach.

Clone the repository to start creating accessible, version-controlled, governed documentation for your project.

Features

Acronyms and abbreviations

Hovering your mouse over any TLA will reveal a tooltip with its definition.

You can tell if a TLA has a definition because it will be underlined.

Adding new acronyms

Define your glossary in includes/glossary.md. Tooltips will be added automatically whenever that acronym is used in any page.

Side notes

Callouts

Callouts draw the readers attention to important information. The callouts below are collapsible; click them to expand.

This is a tip

This advice may be handy here.

This is a warning

Caution is needed here.

This indicates danger

There is a critical potential pitfall here.

This is a placeholder

More details are needed here.

This is a note

Extra information is here.

If you are looking for something specific, the search bar at the top is the fastest way there.

Learn more about search

The mkdocs-material documentation has more information on how search works and how to configure it.

  • Top-level sections can be navigated using the links on the left-hand menu.
  • Sub-sections are shown on the right-hand menu.

Keeping track of your place

The right-hand menu helpfully updates as you scroll.

Dark Mode

The documentation recognises your system preferences and automatically activates dark mode to reduce eye-strain.

Switching on Dark Mode

Use the icon in the top-right to manually toggle dark mode.

Footnotes

Tangential information can be added as a footnote.1 This allows extra information to be added without interrupting the flow.

Footnotes automatically become links

Click to jump to a footnote, then click the arrow to jump back again.

User guide

This section describes how to work with the documentation and how to make changes.

Markup

This documentation is written in markdown. It is compiled with mkdocs and styled with a DfE-tailored version of the mkdocs-material theme.

Diagrams

Diagrams can be created with Mermaid. Mermaid lets you create diagrams and visualisations using text and code. This makes it easy to keep them up-to-date.

Learn more about Mermaid

Consult the Mermaid Documentation for examples and tutorials.

Version control

By version-controlling your documentation with git you get benefits like:

  • Branching: Work on different versions in parallel without affecting the main version.
  • History Tracking: Every change is recorded, allowing you to revert to previous versions.
  • Backup and Recovery: Protect against data loss with remote repository backups.

Change management

You may like to set up branch protection rules to ensure changes are properly governed (e.g. require at least one review before merging to the main branch).

Building locally

Serve the documentation by running:

$ pip install mkdocs-material
$ mkdocs serve

Deployment

TODO

Document deployment options for serving static content to:

  • All DfE users
  • Specific DfE users
  • The general public

  1. This footnote serves no real purpose other than to demonstrate how footnotes work. Click the arrow to go back to where you were. ↩