From 9912d0d488819854a629a860b29715c53d1995d7 Mon Sep 17 00:00:00 2001
From: digehode <digehode@googlemail.com>
Date: Wed, 22 Jul 2020 13:58:26 +0100
Subject: [PATCH] Added rough documentation for `code_from_file` and
 placeholders for the rest

---
 README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/README.md b/README.md
index c18782c..b980760 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,103 @@
 # mk_doc_ultra
+
+A collection of macros to help write tutorials.
+
+# 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