Making Changes to RTFM¶

The RTFM Manual is built on mkdocs, with the Material theme installed. Pages use the Markdown syntax.

For full documentation visit mkdocs and mkdocs-material.

Basics¶

Basic Requirements¶

Python (2.7, probably) - With the relevant environmental variable added
PIP - With the relevant environmental variable added

Basic Installation¶

pip install mkdocs - Install mkdocs
pip install mkdocs-material - Install the theme
pip install pymdown-extensions -Allow for Code

Basic Commands¶

mkdocs serve - Start the live-reloading docs server.
mkdocs build - Build the documentation site.

Live Server¶

Visit 127.0.0.1:8000 to see live changes, as long as mkdocs serve is running.

Adding a Page¶

Adding a page has two steps:

Create a new .md file, and name it something short and relevant in camelcase. Add your content in Markdown syntax. Place this file in the /docs folder

example: docs/bestTacosInBeaverton.md

Open mkdocs.yml in the repository root, and add the new page's title and link under pages:. For Example:

pages:
  - Home: index.md
  - Basics: basics.md
  - Lunch:
    - 'Tacos for Lunch': food-ideas/bestTacosInBeaverton.md
    - 'Thai for Lunch': food-ideas/bestThaiInBeaverton.md

Warning

YAML is a super stupid syntax, and requires nesting to be via two spaces instead of tabs.

Notice

If you want pages to be nested in the menu structure, nest them in subfolders, such as:

docs/
    index.md
    basics.md
    food-ideas/
        bestTacosInBeaverton.md
        bestThaiInBeaverton.md

RTFM file layout¶

docs/
    mkdocs.yml          # The configuration file.
        css/
            style.css   # Any style overrides. Use these sparingly.
        docs/
            index.md    # The documentation homepage.
            ...         # Other markdown pages.
        images/
            ...         # Any referenced image files. 
site/
    ...                 # Built static files, never make manual changes to this folder.

Info

Try to prefix image files with their relevant page. Example: zoom.md -> zoomvoip.png and zoomschedule.png

Warning

Make sure all changes are made to files in the /docs folder, not the /site folder

Git Rules¶

For the love of the gods, please don't add or commit the /site folder. You should only be committing changes and additions to files in the /docs folder. Commit often, and avoid jokes in RTFM commit notes.