READ ME

This brings together GIS teaching materials from a variety of weeks and incarnations into a single set of open source frameworks that are easy to manage in a git repository.

Lectures

The lecture slides are maintained in simple markdown files using a per-lecture image directory for media. In the lectures base directory, there are is a shared CSS file (lectures.css). This file is intended to provide a common set of styling options for the lectures but isn't fully implemented yet for the MARP framework. There is also an index.md file that contains a single slide with links to each lecture:

Each lecture directory then contains:

• A lecture_X_marp.md file containing the markdown slide contents.
• Possibly a lecture_X_marp.rmd file containing R markdown - this is used to generate figures and statistical output. Where this is present, the plain .md file is automatically generated from this source (see below).
• An images directory used to contain any lecture specific images to be included on slides.
• Possibly a figure directory, containing figures generated by executing the R markdown source file.
• Possibly a cache file - these are on the .gitignore list, but appear when the R markdown source is run to cache slower running code outputs.

The MARP plugin for VS-Code is highly recommended - it provides QA tools for wwriting the slides, can also generate a live preview of the slides and provides a GUI export button for creating PDF and static HTML.

Running R markdown

The R markdown source files are used to generate figures and examples. These .rmd files need to be run through knitr before then can be viewed. Handily, the VS-Code live preview of the resulting MARP markdown file updates when this command is run, so it is easier to see how the final slides will look.

Rscript -e "knitr::knit('lecture_5.rmd')"

Layout

Markdown is not about layout, so the MARP framework uses HTML and CSS to position elements on the slide. MARP provides some default themes that contain the CSS to define layouts: these lectures use a locally defined modification of the gaia theme called gaia-local that is defined in the file gaia_local.css. This theme is registered for use with the VS Code plugin in the .vscode/settings.json file.

Exporting lectures

The VS Code plugin provides an export button to generate PDF and HTML files. Alternatively, the MARP framework can be run from the command line: this requires the use of the Node framework and specifically the npx (node package execute) command. Note that although the theme is registered for use by the VS Code plugin, it needs to be explicitly added to npx calls.

npx @marp-team/marp-cli@latest lecture_1/lecture_1_marp.md \
  --theme gaia_local.css \
  --allow-local-files --html --output pdfs/lecture_1.pdf

You can also create a static HTML page. Note that this must stay in the same directory as the original markdown source because it will use the same paths to images.

npx @marp-team/marp-cli@latest lecture_1/lecture_1_marp.md \
  --theme gaia_local.css \
  --allow-local-files --html --output lecture_1/lecture_1.html

Build script

The script lectures/build_slides.sh automatically builds slides from all lectures in the lectures directory. It builds PDFs into an explicit pdfs directory, but the HTML slides are built into each individal lecture directory, because they need the paths to images to be maintained.

reveal.js

The lecture slides used to built and served using the reveal-md framework. This has lots of lovely features for display (nested structure, hot keys for black slides etc) but reliably turning the slides into PDFs for handout that maintained formatting turned into a hellscape of puppeteer configurations and CSS noise. The MARP framework is more limited in some ways but seems to produce consistent static HTML and PDF pages much more easily.

Practicals

The practical files are built using JupyterBook. The files themselves are stored as Markdown files using the Myst Markdown extensions provided for JupyterBook. This makes it easy to save the notebooks in the more human readable Markdown format.

There are two stages to deploying the pages:

1. Build the site, generating the practicals/_build folder containing the html folder

jupyter-book build practicals/

1. Publish the html version of the pages to Github

ghp-import -n -p -f practicals/_build/html