GraphStream uses GitHub Pages to manage its documentation. The GitHub Pages process combines a git repository containing your documentation and the Jekyll platform to create a website from this documentation. The latter is written using the Markdown markup language (but you can use HTML directly). For example, just have a look to the source of this tutorial.
Writing Your Document
First you have to decide a few things :
- Title of your document ;
- Where your document belongs into the documents hierarchy, it will be called document path. This one belongs to the
File containing your document should be named after the document title, with no space, only word characters, and
- between words. Use the
.md extension and put your file inside the directory linked to your document path.
Jekyll uses file headers to identify which files should be processed. Headers should start at the very beginning of the file (first characters) with
--- on a single line, and have to end with the same
--- chain. Between these two lines will come some meta-informations about your document. There is one information by line, on the form
The basic header you will have to set is :
--- title: Your Document Title docpath: YourDocumentPathName|/your/document/path layout: documentation permalink: /your/document/path/Your-Document-Title/ ---
layout information is used to tell Jekyll the template that will be used. You can add other informations like
Referencing your document
We have to tell files contained in each section. Jekyll will have later a feature called
collections, but this is actually unstable. So you have to do the job.
List of files in a section are stored as
data. Jekyll stored these data, which are YAML file, in the
_data directory. If we consider the Tutorials section, we can find the
_data/doc/tutorials.yml file, listing all document in this section. Name convention is :
- to use lower case ;
- to use
snake_caseto format each path component ;
- to use
-between components, ending the file with
For example, if we consider the FAQ section about the graph class
/doc/FAQ/The-Graph-Class, we should put list of files in this section in the data file named
Have a look to the existing files to become familiar with the YAML syntax. There are two main lists in these files,
documents. The former to reference subsections, and the latter to reference documents. Inside these lists, each entry has two items,
Before performing a pull request on the git repository, you should test your modifications locally. You will need the ruby tool called
Bundler will help us to manage the ruby part of this. You can install it using
gem install bundler. Then, inside the root of the git repository, create a file called
Gemfile and put the following content inside :
source 'https://rubygems.org' gem 'github-pages'
You may have to install other gems like
jekyll-redirect-from. These gems are used by the GraphStream website.
To launch your Jekyll server, just run
bundle exec jekyll serve. It will generating the website (in the
_site directory), and create and http server at http://localhost:4000. Jekyll is listening to file changes, so you should not have to restart it after making some changes.