Skip to content

Setting Up

We'll kick off by setting up your local development environment.

Important

If you have any questions about setting up your development environment for this website, or you get stuck - feel free to reach out to the Technology Team via Discord.

Requirements

To contribute, you'll need the following -

Lets get cracking!

  • Fork and Clone the - Knowledgebase Project - Guide.
  • Install the following Python packages: mkdocs-material, mkdocs-git-revision-date-localized-plugin, mkdocs-awesome-pages-plugin and mkdocs-redirects.

Easy Python Package Installation

These packages can be installed easily through a single command.

  pip install -r requirements.txt

You'll still need to ensure you have Python installed first, as these use pip - a Python package installer.

  • Once you've installed the requirements, open a command line terminal, cd into the cloned repository and start the mkdocs service:

mkdocs serve
OR 
python -m mkdocs serve

  • You'll see the command line performing some magic, eventually displaying Serving on http://127.0.0.1:8000. Open up your web browser, and navigate to that address.

Common Setup Issues

'pip' Term not Recognised

When running the pip install -r requirements.txt command, you may receive an error preventing any packages from being installed. Check that Python is installed and accessible by typing python into a VS Code terminal. If necessary, the Windows Store will open and allow you to install the correct Python package. Restart VS Code before continuing.

Script installed 'Not on PATH'

After running the pip install -r requirements.txt command, some packages may produce yellow warnings, such as below:

"WARNING: The script watchmedo.exe is installed in 'C:\Users\username\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p0\LocalCache\local-packages\Python310\Scripts' which is not on PATH. Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location."

Python is recognised but some scripts have been installed beyond the scope of the software. Update your Windows PATH variable to include the path indicated in the error.

Follow the steps here to update your Windows PATH variable. Restart VS Code before continuing.

Using MkDocs

MkDocs is the underlying tool that we use for our Knowledgebase. It takes in Markdown files, and converts them to a static website on each save, which is then pumped into your browser upon an automatic reload.

Info

You won't need to run the mkdocs build command. This is automatically run as a part of the GitHub deployment workflow. If you do run this command, please make sure you delete the site folder that is generated in your base directory before committing your code.

Sometimes MkDocs wont like your changes, and may escape from the running serve instance. This is usually as a result of a broken .pages file. Just undo your changes and try again.

Last update: March 23, 2023
Back to top