Skip to content

How To Contribute

Contributing to this site is easy! (Relatively). This site is made using MkDocs, a markdown-based (i.e. no fancy complex code) documentation site generator. This page is aimed at those who don't really know how to, or care for, coding or technical work, but still want to add resources. As such, I will try to skip over as much of the "install python, configure dev environment, etc, etc, etc" boring stuff as I can.

Prerequisites

  • Know how to write markdown. See here for a reference of the MkDocs markdown dialect.
  • Know, or be willing to learn how to write yaml.
  • Have a GitHub account and know how to navigate the site. Click here to go to the GitHub page for this project or from the icon in the footer from any page.
  • Knowledge of Git and a code editor is helpful, but not required. You can create, upload, and edit markdown on the GitHub web interface, though you will not be able to run and preview the site yourself.
  • (Only if you want to run the site locally) Python 3, with the mkdocs, mkdocs-material, mkdocs-material[imaging] (and dependencies) packages. I won't go into further detail because that's not the aim of this page.

Guidelines

  • Keep the file sizes lean. Only upload markdown and image files. For any large files, such as PDF scans, csv dumps, etc, it's best to use a public link from a hosting service like drive, and just link it here.
  • Try to categorise things nicely. Take advantage of the categories, folders, and subfolders we have.
  • Make frequent commits. A "commit" (see Submitting your work) is a checkpoint of your changes, so each single "change" you make (e.g. adding a page, editing a paragraph, adding a set of dictionaries) should be one commit. When you merge back in, you can merge multiple commits at once, so don't worry about making small, frequent checkpoints.

Final Words

  • See Tutorials for some tutorials walking through different possible use cases and covering the whole process from making an edit using the GitHub web editor, to merging your contribution into the site. The whole process can be quite technical and the tutorials may not cover every case, so please take advantage of any other resources available to you.
  • See Useful Tips for any fancy functionality that I've enabled, that may not come in vanilla markdown. These can help you better format and present your page.