01 Building the site locally to edit - harvardinformatics/informatics-website GitHub Wiki

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
notebook>=7.4.4

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

Cairo libraries for social cards plugin

The social cards plugin (social) uses the mkdocs-material[imaging] plugin, which installs cairosvg to generate the social card images. However, this does not install the associated cairo libraries.

Easiest solution: disable the social plugin for local builds

Unless you're actively developing the social cards, you can just disable the social plugin by un-commenting the enabled: false line in mkdocs.yml:

  - social:
      # enabled: false # SOCIAL PLUGIN: Uncomment to disable for local builds
      cards_layout_options:
        background_color: "#F3F4F4" 
        color: "#a51c30"
        font_family: Open Sans

This should disable the generation of the social cards.

If you do need to generate the social cards locally, you may need to do one of the following.

Windows: Install cairo libraries

Windows can 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.

macOS: Install cairo libraries

Mac users will have to first install cairo:

brew install cairo

And then add the path to the libraries to the appropriate environment variable:

export DYLD_LIBRARY_PATH=$(brew --prefix cairo)/lib:$DYLD_LIBRARY_PATH

You may also want to add this line to your shell profile so you don't have to bind it each time.

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
  1. Once the server starts, allow Python to accept incoming connections from the network in your firewall.

⚠️ Only do this on trusted private networks.

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