Humphries' lab manual

Source behind the lab manual of the Humphries lab, which is hosted at:

→ humphries-lab.github.io/Lab-Manual

Editing the manual

You can make edits to the lab manual straight from your browser:

1. Every page on the website contains an edit this page icon (in the top-right-hand corner of the page, right of the main heading).
2. Clicking that icon opens the source of the page on GitHub. (This will be one of the markdown files in content/)
3. Make your proposed edits, and click the green Commit changes button.
4. This will open a Pull Request (PR), for review by someone from the lab.
   • If you are a member of the Humphries-Lab GitHub Organization, you can also directly 'commit to main', which will update the website immediately, without review.

When the PR is reviewed and merged (or when the commit to main is made), the website will automatically be rebuilt (by a GitHub/Microsoft computer), and the website will be updated after a short while.

For more on the particular Markdown syntax used, see below.

The following is not necessary to edit the website.
But if you'd like, you can build the website locally, and try out changes on your own computer:

Local live build

_{This section assumes some familiarity with the command line.
If you're on Windows, I recommend using Windows Terminal, and either Git-for-Windows' Bash, or WSL2.}

Make sure you have a recent-ish Python version installed and available on your PATH.
_{If you haven't got Python, you can install it via e.g. conda, for which I recommend the miniforge distribution.}

Download or clone this repository, and in its root directory, run:

pip install -r requirements.txt

and

mkdocs serve

This will build and serve a live-reloading version of the website at http://127.0.0.1:8000
The server can be stopped with Ctrl-C.

About

The lab manual was originally written in LaTeX by Mark Humphries, and was converted to the current editable-website form by Tomas Fiers.

Version history

• First version: March 29th, 2019
• Last LaTeX version: April 28th, 2020
• Conversion to website: January 30th, 2023

For more fine-grained changes, from 2023 on, see the commit log.

Technology

The website is built using MkDocs, which is a so called 'static-site generator' (i.e. a markdown-to-html convertor), written in Python. It is styled with the mkdocs-material theme.

MkDocs and mkdocs-material are configured with mkdocs.yml. This YAML file defines which pages are included (and in which order), what goes in the website footer, which plugins are enabled, etc.

On every commit to the main branch on GitHub, the process defined in .github/workflows/build.yml starts. This is a GitHub Actions 'workflow'. It runs mkdocs, and commits the resulting HTML, CSS, and Javascript files to the gh-pages branch, which is what is visible on the website.

Customization & Markdown syntax

For more on how to customize the website (beyond just editing its content) please see the documentation of MkDocs and of mkdocs-material.

Those resources are also useful when you're wondering how to achieve some typographic effect with the particular markdown syntax used here.

In particular, note that MkDocs / Python-Markdown does not support using \ for hard line breaks (unlike GitHub Markdown, CommonMark, and TeX). Use <br> instead.