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
bibtexparser>=1.4.3

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

Windows only: Windows users also need to install the appropriate GTK libraries to install other dependencies to render social cards. This is done by manually running the GTK+ for Windows Runtime Environment Installer. Just get the executable from the latest release of that repo and install with all defaults, then restart your terminal.

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).

Debugging on mobile

You can also start the server to be viewed from other devices on your network, including mobile devices.

1. Lookup your computer's IP address with ipconfig or ifconfig.

2. Start the server at a particular address:

mkdocs serve -a 0.0.0.0:8000

3. Once the server starts, allow Python to accept incoming connections from the network in your firewall.

⚠️ Only do this on trusted private networks.

4. On the other device on your network, in the browser go to http://<your computer's ip address>:8000.

The site should be visible and rebuild as you develop.