README.md

# 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
    ```