datahub/examples/openspending/content/about/meta/contribute/editing.html

---
lang: en
title: Editing a page
authors:
 - Sam Smith
section: meta
---

<p class="lead">If you haven’t done so already, the first thing you need to do is head over to <a href="https://github.com/" rel="external">Github</a> and create your free account.</p>

<p>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. <strong>Method A</strong> is probably the simplest, and most likely way you’ll do it. <strong>Method B</strong> will serve as a primer for the next section: <em>Adding a page</em>.</p>

<h2>1: Locate the page</h2>

<h4>Method A: Browse the website</h4>

<p>While reading any section of the Handbook you’ll see an '<em>Edit this page</em>' link in the bottom left of the page. Following this link will take you directly to an editable version of that page. Easy huh?</p>

<div class="note">
  <h6>Note</h6>
  <p>When the editable page opens it will (most likely) contain a message saying <em>“You're editing a file in a project you don't have write access to”</em>. If this is your first edit to The Open Data Handbook it will say <em>“We've created a fork of this project for you to commit your proposed changes to”</em>. This is normal and part of the workflow.</p>
</div>

<h4>Method B: Browse the Github repository</h4>

<p>The entire file structure of this site can be browsed on Github. For example, the root of the site is <a href="https://github.com/{{ site.github_username }}/{{ site.github_repo }}" rel="external">here</a>, and the English language handbook section is <a href="https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/gh-pages/en" rel="external">here</a>. 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 <code>{{ site.url }}/<strong>en</strong>/<strong>introduction</strong>/</code> we know this file can be found in the <code><strong>en</strong></code> directory with the filename <code><strong>introduction</strong>.md</code> <em>Note: the extension (.md) is stripped from the URL.</em> Following these links you should see a preview of the page you wish to edit. From here click the edit icon <code class="icon-pencil"><span>[pencil icon]</span></code> to start editing.</p>

<div class="note">
  <h6>Pro Tip!</h6>
  <p>Press <code>t</code> on any tree or blob page to launch the file finder.</p>
</div>

<h2>2: Make your changes</h2>

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:

<pre>
<code>---
title: Introduction
---</code>
</pre>

<p>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 <code>title</code>. The title set here will be used as the main heading for the page, as well as in the browser tab.</p>

<p>The other important thing to recognise is the Markdown syntax. For example, where you see a line commencing with two hash marks:</p>

<pre>
<code>##Do you know exactly how much of your tax money is spent on street lights?</code>
</pre>

<p>This is the Markdown way of creating a level two heading. On the site it will be outputted like so:</p>

<h2>Do you know exactly how much of your tax money is spent on street lights?</h2>

<p>Another common formatting requirement is bullet points, or lists. These are achieved in Markdown by using asterisks, like so:</p>

<pre>
<code>* civil servants
* journalists
* politicians</code>
</pre>

<p>giving you:</p>

<ul>
  <li>civil servants</li>
  <li>journalists</li>
  <li>politicians</li>
</ul>
<br>
<p>Links are created like so:</p>

<pre>
<code>Give your data a home at the [Datahub](http://datahub.io/).</code>
</pre>

<p>result:</p>

<p>Give your data a home at the <a href="http://datahub.io/">Datahub</a>.</p>

<div class="note">
  <h6>Pro Tip!</h6>
  <p>To get a link to a specific heading on this site, hover over it then click the section icon <code class="icon-section"><span>[section icon]</span></code>. This will put the URL into your address bar.</p>
</div>

<p>More Markdown examples can be found <a href="{{ "/meta/contribute/markdown-examples/" | prepend: site.baseurl }}">here</a>, and a more detailed overview <a href="http://daringfireball.net/projects/markdown/syntax" rel="external">here</a>.</p>

<p>If you are unsure of your markup while editing, you can switch to the preview tab <code class="icon-eye"><span>[eye icon]</span> Preview changes</code> to see how it will be rendered.</p>

<div class="note">
  <h6>Note</h6>
  <p>The Github previews will look stylistically different from the live site. A different font will be used for example.</p>
</div>

<p>Once you are happy with your changes, add a summary of what you've changed in the field below the editable text. Then click ‘<em>Propose file change</em>’.</p>

<h2>3: Make a pull request</h2>

<p>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 ‘<em>Create pull request</em>’.</p>

<p>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.</p>