Editing a page
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.
1. Locate the page
Method A: Browse the website
While reading any section of the Handbook you’ll see a button with the paper icon
[paper icon] Improve this page in the right side or bottom of the page, depending on the size of the screen. Hovering over it then clicking an ‘Edit on Github’ button 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 need to fork this repository to propose changes.". If this is your first edit to The Open Data Handbook there will be a 'Fork this repository and propose changes' button. This is normal and part of the workflow. Click the button to start editing.
Method B: Browse the Github repository
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 guide section of the Handbook 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 Open Data Guide introduction page, given that it’s URL is
http://opendatahandbook.org/guide/en/introduction/ we know this file can be found in the
guide/en/introduction directory with the filename
index.md 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.
t on any tree or blob page to launch the file finder.
2. Make your changes
With the editable content in front of you, you’re probably either thinking “great, let’s get editing”, or “hang on, this looks a bit weird”. In case it’s the latter, let’s have a closer look. The first thing to recognise is the ‘Front Matter’, which will look like this:
--- 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:
Do you know exactly how much of your tax money is spent on street lights?
Another common formatting requirement is bullet points, or lists. These are achieved in Markdown by using asterisks, like so:
* civil servants * journalists * politicians
- civil servants
Links are created like so:
Give your data a home at the [Datahub](http://datahub.io/).
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 show you the URL.
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’.
3. Make a pull request
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.