contribute

Adding a page

Written by
  • Sam Smith

Most of what you need to know to add a new page is covered under 'Editing a page', so make sure you have first read through that section.

Adding a page follows a similar process to editing. Instead of locating your page, your first step is to locate your new page’s parent directory.

1. Create the page

First locate the parent directory, or folder, in which your file will live. If you are adding a page to the English language Handbook, for example, you should be in the ‘en’ directory, where you’ll see a list of all the Handbook pages.

Above the list of pages is a breadcrumb trail opendatahandbook / guide / en /, to the right of which is a plus symbol [plus icon]. Click the plus symbol to create your new page.

2. Name your file

You should now have a new file editor page open. The first editable section you are presented with is the ‘Name your file’ field. As we touched upon when looking at editing files, the file name corresponds to the URL of the page on the site. There are a few of rules to follow here:

  • The file name should reflect the title of the new page
  • Must be unique
  • Should be all lowercase
  • Words should be separated by hyphens (-)
  • File name should end with the extension ‘.md’ (the .md extension indicates a markdown file)

As an example, if you were creating a page titled ‘My Cool Page’, you would use a file name of:

my-cool-page.md

Assuming you are creating this in the ‘en’ directory, this would result in a URL of /en/my-cool-page

Note

The actual words used in your file name are not crucial. It's fine to use a more succinct version of your page title, for example.

3. Formatting your content

This step is the same as when editing a page. You need to start your file with the Front Matter, then add your content, formatting it using Markdown. Here is a template to get you started:

---
title: My Cool Page
authors:
 - Fred Bloggs
---

##A large introductory paragraph.

Regular paragraphs, separated by empty lines.

###A heading

Another paragraph.

 * Maybe
 * a
 * list

When you’re done, click ‘Propose new file’.

4. Make a pull request

Once you have created your page(s) and updated the contents document, you’re ready to make your pull request. Click the pull request icon to the right of the screen [git pull-request icon], then click ‘New pull request’.

At the top of the resulting comparison screen, you’ll see a row of select boxes. You want to make sure these are configured like so:

base fork: jjediny/opendatahandbook
base: gh-pages
...
head fork: username/opendatahandbook
compare: branch

username being your github username, branch being the branch you have been working on.

You should now be able to see listed below, all the changes that you wish to contribute. If everything looks as it should, click ‘Create pull request’.

Give your pull request a title and description, then click ‘Create pul request’. You have now contributed your pages to the Handbook :)