Link Search Menu Expand Document
Heads - Wiki

Contributing to the Heads Wiki

The Heads wiki is open source and encourages contributions both big and small. It is written in Markdown (Markdown Cheat sheet) , built using Jekyll and themed using Just the Docs.

Table of contents
  1. On GitHub
  2. Locally

On GitHub

The simplest way to make a small change to existing pages is directly on GitHub as it requires no software to be installed.

  • Start by login into GitHub and forking osresearch/heads-wiki.
  • Find the desired page on osresearch.net. Click on the link at the bottom of the page saying “Edit this page on GitHub.”
  • This will bring you to an editor on GitHub and should mention that you do not have write access to the osresearch/heads-wiki repo and that changes will be made in your fork.
  • After making the desired edits, add a summary of the changes to the comment box and click the “Propose changes” button.
  • Now on the “Comparing changes” will be a “diff” of these changes to review before submitting. If the changes are correct, press the “Create Pull Request” button at the top of the page.

Locally

For larger changes, multiple changes and that may require adding new pages, it is strongly suggested to set up a local Jekyll instance. Please refer to Jekyll’s installation documentation to setup it up on your system.

Additionally, the theme will also need to be installed as the remote theme does not seem to work with locally severed Jekyll instances. Instructions for installing the Just the Docs theme can be found here.

After installing Jekyll and the Just the Docs theme,

  • Start by login into GitHub and forking osresearch/heads-wiki. Then clone your fork locally.
  • Navigate to the base of the locally cloned repo and alter _config.yml to use the local theme. The simplest way is to comment out the line that beings remote_theme and add a line theme: "just-the-docs"
 # remote_theme: pmarsceill/just-the-docs
 theme: "just-the-docs"
  • Now start Jekyll with: 
    $> jekyll serve

    This will start the Jekyll development web server and should be viewable in a web browser at http://localhost:4000/

  • Make the desired changes, commit them. BE SURE NOT TO ADD _config.yml to your changes.
  • Push the changes your forked repo.
  • To allow you and others to view the changes on GitHub, the GitHub pages branch may need to be changed. To do this, go to your fork of the heads-wiki on GitHub.com and click Settings. This should default you to the Options tab, scroll down to the section “GitHub Pages” and change the source branch to the name of the branch your changes are on. After a minute of so it should be built and can be seen under https://YOUR_USERNAME_HERE.github.io/heads-wiki/ replacing YOUR_USERNAME_HERE with your GitHub username.
  • Create a pull request.

** NOTE:** the email account associated with your GitHub account may receive an error regarding the CNAME, this can be ignored.