Contribute to the teaching material
This website is stored as a project site Github page and is stored on the CERG-C github repository. The documentation is written in Markdown, and built into a website using the static website generator MkDocs with the Material for MkDocs theme. Building and deploying the website requires some knowledge of Python and Git.
Software requirement
Github
Contributing to the course requires a Github account. So make one, then send me an email so I can add you to the organisation/repository.
Pandoc
It is recommended to install pandoc before installing the Python dependencies.
Old Mac OS versions
On older (e.g., 10.x) versions of MacOS, installing pandoc with Homebrew can be problematic. In which case, revert to the packaged distributions.
Installing the website
Setting up a Python environment
It is recommended to setup the website in a Conda environment rather than on the system's Python distribution. For an environment named teaching, create it using:
Then activate it using:
Installing dependencies
Install the following Python dependencies:
pip install mkdocs-material mike mkdocstrings livereload mkdocs-jupyter mkdocs-bibtex mkdocs-encryptcontent-plugin
Python versions on Mac OS
If pip complains about a 2.7 Python version, use pip3 instead.
Contributing to the course
The teaching content is located in the folder docs/Teaching, where sub-folder contain Bachelor, Master and CERG. Create a sub-folder in the relevant folder and create the following sub-folders
- A sub-folder named img/ that will contain all images
- A file called index.md that will be the landing page of your course.
Writing the documentation
The documentation is written in Markdown, which is a simple and elegant typesetting language. For an introduction to Markdown, check out the cheatsheet.
Further cool features are complemented with the use of the Material for MkDocs theme. These include:
Check out the reference page of the Material for MkDocs documentation for more info.
Linking files
All internal links to the website (i.e., both to files and images) use relative path to the location of the current page. Within a single class, cergclass1.md can be linked within index.md by a simple [link](cergclass1.md).
This path must be adapted to link files between classes. For instance, masterclass1.md can be referenced in cergclass1.md using [link](../../Master/MasteClass/masterclass1.md).
References
Bibtex-style of referencing is accepted using the mkdocs-bibtex. The master .bib file is includes/bibliography.bib. Please add your reference to the existing list. In-text citations are then achieved as:
Abbreviations
A glossary exists in includes/glossary.md. Each entry will automatically be formatted at the bottom of the page that contains the term following this. Add your own abbreviations to this list.
Extra files
Deploying the website
Local deployment
To deploy the website locally, run the following command from the root of the directory (i.e., at the same level as the mkdocs.yml file):
Remote deployment
We use mike to keep track of versions. The active version is always set with the latest label, so make sure it is set by default. From the root of the CERG-C repository, run from the terminal:
When working on a new version, push the website using a dummy label - here test.
When happy with your changes, use the latest label.
Different versions are accessible with their version numbers. For instance, the url of version 2022.1 is https://cerg-c.github.io/CERG-C/2022.1/.
Keep track of versions!
Log the purpose of the versions here!
Mike, don't push me
mike pushes the build version of the webpage to the remote gh-page branch. For collaboration, it is also necessary to synchronise the main branch that contains the class Markdown files.
-
Newhall CG, Self S. The volcanic explosivity index (VEI)- An estimate of explosive magnitude for historical volcanism. Journal of Geophysical Research 1982;87:1231–8. ↩