How to post in the underworld blog

Sep 23, 2015

Examples of markdown format used in the underworld blog / website

Innards

Github will process web material with Jekyll to make a fully functioning website and that is how we deploy these pages. Most things are handled with templates but a few odds and ends are important to know about.

Format

All posts are written using the kramdown / github markdown (GFM) style. Basic markdown which is very similar to that used in the jupyter notebooks.

The backtick code block extensions for GFM don’t properly highlight in the web pages so we use the following

  

    <!-- highlight bash script -->
    {% highlight bash %}
    #! /usr/bin/env sh
    echo "Hello, World"
    {% endhighlight %}

which does this:

#! /usr/bin/env sh
echo "Hello, World"

And something in python

    #!/usr/bin/env python
    '''
      This example shows how you can add a set of particles to a swarm.
      Here the particles are layed out in a spiral configuration.
      Note that Scipy / Numpy are required for this example
    '''  
    import underworld as uw
    import Numpy

    # if that doesn't work, you did something very wrong

We have added mathjax scripting to produce equations

\begin{equation}
S \frac{\partial h}{\partial t} + H = -\frac{\partial }{\partial x}
\underbrace{\left( - K \frac{\partial h}{\partial x} \right)}_\text{flux}
\end{equation}

which look like this

\begin{equation} S \frac{\partial h}{\partial t} + H = -\frac{\partial }{\partial x} \underbrace{\left( - K \frac{\partial h}{\partial x} \right)}_\text{flux} \end{equation}

Note that, if you have underscores or stars or other markdown markup in the equation then you need to be careful

\begin{equation}
    r _0 = A x_ 0 - b
\end{equation}

Will not work because of the underscores being interpreted by the markdown parser before mathjax. Easiest trick is to separate them from the argument with a space (i.e. consistently on one side only).

\begin{equation}
    r_ 0 = A x_ 0 - b
\end{equation}

Images can be added using standard markdown or using the html <figure> tags. The latter allows more flexibility with captions, specification of figure widths etc. At the moment, we probably recommend something like this:

<figure >
    <!-- Add an href here and the image will be available in a page slideshow -->
	<a href="/images/posts/ScalingGraphs/UWScalingGraph.png">
    <img src="/images/posts/ScalingGraphs/UWScalingGraph.png"  width="100%"></a>
	<figcaption> Scalings for parallel Underworld 2 on the Pawsey supercomputer
    </figcaption>
</figure>
Scalings for parallel Underworld 2 on the Pawsey supercomputer

What goes where

The website is organised like this:

    underworld.github.io/
    ├── _includes
    |    ├── footer.html  //site footer
    |    ├── head.html  //site head (not used any more)
    |    ├── head-dark.html  //dark site head for light pages
    ├── _layouts
    |    ├── home.html  //homepage layout (like page but with built in list of blog posts)
    |    ├── page.html  //standard page layout
    |    ├── post-index.html  //page with comprehensive chronological listing of all posts
    |    ├── post.html  //post layout
    |
    ├── _posts //  "Dynamic" site content in jekyll blog format (markdown/html + yaml headers + date-naming convention)
         ├── YYYY-MM-DD-blog-post-name.md  // becomes /posts/blog-post-name on the site
         └── ...

    ├── pages // "Static" site content in jekyll blog formal  (markdown/html + yaml headers)
        ├──FAQ/           //  To keep linking simple, pages are directories with an index.md file
            ├── index.md  //  The index.md file becomes index.html and is auto-served by a link to FAQ
            └── ...       //  AnythingElse.md has to be linked as AnythingElse.html within the site (more complicated !)
        └── ...

    ├──  assets (exactly as Balzac)
    |    ├── css  //preprocessed less styles. good idea to minify
    |    ├── img  //images and graphics used in css and js
    |    ├── js
    |    |   ├── main.js  //jQuery plugins and settings
    |    |   └── vendor  //all 3rd party scripts
    |    └── sass
    ├── images  //images - path for images is to this directory by default
         ├── posts (images from blog posts)
    |    ├── pages (images included on specific pages)
    |    ├── site  (location for default images used across the site)

    ├── index.md     // site home page linked from "underworld" in the top menu
    ├──_ ...          // other files that will get deployed by jekyll

New posts are added to the _posts directory. They need to contain the yaml header (just use the template as a starting point). It is possible to switch off the comment stream, change the post image, and change the date in the header (which reflects updates). The yaml header can have any variables defined which can be picked up by jekyll and used in the logic of conditionals / variables etc.