mk_doc_ultra

A collection of macros to help write tutorials.

Requirements:

mkdocs
mkdocs-material>=5.4.0

Usage

You can download the contents or add it as a submodule to your repo.

For the rest of this document we assume it is located in the same place as your mkdocs.yaml file. That is, in the root of the repo, in a directory called mk_doc_ultra.

Add the following to your plugins/macros config hierarchy:

module_name: 'mk_doc_ultra.main'
include_dir: 'mk_doc_ultra/'

For example:

plugins:
  - search
  - macros:
      module_name: 'mk_doc_ultra.main'
      include_dir: 'mk_doc_ultra/'

Then in the theme element, add custom_dir: 'mk_doc_ultra/'.

Finally, include mk_ultra.css in your extra_css config.

A full example:

site_name: Some Site

nav:
  - home: index.md


markdown_extensions:
  - admonition
  - codehilite:
      linenums: false

plugins:
  - search
  - macros:
      module_name: 'mk_doc_ultra.main'
      include_dir: 'mk_doc_ultra/'


theme: 
  name: material
  custom_dir: 'mk_doc_ultra/'
  logo: 'images/logo.svg'
  palette:
    primary: 'indigo'
    accent: 'indigo'
    
extra:
  draft: 1
  year: '2020/21'

extra_css: 
    - css/extra.css
    - mk_ultra.css

The extra variables shown above are used by the version_info macro.

Provided Macros

version_info

todo

button

Adds a button. Taken from the sample macro file and left because it might be useful later.

state

code_from_file

Adds a code block taken from the given file. Example:

{{code_from_file("example.py")}}

Parameters:

start: If given, sets the starting line number to show. Defaults to 0
stop: If given, sets the last line number to show. Defaults to the last in the file
flavour: sets the type of highlighting to be used, e.g. "python"
download: If set to True, includes a link to download the source file. Default is False
execute: If set to true, executes the code and displays the output
typed: If given, this string will be used as user input to the code being executed
colour: If set to true, adds output highlighting. Curerntly only highlights the piped user input

external_markdown

Theme Switcher

I have also added a theme switcher for the mkdocs material theme. This allows you to select between dark mode, and light mode. It uses localstorage to stash a "lightMode" token so it remembers the settings.

To use the switcher you need to modify your mkdocs.yaml

Include the custom.css file using the extra_css attribute
Place the custom_theme in the base directory (the same one as the mkdocs.yaml, not the docs directory

Configure in the config file using:

theme:
  name: material
  palette:
    scheme: preference
  custom_dir: custom_theme

mk_doc_ultra/README.md