Tutorial¶

You should get a grip of things running through this tutorial (there’s not much to get), but if you want to know more, please refer to the Documentation.

Assumptions¶

This tutorial and indeed Bade itself are written with a few assumptions.

You intend to serve from /

You’re in a *nix shell

You’re using Python 3.x

You’re in a Git repo

Of course you are!

Setup¶

Bade is configured by YAML file (vaguely inspired by Grunt) which holds something like a site map and paths to template and asset directories. The default name for Bade’s configuration YAML is bade.yaml [1], so let’s create that file and add some basic configuration:

blogtitle: Blog
pages:
  - pages/about-me
  - github: https://github.com

We’ve specified two pages, one is a local “about” page and the other is an external link to github. The first is a string pages/about-me and tells Bade there is an rST document pages/about-me.rst that should be rendered and added to the site navigation list, the second is a mapping of name to URL which should also be added to the navigation list, but since it’s an external link no rST needs to be rendered. The order pages are specified in the YAML is significant; it’s the order they will be rendered in the navigation list. In the next section we’ll create our “About me” page.

[1]	You can call it something else and specify that on the command line

Pages¶

Pages are rST documents that want to be rendered and added to the site, but not included in the blog. Links to them are provided in the context to all templates (we’ll get to Templating).

Let’s make a pages directory and put a page there.

mkdir pages
touch pages/about-me.rst

And throw some rST in that file.

About me
########

I like biscuits, especially custard creams.

This is the page that is referred to in our configuration YAML:

pages:
  - pages/about-me

Add all this stuff to Git and commit it:

git add pages bade.yaml
git commit -m 'Added about page'

The title of the page is derived from the file name, in this case the file about-me.rst will be titled About me. This holds for posts too.

We could render our site now, but let’s add a post first ...

Posts¶

Posts are almost the same deal as Pages, except they must appear in a directory structure like looking like this (it’s used as a faux index) and don’t need to be explicitly added to bade.yaml:

blog
└── 2014
    ├── 07
    │   ├── 10
    │   │   ├── evening.rst
    │   │   └── morning.rst
    │   └── 16
    │       └── next-week.rst
    ├── 09
    │   └── 14
    │       └── entry.rst
    └── 12
        └── 16
            └── today.rst

The default directory for posts is blog, but this can be configured [2]. There is bade utility command for creating a post for today, which runs like this:

bade --post exciting-news

The above command will create any required directories for year, month, day and add the named file in the directory for “today”. Throw some rST (the minimum required is a heading) in that file and tell Git about it:

git add blog
git commit -m 'Added blog post'

Let’s render our micro-blog for the first time.

bade

The HTML for the rST files we created above will be rendered in a directory called _build (of course, this can be changed in Configuration). You can serve from that directory for development. Things are looking pretty plain right now, so after a brief overview of configuration options, we’ll look at how to add styles and use our own templates.

Before we forget, let’s also tell Git to ignore that pesky _build directory:

echo '_build' >> .gitignore

[2]	See Configuration for all the options.

Build¶

When you build your site, rST is rendered to HTML and jammed into page or post templates, the Blogtree and site index are rendered. Any assets specified for inclusion are also copied to the build directory. Optionally SCSS/Sass is compiled.

Templating¶

The templates provided with Bade are simple, a little bit semantic and work out of the box. However, they are plain as you like and don’t have any styles! To start hacking your own templates together, download the “template” templates from GitHub and go crazy. Let’s follow a quick example for changing up our site index to welcome visitors.

First grab the remote index.html template and put it in templates [3] locally:

mkdir templates
curl https://raw.githubusercontent.com/bmcorser/bade/master/templates/index.html > templates/index.html

It looks like this:

<%inherit file="base.html"/>

<%block name="title_block">Index</%block>

<%block name="header_block"></%block>

<%block name="content_block">
    <ul>
    % for page in pages:
        <li>
            <a href="${page['path']}">${page['title']}</a>
        </li>
    % endfor
    </ul>
</%block>

Let’s knock out the header block [4] to use the default inherited from base.html. Let’s also add a big welcome message. Your index.html will now look like this:

<%inherit file="base.html"/>

<%block name="title_block">Yes, this is blog.</%block>

<%block name="content_block">
    <h1>Hello, computer!</h1>
</%block>

Let’s build again by running bade and check things are looking how we expect. This is cool, but our blog is still looking plain. Let’s spice it up a bit by adding some CSS and images.

[3]	This is the default templates directory, but can be configured (see Configuration).

[4]	In the example above, an empty but specified block will override the parent template’s block – even if it has some content.

Assets¶

By default, everything in a directory called assets will be copied to the build directory and be available at /assets when serving.

Anything else your site needs apart from its rendered rST can be included by adding to the assetpaths list in the configuration YAML. Let’s see how to add styles and put an image in blog post

Styles¶

First create an assets directory and add a stylesheet that will make our site look really cool:

mkdir -p assets/css
touch assets/css/styles.css

Red text? I rather think so. Everyone likes red text.

body {
  color: red;
}

Next we need to include this in our templates, so we need to override another default, this time the base.html where our <head> is specified. Let’s grab is like we did before:

curl https://raw.githubusercontent.com/bmcorser/bade/master/templates/base.html > templates/base.html

The base template is pretty simple, it pretty much just provides a few blocks to override:

<html>
    <head>
        <meta charset="UTF-8">
        <title><%block name="title_block">${title_text}</%block></title>
    </head>
    <body>
        <%block name="header_block">
            <%include file="header.html" />
        </%block>
        <%block name="content_block" />
        <%block name="footer_block" />
    </body>
</html>

Add the <link> somewhere in the <head> the path should treat the build directory as root:

<link href="/assets/css/styles.css" rel="stylesheet" type="text/css" />

Build the site by invoking bade and check the technique! It’s all red, yo.

Images¶

Including images in the build is as easy as dumping them in the assets directory. Local images can then be referenced from your rST in an image directive. Let’s try it, first let’s get an image in our assets directory:

mkdir assets/images
curl https://www.python.org/static/img/python-logo@2x.png > assets/images/python.png

Then alter pages/about-me.rst to reference this image:

About me
########

I like biscuits, especially custard creams.

I write ...

.. image:: /assets/images/python.png

`dot-graph` directive¶

Sometimes we all like to draw a graph, but how to store it in plaintext? One answer is to use DOT. The directive for a graph written in DOT might look something like this:

.. dot-graph::

    digraph G {
        a -> b -> c;
        b -> d;
    }

This would render an SVG to the build directory that was available to the DOM at the address provided.

There’s a PDF describing DOT syntax in more detail, but the Wikipedia article is also an excellent reference.

Warning

This directive directive depends on Graphviz binaries being available (available on Homebrew and APT).

`maths` directive and role¶

There’s a directive and role to render TeX markup to inline SVGs, so you can get worthwhile mathematical notation without your page looking like it’s having an unpleasent turn (I’m looking at you, MathJax). Of course, for this to be possible, you will need a local LaTeX installation.

.. maths::

    $
    S = \{1, 2, 3} \\
    \\
    \alpha : S \rightarrow S \\
    \\
    \alpha =
    \bigl(
        \begin{smallmatrix}
            1 & 2 & 3 \\
            1 & 3 & 2
        \end{smallmatrix}
    \bigr)
    $

This would render some SVG markup directly inline with the page (no extra HTTP request required) looking something like this:

There’s also a maths “role” so you can put notation inline with your text. For example, to define the permutation above in a more narrative fashion, we could write rST like this:

Let :maths:`S = \{1, 2, 3\}` and let :maths:`\alpha : S \rightarrow S` be
the bijection given by :maths:`\alpha(1) = 1`, :maths:`\alpha(2) = 3` and
:maths:`\alpha(3) = 2`

The layout of inline equations with their surrounding text is not managed whatsoever, so it won’t come close to looking like a LaTeX layout ... but at least the formulae will look perfect.

Debugging templates¶

Bade hooks into Mako’s excellent debugging output with the --debug flag. Once the build is completed, there’ll be a message pointing you to files to inspect through the browser:

Debug HTML written to: ../_build/about.html

Tutorial¶

Assumptions¶

Setup¶

Pages¶

Posts¶

Build¶

Templating¶

Assets¶

Styles¶

Images¶

`dot-graph` directive¶

`maths` directive and role¶

Debugging templates¶

Table Of Contents

Previous topic

Next topic

This Page

Tutorial¶

Assumptions¶

Setup¶

Pages¶

Posts¶

Build¶

Templating¶

Assets¶

Styles¶

Images¶

dot-graph directive¶

maths directive and role¶

Debugging templates¶

`dot-graph` directive¶

`maths` directive and role¶