Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mdanalysis/mdanalysis.github.io

MDAnalysis home page mdanalysis.org as GitHub pages.
https://github.com/mdanalysis/mdanalysis.github.io

Last synced: about 1 year ago
JSON representation

MDAnalysis home page mdanalysis.org as GitHub pages.

Awesome Lists containing this project

README 

          
# MDAnalysis Web Site #



The home page [www.mdanalysis.org](https://www.mdanalysis.org) is maintained as

a [GitHub pages](https://pages.github.com) site. The home page is also

accessible as [mdanalysis.github.io](https://mdanalysis.github.io).



Pages are generated from markdown files using the static site

generator

[Jekyll](https://help.github.com/articles/using-jekyll-with-pages/).



## General page authoring guide ##



- use [GitHub-flavored Markdown](https://github.github.com/gfm/)

- 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](#web-development) below.



## Blog [mdanalysis.org/blog](https://www.mdanalysis.org/blog) ##



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:



    YEAR-MONTH-DAY-title.md



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](#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](https://help.github.com/articles/mentions-on-github-pages/)

  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](https://github.com/poole/hyde) theme for

[Jekyll](https://jekyllrb.com/docs/).



### 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: ` 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](http://daringfireball.net/projects/markdown/) as processed by

[Jekyll](https://help.github.com/articles/using-jekyll-with-pages/).



The actual markdown processor is

[kramdown](http://kramdown.gettalong.org) so it parses more than basic

markdown --- see the

[kramdown syntax](http://kramdown.gettalong.org/syntax.html),

including MathJax.



### Images ###



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



```html

  alternative text

   ```



or use Markdown

```markdown

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

```



### 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](https://jekyllrb.com/docs/liquid/tags/#linking-to-posts)

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

```markdown

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](https://help.github.com/articles/using-jekyll-with-pages/) 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:

```bash

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

```bash

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](INSTALL.md) 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

. 



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](https://jekyllrb.com/docs/configuration/options/#serve-command-options)

for more details.)



For a full list of Jekyll commands, see the [Jekyll

documentation](https://jekyllrb.com/docs/).



##### 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](https://help.github.com/articles/setting-up-your-pages-site-locally-with-jekyll/#keeping-your-site-up-to-date-with-the-github-pages-gem)

with



    bundle update github-pages



##### Problems with jekyll and required packages? #####



* See [INSTALL](INSTALL.md) and if in doubt, follow the latest instructions from

  [GitHub: Testing your GitHub Pages site locally with

  Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll)

  and in particular [Jekyll's installation

  instructions](https://jekyllrb.com/docs/installation/)



* **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.