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.

Initialize the virtual environment in the informatics-website directory:

cd informatics-website
python -m venv venv

Start the virtual environment. This step alone differs based on operating system:

Unix/Mac:

source venv/bin/activate

Windows:

.\venv\Scripts\activate.bat

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

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

The mkdocs-table-reader-plugin also needs to be installed. This is used to build the tag table pages (see below).

And the mkdocs-jupyter plugin needs to be installed for some of the workshops.

pip install mkdocs-material
pip install mkdocs-table-reader-plugin
pip install mkdocs-jupyter

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 (e.g. .json files in data/, Markdown templates in templates/, generator scripts in scripts/) will require you to manually re-run the associated Python script in scripts/ in another terminal window in order for the page to be rebuilt and refreshed.