A Digital Transformation Office UI Kit theme for MkDocs. View a demo of this theme
Install with pip:
pip install mkdocs-gov-au-theme
Add the following line to mkdocs.yml:
theme: 'gov-au-theme'
Add an abstract to the top of your page by adding the following to the start of your Markdown file:
abstract: Your abstract here
The table of contents will automatically display on any page that has multiple headings in the content. If you would like to hide the Table of contents add this to the top of the relevant Markdown file:
hide_toc: true
This theme allows you to add certain components to the page by specifying configuration options in the mkdocs.yml file. All the custom components must be listed as key value pairs within the extra YAML array.
For example:
extra:
badge: beta
feedback_link:
- 'title': 'Support request'
'url': 'https://www.support-url.gov.au'
You can add a badge to the site title in the header by adding the following
line to mkdocs.yml:
extra:
badge: beta
You can add whatever text you want within the badge. This can be helpful to let the user know if your docs are in Alpha, Beta or Live.
You may want users to be able to lodge tickets or email you for help with your documentation or service.
You can do this by adding the following lines to mkdocs.yml:
extra:
feedback_link:
- 'title': 'Support request'
'url': 'https://www.support-request-url.gov.au'
Add the following line to mkdocs.yml:
extra:
search: true
Add the following lines to mkdocs.yml:
extra:
footer_links:
- 'title': 'Status'
'url': 'http://status.gov.au'
'external': 'true'
- 'title': 'Privacy policy'
'url': '/privacy-policy'
You can add as many links as needed. You can also specify whether a link is an external link with 'external': 'true'
If you specify a repo_url for your docs the template will automatically add a
'Edit this page on GitHub' link to each page generated for a .md file. This link will take the
user to the md file on master branch in the GitHub repo.
You can specify your GitHub repo by adding the following line to mkdocs.yml:
repo_url: https://github.com/AusDTO/mkdocs-gov-au-theme
You do not specify the repo_url within the extra: YML array
This theme also allows you to add and modify tags in your sites <head>.
Add the following lines to mkdocs.yml:
google_analytics: ['UA-12345678-9', 'name']
You can hide a page from displaying in the navigation while still allowing that page to be part of the site build.
Add a _ in front on the page title in mkdocs.yml:
pages:
- Home: index.md
- A section:
- 'Section content page': 'section/section_content_1.md'
- '_Hidden section content page': 'section/section_content_2.md'
You can extend template block components by creating a new theme_dir in your project and adding a main.html with the following markup:
{% extends "base.html" %}
{% block block_name %}
Add your custom stuff here
{% endblock %}
The following template block components exist:
contentarticle_footer_contentpage_footerhead_meta
This project uses pa11y CI for accessibility testing.
If you want to run tests, first install dependencies with:
make pa11y-install
Make sure you have the site running locally with:
mkdocs serve
Then run the tests and results will be displayed in the terminal.
make pa11y-test
Read the pip distribution guide
- Update the version number in
setup.py python setup.py bdist_wheel --universal- Install twine
- Login to PyPI
twine upload dist/*- Draft a 'New release' on GitHub