Site Contribution Guide

Table of Contents

Preliminaries


The site uses Jekyll to parse Kramdown files in to HTML which can then be hosted. To edit the site, you will need access to the GitLab repository used to host the site. For access to this repository please contact lewis.christiansen@gmail.com. Once you have access simply clone the directory, make your changes and push to the repo. All the Jekyll site compilation is done server side, you simply need to provide the markdown files.

It would be of benefit to read through the Kramdown documentation here to get an idea of what is used on the site and what is possible. Some syntax in this guide is specific to the site and will be detailed however some more general syntax will not be explained as the aim here is to outline the formatting rules. Should you wish to know what specific syntax elements are doing, refer to the Kramdown documentation linked previously.

Site Formatting


General Document Style

The document should start with a “Purpose” section and a “Preliminary” section, where “Purpose” contains the purpose/aims of the tutorial and “Preliminary” contains the prerequesites, recommended reading or guidelines that should be read before progressing with the tutorial. Next should be the content of the document, split up in to short and easily followed sections (large tutorials and documents should be split in to multiple smaller tutorials and documents where possible). An ‘Other Resources’ section can be supplied if there are tutorials/papers/other useful documents that are relevant to the current document. An ‘Issues or Comments’ section can be included with contact details should the reader have an issue or suggestion about the document.

Tutorials, unless they are very involved (e.g. the DMFT tutorial) should have a “Command Summary” section that assembles all the commands in the tutorial together in one place, for quick reference. Thus tutorials generally should contain the following sections, in order shown. You can use the basic lmf tutorial for a template.

Purpose
Table of Contents (optional)
Preliminaries
Command summary (optional)
Tutorial/Documentation
Other Resources (optional)
FAQ (optional)
Additional Exercises (optional)
Table of Contents

Documents with multiple references or subsections should contain a table of contents, usually before any other text. Jekyll/Kramdown has support for auto-generating this ToC as shown here:

### Table of Contents
{:.no_toc}
*  Auto generated table of contents
{:toc}

Adding the

{:.no_toc}

flag directly under a header will exclude that category and its subcategories from the ToC autogeneration.

Front Matter

Front matter is always placed at the top of *.md files. Jekyll uses this data to format the page in question. More information on the capabilities of the Front Matter can be found here. The Front Matter used, for example, this page is:

---
layout: page-fullwidth
title: "Site Formatting Guide"
permalink: "/formatting/"
header: no
---

Here we can see that our title is “Site Formatting Guide” which you can verify yourself above. Our link is also “/formatting/” which, if you check your current url, should also agree with the config.

An important note about the permalink: This is where your file is found on the site. To give an exmaple, lets say you have a file test.md which has a frontmatter with

permalink: "/tutorial/lmf/"

When trying to find your tutorial on the site, you will not find it under

/test.md/ or /test/

But rather, you will find it under

/tutorial/lmf/

Which is what we defined in the front matter. Of course, these variables should be tailored for the page in question.

A skeleton file, containing the basic structure and a non-configured front matter is included in the repository and acts as a good file to start a new tutorial in. It can be found in assets/download/examples/skeleton.md.

The site does not naturally use folders due to how Jekyll works. However to simulate files and pages being in different folders, enabling easier navigation or just simply looking better, we can use the “permalink” to pretend that our file is within a folder.

Jekyll will allow a permalink such as

/test/tutorial/

Just as much as

/tutorial/

The site utilizes this functionality by grouping documentation and tutorials together, and further subdividing them by dropdown level. Lets construct a permalink. We have a file lmf_dos.md which is a tutorial that we would store in the lmf section of the tutorial dropdown (if you navigate to the site here and hover over “Tutorials” you will see a “lmf” section, this is where we would like our file to show).

If we click on a tutorial in the Tutorial>lmf dropdown, we will see that it’s url starts with “/tutorial/lmf/”, as would be expected. So to construct our front matter, we will start with “/tutorial/lmf/” and add our desired identifier at the end. In the end, our front matter may look something like

permalink: "/tutorial/lmf/dos"

The url prefixes of the different sections can be found in the _data/navigation.yml file, under the section “prefix”. To give a few common examples:

Section Parent Prefix Resultant URL
Documentation - /doc/ /doc/
Input Files Documentation /input/ /doc/input/
Tutorials - /tutorial/ /tutorial/
LMF Tutorials /lmf/ /tutorial/lmf/
DMFT Tutorials /dmft/ /tutorial/dmft/
Front Matter: Using The Auto Generator

The Questaal site uses an automatically generated tutorial overview page and the physical application page, see here and here. To have these pages generate automatically, you must include some information in the frontmatter, namely:

auto:
    code: "code"
    physical: "Physical Application"
    info: "Short sentence describing the file's function"

The end result would look something like:

---
layout: page-fullwidth
title: "Density Of States"
permalink: "/tutorials/lmf/dos/"
auto:
    code: "lmf"
    physical: "Calculating DOS"
    info: "This tutorial demonstrates how to calculate density of states with lmf."
header: no
---

If a new code is detected (for the code functionality page) or a new physical is detected (for the physical application page - this also indexes by code and will create a new category for that too), the page will automatically create a new category for it, so it’s best to use the same headers as everyone else! You should generally use ‘code’ as the lower-case code acronym the code is related to (e.g. ‘lmf’, ‘lm’) and ‘physical’ as a short title of the application (e.g. “Partial DOS”, “Spectral Functions”).

The info should be relatively short and serve as a descriptive summary of what the file does, paying special attention to any specifics the tutorial might cover that aren’t covered elsewhere (so people can ctrl+f the page for specifics). Also note, the info cannot be formatted, so normal Markdown formatting, e.g. **bold** will not work.

Headers

Headers are nested automatically in the table of contents generation by number of # used. Generally, the site uses ### for primary headings and an extra ## for each subheading under that. For example, your primary heading may be ###, a subheading ##### and a subheading under the first subheading #######.

Colours

The site uses colours to denote certain things. Blue is used for program/package names, terminal commands and scripts, such as the lm package or the console command cd. Green is used for directories or files, such as the ctrl.si file. Red is used for important points such as a Note:. Colouring items can be achieved with:

**Placeholder Text**{: style="color: blue"}

“blue” can be changed to “red”, “green” or any standard colour. Note that to colour a string (with or without spaces) there must be a text emphasis element (such as _ _ or ** ** etc) surrounding the string.

Text Emphasis

Bold is used for programs/package names, noteworthy points (Note:) and the names of input file tags (e.g. SITE_ATOM_POS). Italics are used for directories, files, headers and scripts (or uncompiled programs, i.e. not executabels).

Text Emphasis And Colours: A Summary

Here we have a table of combinations of text emphasis and colours that should be applied throughout the site for each given object.

Note: This list should contain all of the commonly needed formatting rules, if some are missing please contact us and let us know. There may be some niche cases that aren’t covered here, if you find one feel free to contact us and we can include it in the table.

Item Text Emphasis Colour Result
Directory _italic_ green directory
File _italic_ green file.md
Source Code **bold** green bndasa.f
Input File Tags **bold** None SITE_ATOM_POS
Scripts and Subroutines _italic_ blue script.py
Package Names **bold** blue lmf
Terminal Commands **bold** blue ls
Note _italic_ red Note:
Warning **bold** red Warning:
Code Blocks

Code blocks, as would be expected, should be used for any code, input or outputs (such as the ctrl.si input file), terminal commands and general instructions. Code blocks are always on a new line so it is not suitable if inline text is desired.

Code blocks can be defined with either a 4-space indentation relative to the current indentation (so if your block of text has a 4-space indentation already, your code block would need to be 8-space). Code blocks can also be denoted with ~~~ at the open and close of a block.

~~~

Code here

~~~

Drop down boxes allow for hiding of information unless the user manually opens it, enabling tutorials and documentation to be condensed and easier to follow while not removing information. Drop down boxes are not included within standard Kramdown formatting and are implemented with html. Below is a syntax example for the dropdown box, where the dropdown shows the syntax for the box itself:

{::nomarkdown}<div class="dropContainer" data-name="Drop Down Boxes">{:/nomarkdown}

Content

{::nomarkdown}</div>{:/nomarkdown}

This can simply be used by copying the syntax, replacing data-name with the text to appear on the button, and replacing the Content with whatever you want to show!

Math

Mathematical expressions can be added in-line within the markdown files by enclosing the equation in double dollar signs:

inline $$math$$ example

Or in their own blocks with double dollar signs and at least one empty line above and below:

Display style, is when

$$the expression$$

is surrounded by blank lines, and

$$
    this
$$

also works.

The expression itself is in standard LaTeX syntax. If you are not familiar with LaTeX equation formatting, more information can be found here. Keep in mind the specific renderer used KaTeX is not a complete implementation but it does strive to provide the commands with otrthogonal functionality. If a particular command is missing lookup the available equivalent.

Images

Images can be used on the site if so desired. They can be shown by using

[image hover text](http://imageurl.svg)

Where the hover text is the text you want to appear when a user hovers over the image, and the url is the url that points to the domain hosting your image. While this is not a strict requirement, images should be in *.svg format where possible. It is also possible to host your images, and other files, on the site. See below for more information.

Lists

To format a list in kramdown one must either use the characters - and * for an unordered list or numbers for an ordered list. The difference being, an ordered list will automatically increment as new elements are added (starting at 1, regardless of what number you started your list at) whereas unordered lists will act as simple bullet points. To initialize an unordered list you do:

* List element 1
* List element 2
...
* List element n

Starting the line with an unordered character, with one space after it, defines the list. The same goes for an ordered list:

1. List element 1
2. List element 2
...
n. List element n

With the difference being that for an ordered list, the number must be succeeded by a full stop.

Tables

Creating a table in kramdown involves first defining the headings. This can be done using the | character between each heading:

Heading 1 | Heading 2 | Heading 3

We follow this by defining the line as an actual heading line, this can be acomplished by ‘underlining’ it, using the following line under our heading line:

- | - | -

Where the number of - correspond to the number of headings. Finally we have our data lines situated under the ‘underline’:

Data 1 | Data 2 | Data 3
Data 4 | Data 5 | Data 6
...

Giving a final table that looks something like:

Heading 1 | Heading 2
- | -
Data 1 | Data 2
Data 3 | Data 4
...
Using HTML

Generally we want to avoid the use of HTML within markdown files - the idea behind using markdown is to make it readable in raw text as well as nicely formatted when parsed, HTML obviously goes against this goal. However, if what you want to do is impossible to do in markdown, and you deem it neccessary to the document (stylistic things can still be ‘neccessary’), HTML can still be used.

To use HTML, enclose your HTML in the nomarkdown brackets:

{::nomarkdown} html here {:/}

Note: Jekyll will not parse any markdown within these tags. If you want to use markdown style formatting, you must close the nomarkdown tag before writing any markdown, and reopen it where your closing HTML tag is found (see the dropdown boxes as an example). The other option is to use HTML-style formatting, which will work fine within these tags, although that raises the obvious problem of making the raw text harder to read.

Do not use HTML for math and especially html codes for symbols as as these are nearly incomprehensible in plain text and this violates one of the basic objectives.

Making Changes

Using Git

The site is currently hosted on GitLab and git is used to manage the site and upload changes. The below text will provide instructions to allow contributions to the site.

Actually making changes, for those of you unfamiliar with git, is fairly simple. It is best achieved with git installed on your machine, more information can be found here. There are two ways to make a change:

First, you can request full write access to the repo, and push your changes as you normally would. Otherwise, you can request fork (read) access and fork a copy, which will allow you to make changes locally and request a merge of your changes with the master branch. This is probably the better idea if you’re worried about breaking something, as whoever approves your merge will be able to see all changes. Before using git locally however, you must first navigate to the repo page, sign in with your GitLab account, and fork the repo. This will create a server-side clone of the repo on your own account, allowing you full edit writes. At this point, if you prefer the command line, you can clone your repo:

git clone https://gitlab.com/youraccount/yourrepo.gitlab.io.git site

With youraccount and yourrepo pointing to the correct names. This will clone the site’s files in to the site folder. You can now make your changes or additions to the site source files. When these are completed, we must add the file to the index for committing. The following commands assume you are working from the repository directory.

git add *

You can also add files individually

git add [filename]

With the files indexed, we can now set up the commit

git commit -m "Commit message"

Where “Commit message” should be a useful message to let other people using the respository know what you are committing.

Finally, we can commit the changes

git push origin master

You may be asked for username and password details, fill these in all should be fine.

With your local repo updated with changes you would like to push to the main repo, you can use GitLab’s pull request function. This will notify the site developers that you wish to merge your changes with the main site, on which they can review the changes and hopefully approve them. You can continue working on your local branch and create pull requests whenever you have changes you think are large enough to require another merge. With this method, however, you will not be able to see your changes on the site until a pull request is made. The next section details how you can locally view the changes to ensure the site compiles properly and you have not made mistakes.

It would be useful to also email the site developers directly with your pull request to let them know who you are and what changes you are making. It also allows us to respond with feedback should the request be denied. Check out the contact page for more information.

Should you instead prefer to get full write access to the master repository, and you are successful doing so, the editing instructions are the same as above except where above you are committing to your own repo, you are instead committing to the master repo, so the urls you use should be changed accordingly.

Hosting Locally

With either methods, it is a good idea to build and host the site locally so you can find any errors you have made, potentially avoiding having a large number of commits to fix something minor (its quicker, too). The site can be built and hosted locally for you to check errors, formatting and the like.

Installing Jekyll

To do this, ensure jekyll is installed on your machine, the official guide can be found here, we will however go over some brief instructions.

To install jekyll and related plugins, you need to have Ruby and RubyGems installed (there are many guides for this, dependent on your system, a quick google will surely find you something). With these installed, you can install jekyll with (in the command line):

gem install jekyll

jekyll also needs some plugins that the site uses installed, to get these:

gem install jekyll-paginate

The repo also contains a GemFile which will install these two gems through bundle, we won’t go through this here though.

With jekyll now installed, you can either build the site html for hosting elsewhere, or host with jekyll’s built in webserver. To build without hosting, simply

jekyll build -tVd _site

From within the repository’s directory. This will produce a _site folder which contains the compiled html files for the site. To host the site locally

jekyll serve -tVd _site

(Note: you could run either command as ‘jekyll build/serve’ without the tags, however these tags replicate how the site will be built on GitLab, so this way you ensure compatibility) This will create the same _site folder, but will also host the website locally. Read your terminal output for the address of the site.

You could also use the command

jekyll serve -VItd _site

Which will speed up your build time after each file change quite drastically (it has some drawbacks, but it’s unlikely you will run in to them).

Note: The default .gitignore file will ignore _site files, but if yours for some reason doesn’t work, please make sure, before committing your changes to the repo, you delete the _site folder so as to not clutter the repo unnecessarily.

Adding To The Navigation Bar

When you have created a new markdown file in the /pages directory, you will need to edit the navigation.yml file, which can be found in the _data/ directory, to ensure it appears in the navigation bar.

To do so, find the permalink section of your file (in the front matter at the top) and take a note, we will use this as the nav file link. Open the navigation.yml file and you will see the structure, taking particular note of the indentation. To add a new field, find the category you want your new page to be listed under (tutorial/, docs/, tutorial/lmf/, etc) and add a new entry. A new entry simply looks like:

- title: "Page Title"
  url: "permalink"

Specifically, the ‘title’ and ‘url’ text must be aligned as in the example. The page title can be anything you want but ‘url’ must be the permalink you noted above enclosed in quotation marks. When adding this new entry to the file, ensure that all indentation is preserved (see the file for a proper example) as it will not compile otherwise.

Hosting Files

Images, input files and whatever other files your tutorial or documentation needs can be hosted on the site, provided they are not too large. Files stored in the assets/download/ directory in the site source will be accessible on the site. Simply upload your file to the relevant folder, be that img, inputfiles etc. If a category does not exist, feel free to create one with a relevant name.

If your file is too large, contact us and we can look at other options. To actually commit the changes to the site, follow the making changes guide above; uploading your extra assets is as simple as committing any other file.

Debugging Your Local Builds

If you decide to build and test locally (you should!) then finding errors is easy. When you are hosting your Jekyll server, simply right and click ‘inspect’ (Note: these instructions work for Chrome, but should be similar for most modern browsers, a quick google will be sure to find you the exact instructions) and check the errors/console tab. More times than not, if your math isn’t parsing, or an image not showing, the console will have the reason why.

If this doesn’t help you to debug your file, either try and rework it to avoid the error or, if the erroring part is essential and can’t be rewritten, contact one of the site developers for help.


Edit This Page