Tutorial: Creating new pages

This tutorial will describe how to create new pages and add them to your main menu. It will also cover some steps needed for multilingual implementations.

Topics covered¶

Jekyll pages
Markdown
Multilingual pages
Menu configuration

Level of difficulty¶

This tutorial is mostly about content, but does involve the editing of some configuration files. Anyone can follow the steps to complete the tutorial, however you will be using the YAML syntax involved in most Open SDG configurations. YAML requires particular indentation and spacing, so some attention to detail will be needed.

Decide on a new page to create¶

In practice, you will need to come up with the title and content for the new page. This may involve some content work, but for now we will just use example text.

Start a branch¶

Like many tutorials, we will be changing multiple files. So it is best to create a branch first.

In your site repository on Github.com, open the dropdown in the top left which says "develop".
Type "create-pages-tutorial"
In the dropdown select "Create branch: create-pages-tutorial from 'develop'".

This creates a branch called "create-pages-tutorial" and switches to that branch. We will be working on this branch for the rest of the tutorial.

Start the new page¶

In your site repository on Github.com, go into the _pages folder.
Press "Add file" and then "Create new file".
Name your file "example.md". Or substitute any other name, as long as it ends with ".md". This extension stands for Markdown, which will be discussed in more detail below.
After typing the name, click into the editor which is open below, in which you can proceed to the next section.

Add the page's "front matter"¶

The term "front matter" refers to a series of key/value pairs in YAML syntax, commonly used in Jekyll and other software. For more information, here is the Jekyll documentation on front matter and here is an introductory primer on YAML. However, these resources are not required for this tutorial.

With any Jekyll site your pages need to have a "front matter" section at the top. This section must be formatted in a certain way. In our case, it must have 4 particular "fields" (key/value pairs). Here are the steps:

Click into the body of the page (under "Edit new file").
On the first line, type three dashes: ---
On the next line, type the title field: title: This is my example title
On the next line, type the language field: language: en
On the next line, type the permalink field: permalink: my-example-page/
On the next line, type the layout field: layout: page
On the next line, type three more dashes: ---

Afterwards it should look something like this:

---
title: This is my example title
language: en
permalink: my-example-page/
layout: page
---

Let's go over what these fields do:

title: This is the title of the page. Feel free to change the value here as needed.
language: This is the language of the page, and should correspond to the correct language abbreviation.
permalink: This determines the URL for the page. It should end with a slash, and can have any number of slashes within it. For example, this is also fine: my/example/page/. Like any URL, it should not contains spaces. Typically dashes are used instead.
layout: This determines the Jekyll "layout" that is used, and should usually be set to "page".

Finally the triple-dash lines are important because they identify this section as "front matter".

Add the page's content¶

Now we can add the actual content of the page. This can be HTML code if you prefer, but typically is easier to use a syntax called Markdown, which is designed to be more human-readable than HTML. For details on using Markdown, here is a good Markdown guide.

For our purposes, we can use a simple example sentence:

This is my page content.

So, all together with the front matter we added earlier, you should have something like this:

---
title: This is my example title
language: en
permalink: my-example-page/
layout: page
---
This is my page content.

At the bottom select "Commit directly to the create-pages-tutorial branch".
Click the "Commit changes" button.

Multilingual: translated versions¶

If your implementation uses more than one language, then you may notice that the pull-request you have just created will result in failures in the automated tests. This is because the translated versions are missing.

If your implementation does not use more than one language, you can skip ahead to the "Add a menu item" section.

In Open SDG, the expectation is that every page will be translated into every language. To translate a page, you can simply create another copy of the file. For this explanation, let's assume we need to create a Spanish version.

This is nearly identical to the previous step, but we will put the file in a subfolder for Spanish pages: "es".

In your site repository on Github.com, make sure you are still in the create-pages-tutorial branch. If not, select in the dropdown on the top left.
Go into the _pages folder.
Press "Add file" and then "Create new file".
Name your file "es/example.md". (The "es/" is what creates the subfolder.)

As before we will add "front matter", but there will be three important differences:

The "title" will be translated into Spanish.
The language will be "es" instead of "en".
The permalink will be identical, but it will start with "es/".

So this time the front matter will be:

---
title: Este es mi título de ejemplo
language: es
permalink: es/my-example-page/
layout: page
---

Next we will add our Spanish content below. So for example, all together it might be:

---
title: Este es mi título de ejemplo
language: es
permalink: es/my-example-page/
layout: page
---
Este es el contenido de mi página.

Now we can add this change to our branch.

At the bottom select "Commit directly to the create-pages-tutorial branch".
Click the "Commit changes" button.

This step is not required, if you would like to add a link to the new page in your main menu, here are the steps:

In the root of your site repository on Github.com, make sure you are still in the create-pages-tutorial branch. If not, select it from the dropdown on the top left.
Go to the _data folder and click on site_config.yml.
Click the pencil icon on the right to begin editing the file.
Look for the menu section.
Add an item at the bottom of the list, using the same syntax and indentation as the others:
```
- path: my-example-page/
  translation_key: My menu item
```