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.
Check out the repository, edit the pages under _posts, and push
commits. The published pages are on the master branch.
File name
Blog posts should be placed under _posts. These should have names
according to:
where YEAR is a four-digit number, and MONTH and DAY are both two-digit
numbers.
Meta data header of markdown files
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. You must put the title in
quotation marks if it contains special characters.
Other keys can be in the header (such as date (overrides file name date) or
order (for static pages)).
Section headers
- Do not put a title at the start of the post. The title from the metadata will
create the level 1 header.
- Do not use level 1 (
# ... #) headers, level 1 is reserved for the overall
title.
- Use level 2 (
## ... ##) or higher level headers.
Good to know
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:
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

Notes on using Jekyll
Absolute site links
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.
Note: Always put a slash / after {{ site.baseurl }}.
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.
Links to blog posts
Use the
post_url
liquid tag {% post_url FILENAME_NO_SUFFIX %}. FILENAME_NO_SUFFIX
is something like "2025-02-11-GSOC2024-final-blog" to reference the
file _posts/2025-02-11-GSOC2024-final-blog.md. Note that the .md
suffix is not included.
Prefix with the baseurl so you use it something like
See the [GSOC 2024 blog post]({{ site.baseurl }}/{% post_url 2025-02-11-GSOC2024-final-blog %})
for more details.
Liquid tags
One does not need spaces between the configuration variable and the
curly braces (i.e. {{ site.baseurl }}/ as typical seen). If you
find that your editor breaks the line inside the curly braces
(which upsets Jekyll greatly) then omit the space.
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
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=4.0
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. See INSTALL for notes on how to install Jekyll
locally.
Use the command
bundle exec jekyll serve --watch --livereload --future --incremental
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.
Running Jekyll locally has the advantage that you can have it update
the site continuously while you're editing files.
(See the serve commandline
options
for more details.)
For a full list of Jekyll commands, see the Jekyll
documentation.
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?