Markdown

Toolchain for Documentation

This is an attempt to use MkDocs for documenting tutorials for UxD-G-M. The following installation steps are aimed at using MkDocs in a Python Virtual Environment (venv), which can be activated for use when documenting and reflecting on individual assignments. The 'rendered' output can be reviewed in a browser served by a local webserver. A static web page can be rendered for hosted viewing.

For full documentation of MkDocs visit mkdocs.org.

Installation

1. Install VS Code with Python Plugin

Install Python language support

Mac

Mac-Users may need to add python to their path to execute and in most cases may need to use the python3 command instead of python

2. Set-up Python Virtual Environment

Create Python Virtual Environment using a Terminal in VS Code:

python -m venv venv

Activate venv (Win):

venv/Scipts/activate.bat

Activate venv (Mac):

source venv/bin/activate

3. Install MkDocs

Install MkDocs using VS Code Terminal:

pip install mkdocs

Create new project (Note: Take care not to create the project folder within the venv!):

mkdocs new my-project

Run MkDocs. This starts up a local webserver to render Markdown (.md) files for debugging.

cd my-project
mkdocs serve

View your MkDoc by opening http://127.0.0.1:8000

Build static Website:

mkdocs build

4. Install Material for MkDocs

To make things a little more pretty we use https://squidfunk.github.io/mkdocs-material/

Install Material for MkDocs

pip install mkdocs-material

Edit mkdocs.yml to set theme:

theme:
    name: material

To tweak the navigation for drop-down sub-menus:

nav:
    - About: 'index.md'
    - 'U00 Werkzeuge':
      - 'Markdown' : 'U0000_Werkzeuge_MkDocs.md'
      - 'GitLab' : 'U0001_Werkzeuge_GitLab.md'
      - 'TouchDesigner' : 'U0002_Werkzeuge_TouchDesigner.md'
      - 'Processing' : 'U0003_Werkzeuge_Processing.md'
    - 'U01 ':
      - 'Processing' : 'U0003_Werkzeuge_Processing.md'

5. Commit Projectfiles to GitLab Repo

Create .gitignore to exclude the python virtual environmet (venv) from being uploaded to GitLab

venv/

Commit and Push local code to GitLab using VS Code

6. Python Requirements File (optional)

The Python requirements.txt file allows you to install required packages automatically. If you maintain a requirements.txt file you can use ist to create a new venv and then install all required packages such as mkdocs and mkdocs-material automatically. It also documents which packages are required for your python documentation tool.

Create a requirements.txt

pip freeze > requirements.txt

Install all required python packages using requirements.txt (Only needed if new venv is created)

pip install -r requirements.txt

Usage

Commands

• mkdocs new [dir-name] - Create a new project.
• mkdocs serve - Start the live-reloading docs server.
• mkdocs build - Build the documentation site.
• mkdocs -h - Print help message and exit.

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.