Getting the gh-pages

If you want to add a new documentation section you first need to get the website source from GitHub. The source is stored directly on the GitHub nptool repository, in a specific branch named gh-pages. GitHub automatically rebuilds the website after each commit onto this branch and the changes are visible only a few minutes after the commit. It is therefore important to check your changes locally first, and then to push them to avoid breaking the website.

To get the pages you will need to clone the gh-pages branch in a new directory:

$ mkdir gh-pages
$ cd gh-pages
$ git clone https://github.com/adrien-matta/nptool -b gh-pages
$ cd nptool

Getting Jekyll

You now have a local copy of the source. To preview your work you will need the version of Jekyll use by gh-pages (and therefore the gem utility):

  
$ gem install github-pages

Setting up locally

In order for your preview to be done locally, edit the file _config.yml by commenting line 8 and uncommenting line 9:

BEFORE:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
  
# Site settings
title: nptool
email: a.matta@surrey.ac.uk
description: > # this means to ignore newlines until "baseurl:"
nptool, a Root and Geant4 framework for analysis and simulation of nuclear physics experiement.

baseurl: "" # the subpath of your site, e.g. /blog/
url: "http://nptool.org" # the base hostname & protocol for your site
#url: "" # use this line when using jekyll serve to preview locally

github_username: adrien-matta/nptool

# Build settings
markdown: kramdown
include: [_manual]
source: ./
safe: true
lsi: false
# Defining collection
collections:
manual:
output: true
permalink: /manual/:path/
show_in_nav: false

AFTER:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
  
# Site settings
title: nptool
email: a.matta@surrey.ac.uk
description: > # this means to ignore newlines until "baseurl:"
nptool, a Root and Geant4 framework for analysis and simulation of nuclear physics experiement.

baseurl: "" # the subpath of your site, e.g. /blog/
#url: "http://nptool.org" # the base hostname & protocol for your site
url: "" # use this line when using jekyll serve to preview locally

github_username: adrien-matta/nptool

# Build settings
markdown: kramdown
include: [_manual]
source: ./
safe: true
lsi: false
# Defining collection
collections:
manual:
output: true
permalink: /manual/:path/
show_in_nav: false

IMPORTANT: This change will need to be reversed at the end.

Generating a preview

Start the Jekyll server in a terminal. The server will provide a local image of the website and will keep looking at changes to update the page:

$ jekyll serve

If the build is successful it will be available for preview in your web browser, usually at the address 0.0.0.0:4000 (it may sometimes differ but Jekyll should warn you). If the build fails Jekyll will show messages in red telling you what the error is.

Adding a new page to the manual

To create a new manual entry simply create a new file in the folder _manual. For example:

$ vim _manual/NewSection.md 

The file needs to start (do not leave blank line at the top) with a specific header:

---
layout: manual
title: Your title
permalink: /manual/your-title/
author: your name
manual_order: 202
show_in_nav: false
---

Those four lines allow the website to know that your page goes in the manual category, the title under wich it should be displayed in the manual, the path that will be shown in the address bar, and that the page should not be shown in the top navigation bar. The manual order allow to place correctly the manual entry in the menu, i.e. the bigger the number, the later it will show up in the menu. The ordering number does not need to be continuous, so we setup large jumps in number for each of them, allowing easy addition in the future. The annexes, such as this page, start at 1000 with increment of 10. Normal entries, use increment of 100 starting from 0.

After that, the format of the text is Markdown, that uses easy to read marking to specify title and headings. Here is a small example of a file showing off some basic functionnalities:

---
layout: manual
title: Showing-off
permalink: /manual/showing-off/
author: your name
show_in_nav: false
---
# Showing-off basics

## SubHeading

### SubSubHeading

#### SubSubSubHeading

## Typing some text

Just type your text!

## Highlighting code and command:

A Console line:
{% highlight console %}
$ git pull
{% endhighlight %}

A Console line embbeded in the text `$ git pull` is easy as well.

Some cpp code:
{% highlight cpp %}
ClassBase* A = new ClasseA();
delete A;
return 0;
{% endhighlight %}

And the same with line number:
{% highlight cpp linenos%}
ClassBase* A = new ClasseA();
delete A;
return 0;
{% endhighlight %}

Commiting your changes

You first need to revert the changes in _config.yml:

$ git checkout _config.yml

Then, add your new file to the repository:

$ git add _manual/NewSection.md

And eventually commit the change:

$ git commit -a
$ git push