Meta Contributing to the Documentation

The content on this site is written in Markdown, one file per page. These content files are stored on the modmore/Docs repository on GitHub. You'll need a GitHub account to suggest improvements, but little knowledge about using git is necessary.


The Mastering Markdown guide on GitHub is a good place to start if you've not worked with Markdown before.

Proposing Changes

To propose a change to a page, find the Edit this page link at the bottom of the page. Clicking it will send you straight to GitHub's edit interface for that page. You'll need to login to GitHub if you weren't already.

In the edit screen the Preview changes tab is useful to see the rendered Markdown to make sure the syntax is valid.

When you're happy with the changes you've made, you can propose the change at the bottom of the page. Fill in a simple summary and additional information in the description if needed. You'll then see a summary of the changes. Click the green Create pull request button, and Create pull request again to send the changes for review.

When the pull request has been created it will start running an automated test on CircleCI. This automated test verifies things like links and basic markdown syntax. The tests take a minute or two to run. If it flags any issues, you can click the Details link to see the full diagnostic output; there will probably be an error in red towards the bottom.

If the automated test is all green, we'll review your changes and merge it as soon as possible. Once merged it is automatically deployed to right away.

Full Git Workflow

If you have lots of changes to make or just don't want to use the GitHub edit interface, you can also use a full git workflow. This involves forking the repository, cloning it to your machine, pushing changes to a branch on your fork, and then sending a pull request from that.

Having the repository cloned on your machine will also let you build the full site locally with the ./ command (only tested on Mac/Linux) after an initial composer install to install Daux.

The readme on GitHub explains the process further.