Skip to content

MKDocs 🔗

Updated October 7, 2025

Admin rights required

To use the instructions below, you absolutely need admin rights on your computer. You need to request your manager/supervisor to petition for those rights for valid reasons. Once you have approval, contact the IT manager to switch your account.

What is it? 🔗

MkDocs is a static site generator specifically designed for building project documentation. At MobilityData it is used to generate and maintain the technical websites, like gtfs.org, gbfs.org and tods-transit.org and others.

We use a fork of MKDocs called MKDocs Material which has a more extensive UI and capabilities.

https://www.mkdocs.org/ https://squidfunk.github.io/mkdocs-material/

Add commands to your Terminal configuration 🔗

The rest of the documentation assumes these commands are present on your computer.

You will need the local Environment feature correctly setup in 1Password for this to work. Contact IT to have it configured.

These commands turn long and complex commands into simple one-word shortcuts.

  1. In Terminal, paste the following commands then hit Enter , provide your password when asked and press Enter once more.
sudo echo "alias pythonenv='python3 -m venv venv && source venv/bin/activate'" >> ~/.zshrc
sudo echo "alias loadenv='op run --env-file=.env -- env'" >> ~/.zshrc
  1. Issue the source ~/.zshrc command to load the changes, then hit Enter . You can also close and reopen a window, or quit and reopen Terminal.
  1. In Terminal, type sudo nano ~/.zshrc, hit Enter , provide your password and hit Enter once more.
  2. At the end of the text (use the Down key), add the following lines making sure to preserve the straight quotes:
alias pythonenv='python3 -m venv venv && source venv/bin/activate'
alias loadenv='set -a; source ~/.env; set +a'
  1. Then hit Ctrl+O (letter O, not zero), then Enter , then Ctrl+X to save and exit.
  2. Issue this command to load the changes: source ~/.zshrc and hit Enter . You can also close and reopen a window, or quit and reopen Terminal.

How to serve a MKDocs site locally 🔗

MobilityData use a specific layout and configuration of MKDocs Material and as such the standard commands will not work.

  1. cd (change directory) to the root of the site folder of the repo cloned locally on your system.
    • You can type cd + Space then drag and drop the folder from Finder, then hit Enter .
    • It will not work if you are not at the root of the local repo, which you can confirm by issuing the command ls requirements.txt and if you see requirements.txt appear, you are in the correct path.
  2. Type pythonenv to create and activate a new Python virtual environment.
  3. Next type loadenv to load the shared .env file (environment variables and secrets, shared via 1Password). Enter your 1Password Master password or use your fingerprint to authenticate.
    • This does not need to be done every time, perhaps once a day. If during the next step you are asked to provide a password for GitHub, use Ctrl+C to stop and run the loadenv command.
  4. Use the make setup command to install all the bits and pieces required to compile and run the site locally.
    • If you are asked to provide a password for GitHub, that means the .env file is not loaded, hit Ctrl+C to stop the process, use the loadenv command, then try this make setup again.
  5. Use the make serve command to compile the site and start a local web server. Once it says Serving on http://127.0.0.1… it is ready to be accessed. Copy the address and paste into the browser of your choice.
    • Watch the port number (default is 8000 for English) as there is one port per language.
    • The language switcher will not work during this local serving.
    • Some features will not work because it’s served locally, but will once the site is updated on the production server.
  6. Do all the changes you wish on the repo, the site will reload the site automatically.
    • If it does not, hit Ctrl+C, then make serve again. Then reload the page in the browser.
  7. Once you are done, hit Ctrl+C to stop the serve command.
  8. Then use the deactivate command to get out of the virtual environment setup in step 2.
    • Alternatively you can close the Terminal window or simply quit Terminal.