MDAnalysis Web Site

The home page www.mdanalysis.org is maintained as a GitHub pages site. The home page is also accessible as mdanalysis.github.io.

Pages are generated from markdown files using the static site generator Jekyll.

General page authoring guide

• use GitHub-flavored Markdown
• use utf-8 encoding
• The top-level heading (h1) is set by the title: attribute in the front matter of each page.
• In-text headings start at h2, i.e., ## heading title ## in Markdown. There should not be any h1 headings inside the page.

For further notes see Web development below.

Blog mdanalysis.org/blog

Check out the repository, edit the pages under _posts, and push commits. The published pages are on the master branch.

Blog posts should be placed under _posts. These should have names according to:

YEAR-MONTH-DAY-title.md

where YEAR is a four-digit number, and MONTH and DAY are both two-digit numbers. Each post should have a header with:

---
layout: post
title: The title of this post
---

in order for it to be picked up by the paginator. The blog directory should not be touched, as this is only here to set the paginator.

• The _site directory is generated by Jekyll on the GitHub server side and should not be included in commits.
• You can sign posts with your @mention and it will link to your GitHub profile.
• If the date on a post is in in the future at the time of the commit, it will not be built and will not appear (until the next commit on or after the time of the post).

Web development

We are using the minimalist Hyde theme for Jekyll.

Static pages

Additional static pages go under pages. If they have the layout type "page" they will be automatically included in the sidebar. The static "about" page is left at the top level.

To customize the order of pages in the sidebar, add the attribute order: <INTEGER> to the front-matter. Pages will be sorted lowest to highest. Note that some entries in the sidebar are hardcoded in _includes/sidebar.html.

If a page should not show up in the sidebar, use layout: otherpage.

Creating content

There are two ways to add and edit files:

• Check out the repository, edit the pages, and push commits. The published pages are on the master branch.
• Use the add file/upload file and edit file functionality in the https://github.com/MDAnalysis/MDAnalysis.github.io repository web frontend.

Mark-up format: Markdown

The GitHub pages can either use HTML or markdown as processed by Jekyll.

The actual markdown processor is kramdown so it parses more than basic markdown --- see the kramdown syntax, including MathJax.

Images

Drop images into the public/images directory and include them like

  <img src="{{site.images}}/imagename.png"
   style="float: right" alt="alternative text" width="30%"/>

or use Markdown

![alternative text]({{site.images}}/imagename.png)

Notes on using Jekyll

For links between pages to work, generate absolute links with site.baseurl liquid tag:

[see citations]({{ site.baseurl }}/pages/citations

The example will link to the file /pages/citations. Also note that one does not need spaces between the configuration variable and the curly braces (i.e. {{ site.baseurl }}/ as typical seen), so I avoid them to prevent the editor breaking the line inside the curly braces (which upsets Jekyll greatly).

We define additional variables in _config.yml and use them with liquid tags. In particular, the sidebar _includes/sidebar.html is configured with additional links that are all stored in the config file.

Local testing

To locally test that your edits look ok before pushing them, run Jekyll from a docker container (always works if you can get docker to run) or install Jekyll as described in the docs (can be frustrating because of broken dependencies).

Using docker container for local builds

Running Jekyll from a docker image:

• on Linux you should be able to start/run docker after installing the appropriate docker package through your package manager
• on MacOS
  • install Docker Desktop https://docs.docker.com/desktop/install/mac-install/ and let it install all kind of startup items
  • start Docker

Follow the solution from https://stackoverflow.com/a/58850151/ as described next:

To build the static site, run jekyll build inside docker:

export JEKYLL_VERSION=3.8
docker run --rm \
  --volume="$PWD:/srv/jekyll" \
  -it jekyll/jekyll:$JEKYLL_VERSION \
  jekyll build

The static site files are stored in the _site directory.

Then you must serve the site so you can view them in a web browser

python -m http.server --directory _site 4444

(You can leave out the port number and then it defaults to 8000.)

Point your browser to http://localhost:4444

When you make changes, you need to re-build the site.

Note that the CSS is only rendered correctly when the pages are served. Just directly browsing the files will not show the site as it will appear on the web.

Build site locally

To run Jekyll in a way that matches the GitHub Pages build server, run Jekyll with Bundler. Use the command

bundle exec jekyll serve

in the root of your repository (after switching to the gh-pages branch for project repositories), and your site should be available at http://localhost:4000.

For a full list of Jekyll commands, see the Jekyll documentation.

Advanced Jekyll usage

Running Jekyll locally has the advantage that you can have it update the site continuously while you're editing files:

bundle exec jekyll serve --livereload

In this way, the site is immediately rebuilt when you save changes to a file.

Updating the github-pages plugin

If you try out new functionality or plugins locally and you get error messages then try to update the github-pages plugin with

bundle update github-pages

Problems with jekyll and required packages?

• Problems with installing jekyll/github-pages? If the standard installation for jekyll does not work for you (many people complain, for instance, commonmarker does not install https://stackoverflow.com/questions/58849651/bundler-cannot-install-commonmarker) try a docker container, as described above.

• In case the you get an error that a javascript environment is missing, install a javascript environment like nodejs from your distribution repositories.