01 Building the site locally to edit

To edit the site and its content, first clone the repository locally as you would any other repository. Then you will need to install the mkdocs-material package in a Python virtual environment so that the page can be built and served on a local web server.

0. One-time only Initialize a virtual environment in the informatics-website directory:

cd informatics-website
python -m venv venv

1. Make sure you are in the informatics-website directory and start the virtual environment. This step alone differs based on operating system:

Unix/Mac:

source venv/bin/activate

Windows:

.\venv\Scripts\activate.bat

1.5. One-time only, Install mkdocs-material and necessary plugins:

We use several plugins to build the site:

mkdocs-material==9.6.*
mkdocs-material[imaging]
mkdocs-table-reader-plugin==2.0.*
mkdocs-jupyter==0.24.7
mkdocs-macros-plugin>=1.3.7
mkdocs-git-revision-date-localized-plugin==1.3.0
mkdocs-gen-files>=0.5.0

Note that mkdocs-material requires Python 3.8+ and it may be a good idea to update pip before installing.

These all need to be installed before building the site. This can be done with:

pip install -r requirements.txt

2. Start the local server:

mkdocs serve

If that works, your terminal should hang, which is good -- it means that the web server is running. The last line should be something like:

INFO    -  [10:30:46] Serving on http://127.0.0.1:8000/

Just copy the URL you see into your browser and hit Enter and you should see the site! All changes made to any files in the docs/ folder, or any changes to the configuration file mkdocs.yml will automatically rebuild and refresh the site. Changes made to other files, for example .json files in data/, Markdown templates in templates/, or generator scripts in scripts/, will require you to manually re-trigger a site build by editing a file in the docs/ folder (or e.g. just adding a space somewhere in mkdocs.yml and saving).