If you haven’t done so already, the first thing you need to do is head over to Github and create your free account.
There are three steps to editing a page. First you need to locate the page you wish to edit. There are a couple of ways to do this. Method A is probably the simplest, and most likely way you’ll do it. Method B will serve as a primer for the next section: Adding a page.
While reading any section of the Handbook you’ll see an 'Edit this page' link in the bottom left of the page. Following this link will take you directly to an editable version of that page. Easy huh?
When the editable page opens it will (most likely) contain a message saying “You're editing a file in a project you don't have write access to”. If this is your first edit to The Open Data Handbook it will say “We've created a fork of this project for you to commit your proposed changes to”. This is normal and part of the workflow.
The entire file structure of this site can be browsed on Github. For example, the root of the site is here, and the English language handbook section is here. It’s helpful to understand that the page URLs correspond to the file structure you see here. So, if you wanted to edit the Handbook introduction page, given that it’s URL is {{ site.url }}/en/introduction/ we know this file can be found in the en directory with the filename introduction.md Note: the extension (.md) is stripped from the URL. Following these links you should see a preview of the page you wish to edit. From here click the edit icon [pencil icon] to start editing.
Press t on any tree or blob page to launch the file finder.
---
title: Introduction
---
The front matter must be the first thing in the file, must adhere to the above syntax, and must be set between triple-dashed lines. Numerous variables can be set here, but you’ll usually just need title. The title set here will be used as the main heading for the page, as well as in the browser tab.
The other important thing to recognise is the Markdown syntax. For example, where you see a line commencing with two hash marks:
##Do you know exactly how much of your tax money is spent on street lights?
This is the Markdown way of creating a level two heading. On the site it will be outputted like so:
Another common formatting requirement is bullet points, or lists. These are achieved in Markdown by using asterisks, like so:
* civil servants
* journalists
* politicians
giving you:
Links are created like so:
Give your data a home at the [Datahub](http://datahub.io/).
result:
Give your data a home at the Datahub.
To get a link to a specific heading on this site, hover over it then click the section icon [section icon]. This will put the URL into your address bar.
More Markdown examples can be found here, and a more detailed overview here.
If you are unsure of your markup while editing, you can switch to the preview tab [eye icon] Preview changes to see how it will be rendered.
The Github previews will look stylistically different from the live site. A different font will be used for example.
Once you are happy with your changes, add a summary of what you've changed in the field below the editable text. Then click ‘Propose file change’.
You will now be presented with a ‘pull request’ form. So far, the changes you have made are to your own copy, or fork of the handbook. A pull request simply sends a request to the authors/maintainers of the live handbook, asking them to include your changes - and put them live! Add any comments you have for the handbook team, then press ‘Create pull request’.
Your work here is done :) If you need to make related changes though, any new commits pushed to your branch will automatically be added to the pull request.