Skip to content

What is MkDocs Tau Delta?

MkDocs

MkDocs is a static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

It is an open source project. Its repository can be found here. Its website can be found here.

MkDocs Tau Delta

Material is a theme for MkDocs built using Google’s Material Design guidelines.

It is an open source project. Its repository can be found here. Its website can be found here.

Other MkDocs supported themes can be found here.

MkDocs Tau Delta is a modified version of the MkDocs Material theme.

It is an open source project. Its repository can be found here.

Why “Tau Delta”

In the interest of having a proper name beyond the initials:

  • Tau Delta stands for Tremendous Documentation
  • the reasoning is that tremendous, as its definitions go, represents:
    • very great in amount, scale, or intensity: Tau Delta is meant for large documents
    • extremely good or impressive; excellent: Tau Delta is meant to be easy on the eyes

Philosophically:

Warning

Not yet clear which parts of the GitHub Flavored Markdown (GFM) specification work with this theme yet.

The PyMdown extensions site has a guide on how to implement GFM.

Theme setup

Todo

Create an application that allows users to easily:

  • new dedicated documentation site:

    • create a skeleton for an example documentation site
    • obtain input from user: origin address including user, new repo name
    • create a new instance of MkDocs Tau Delta using a new repository

  • new documentation site as part of an ongoing project:

    • obtain input from user: repo address
    • check for existing docs/ directory, if it already exists warn user and ask for permission to continue
    • add a new instance of MkDocs Tau Delta to an existing repository

  • existing documentation site:

    • check for existence of docs/stylesheets, docs/javascripts, and mkdocs.yml
    • get the latest docs/stylesheets, docs/javascripts, and mkdocs.yml from the MkDocs Tau Delta repo
    • update local docs/stylesheets, docs/javascripts, and the extensions section of mkdocs.yml with the latest content

Configuration files

The following components are customized and are the only files you need to include to have the docs site up and running:

  • mandatory:

    • mkdocs.yml file for most site settings in / (root)
    • extra.css for font size and spacing settings in /docs/stylesheets/
    • scripts for supporting various extensions in /docs/javascripts/
    • publish_on_push.yml for automatic publish on push in GitHub in /.github/workflows/

  • optional:

    • favicon.ico in /docs/assets/
    • logo.svg in /docs/assets/

By adding the files above to your repo, https://github.com/{{ USER }}/{{ REPO }}, the site should become available at https://{{ USER }}.github.io/{{ REPO }}.

A local article on how to make your own favicon.ico and logo.svg can be found here.

Colors

Primary color is used for top bar and hyperlinks. It is set primary: 'blue'. The default indigo was replaced with blue for better visibility of inline hyperlinks, blue vs black is better than indigo vs black.

Accent color is used for hyperlinks on hover. It is set accent: 'blue'. The default indigo was replaced with orange for better visibility of hyperlinks on hover, and is also a good choice if the primary color is restored to indigo.

The options for can be found in the table below. They have been compiled from here for primary colors and from here for accent colors.

mkdocs.yml scss primary accent
red $clr-red-a400 X X
pink $clr-pink-a400 X X
purple $clr-purple-a200 X X
deep-purple $clr-deep-purple-a200 X X
indigo $clr-indigo-a200 X X
blue $clr-blue-a200 X X
light-blue $clr-light-blue-a700 X X
cyan $clr-cyan-a700 X X
teal $clr-teal-a700 X X
green $clr-green-a700 X X
light-green $clr-light-green-a700 X X
lime $clr-lime-a700 X X
yellow $clr-yellow-a700 X X
amber $clr-amber-a700 X X
orange $clr-orange-a400 X X
deep-orange $clr-deep-orange-a200 X X
brown $clr-brown-500 X
grey $clr-grey-600 X
blue-grey $clr-blue-grey-600 X