development / guideline / website /

Website syntax and formatting

This page describes the syntax and formatting for the FieldTrip website. The content of the website is maintained on https://github.com/fieldtrip/website and we have a complete tutorial that explains how to contribute. You can also use the GitHub web interface by opening a specific page page and clicking on the pen symbol (“Edit this file”) in the upper right corner.

The website pages are written in Markdown format, which are converted into html using Jekyll. The resulting html pages and css style sheets make use of Bootstrap.

This Markdown cheatsheet is a good place to start. It is also helpful to check the formatting in an online Markdown editor like https://stackedit.io or https://dillinger.io.

For more complex content and formatting, the Markdown pages includes sections in the Liquid makeup language. The Shopify Liquid cheat sheet is a good resource and the online editor https://liquidjs.com/playground.htm helps to develop and test code.

Frontmatter

The Markdown document should start with some so-called frontmatter, i.e., a short header between two lines with three minus characters each (not more and not less), including the title, tags, etc.

---
title: Website syntax and formatting
tags: []
category:
weight:
---

Title and headings

The page title as defined in the frontmatter is automatically used as the top-level (H1) heading. The Markdown document should therefore not start with a header using # ....

Each page should only have a single top-level H1 heading, and since that is automatically added, you should not use H1 level headers with # ... on any page yourself. You can and should use subsequent heading levels (## ..., ### ...), which will appear in the table of contents in the right column.

You should not use sub-headings if the corresponding higher level heading is not also present, i.e., it is fine to use headings at the levels H3, H2 and H1 (which is automatically added with the page title), but not H4 and H2, skipping H3 in between.

Table of content

The first (and only) H1 level header with a single # is automatically added based on the title in the frontmatter and is not shown in the table of content on the right. All subsequent headers are shown in the table of content on the right.

Weights

In the frontmatter you can specify a weight between 10 and 99 (i.e., it should consist of two digits) that is used to determine how pages are sorted in lists. Low weights appear at the top, high weights at the bottom. If a page does not have a weight, it will go all the way to the bottom. Pages that have the same weight will be sorted alphabetically.

Redirection

If you rename a page, the URL (i.e. the link on the web) that points to it will not be valid any more. That is problematic if that link is for example used in other documentation, on other websites, or in the email archive. To prevent broken links, you can redirect from the old page to the new page; this requires that you including redirect_from in the frontmatter of the new page. You can also use it to redirect links to multiple old pages to a new single page in which the documentation has been merged.

---
title: New page title
redirect_from:
  - /olddir/oldname/
---

Text block highlighting

This is implemented with small snippets of html code that are contained in the _includes/markup directory. They correspond to Bootstrap alerts. The syntax is like this

{% include markup/yellow %}
yellow
{% include markup/end %}

and it would show up like this

blue

gray

green

red

yellow

skyblue

white

darkgray

Code syntax highlighting

You can indent a single word in a sentence using three back-tics at the start and end. You can highlight a block with multiple lines by indenting the whole block with 4 spaces. You can also highlight a multi-line block by starting with three back-tics.

```
This would be formatted as MATLAB code.
```

The default syntax highlighter is for MATLAB. You can use other highlighting options as explained here.

```python
This would be formatted as Python code.
```

```bash
This would be formatteded as Bash command-line code.
```

and

```plaintext
This is formatted with a fixed-width font, but without color highlighting.
```

The last option is useful for MATLAB command window output, which in itself is not executable code, and for displaying sections of MATLAB help.

Line breaks

If you have a short piece of text, such as an address, that you want to appear over multiple lines without converting it into a list, you can add two spaces to the end of the line. This will cause explicit line breaks to be inserted.

Images

Since bitmap images can only be displayed inline in a Markdown document with the size (width and height) determined by the actual bitmap images, we are using a piece of Liquid code to insert resizable images. Whereas in Markdown you would to

Inline-style:
![alt text](path/to/image.png "Logo Title Text 1")

Reference-style:
![alt text][logo]

[logo]: path/to/image "Logo Title Text 2"

where the image is either local or a http link.

For the FieldTrip website you have to do

{% include image src="/assets/img/filename.png" width="300" %}

Please keep images in assets/img with subdirectories according to the place where the image appears. The preferred filename is figureXX.png, with XX being the sequential number of the image appearing on the page. The preferred format for screenshots is png. The preferred format for photos is jpg. Do not cross-link to figures from another tutorial or example, but copy that figure over (otherwise changes to the original page with the figure might break the page that cross-links to the figure).

Pdf documents

Pdf documents can be used on the FieldTrip website, but are not managed in git on GitHub. Since they are binary files and often very large (e.g., slides of presentations), storing them in git would be inefficient. Please send pdf files that you want to appear on the website to Robert, he will copy it to the server.

Videos

This is implemented with some small snippets of html code contained in the _includes directory.

You can include a Youtube video like this

{% include youtube id="S8l8Cw7ysis" %}

and a Vimeo video like this

{% include vimeo id="21604990" %}

News items

To show a news item on the front page, you have to add the news item as a Markdown page to _posts with the name YYYY-MM-DD-short-description.md. See the other examples in that directory.

Posts should not have any tags.

Recent posts that have the category ‘news’ are automatically shown on the front page.