Contribute to this site

Overview

This page will be of interest to the collaborators interested in contributing to this site or involved in its maintenance. In many cases making a contribution can be as easy as editing a text file.

We use GitHub to manage the content and formatting for this site. Please take a look at the eAST repository, which is under the EIC Software Organization on GitHub to get an idea of the general organization of the data, layouts and supporing logic. The content and code for this website is in the docs folder of the repository.

At the time of writing we are taking advantage of the “GitHub Pages” functionality of GitHub, which provides hosting and automatic generation of web pages from the content of the docs folder using the Jekyll website generator.

Jekyll, Markdown and Liquid

The Jekyll website generator renders pages written in Markdown format, which is quite easy to read and edit since it’s just plain text for the most part. In a nutshell, the input for Jekyll is a collection of Markdown-formatted files and optionally some content formatted in YAML, and the output is a complete tree of HTML files representing the site to be served on the Web.

Markdown is widely used on GitHub and elsewhere to maintain README files so it’s familiar to most users. Jekyll expects a small section of YAML-formatted data on top of every Markdown page included in the website. It can be quite minimalistic, e.g.

---
title: My eAST Code
name: my_east_code
category: geant4
layout: default
---

In fact only two attributes are mandatory - the layout which specifies the template use to render the page, and name which is used to reference the page. Any number of templates can be created for use on the website.

If you decide to contribute to this website we strongly recommend that you install Jekyll on your machine. The workflow would then consist of

Since Jekyll is an application written in Ruby language installing Ruby is a requirement. Knowledge of Ruby is absolutely not required since all development takes place in the very basic Markdown and YAML environment. Installation instructions can be found on on the installation page of the Jekyll website. Once the installation is done, you can run a development web server locally. Assuming you are working on eAST documentation (this website), and your current folder is east, this is achieved as follows:

# Go the folder which contains the website materials:
cd docs
# This is done only once, after you clone the eAST repository, in order to install necesary dependencies
bundle install
# Finally run
bundle exec jekyll serve

At this point Jekyll has been started in the docs folder, and you can view the web site by pointing your browser to localhost:4000. Depending on the OS environment, for host name resolution to work, you may also need to specify the host address as 0.0.0.0. Also, when working in the WSL2 environment, please be aware that port 4000 is often blocked. In these circumstances, the above command line should be modified to:

bundle exec jekyll serve  --host 0.0.0.0 --port 8000

…and you would need to point your browser to localhost:8000 to view the locally generated website.

Changes made to files locally are automatically compiled and reflected on the displayed site (when the page is reloaded). The optimal workflow is to make changes and debug entirely locally before doing a ‘git commit’ and pushing to GitHub. Once material is pushed to GitHub the instance of the website hosted on that portal will be automatically recompiled and serve. This may take a few minutes.

Users who whish to develop or maintain templates for this website need to get basic familiarity with the Liquid template language. It is easy to read and learn.

Formatting

We aim to provide a uniform look and feel across the site.

Blockquotes are used to put emphasis on quoted text. The standard way of doing it in Markdown is to prepend the lines that need this formatting with the ‘>’ character. For example:

>Blockquote!

…will produce

Blockquote!

Language-aware code highlighting capability has been integrated and can be easily used via the fenced code blocks i.e. blocks delimited by triple backticks, with an optional shortcut for the programming language name. For example,

```bash
export foo="foo"
echo $foo
ls -l .
```

will be rendered as:

export foo="foo"
echo $foo
ls -l .

and

```python
def my_function():
  print("Hello from a function")
```

will show as:

def my_function():
  print("Hello from a function")

For C++, the opening line should be triple backticks followed by “c++” similar to examples above and the code will be rendered accordingly such as:

class MyClass {       // The class
  public:             // Access specifier
    int myNum;        // Attribute (int variable)
    string myString;  // Attribute (string variable)
};

Managing Data

Jekyll is a capable platform when it comes to storing and manipulating structured data. The data component of the site can reside in the “front matter” section of the Markdown-formatted files or in separate YAML (or JSON, CSV etc) data sources. The front matter approach works well for small sites. For scalability, it is recommended to rely mostly on dedicated data files (i.e. files in the “_data” folder) and keep the content of the front matter sections of individual MD files to a minimum.

YAML (and data in other formats) are parsed into data structures such as lists an arrays, providing an intuitive way for the developer to combine and process data using the Liquid template language. This is often done using macros which are technically include files but are semantically similar to functions. For example, this site contains a file named links.yml which provides a way to quickly generate URLs on pages using mnemonic names. This is done using this simple macro: link.md