.. _tutorial:
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
:ref:`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!
.. _Git: http://www.git-scm.com/
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`` [#]_, so let's
create that file and add some basic configuration:
.. _Grunt: http://gruntjs.com/
.. code-block:: yaml
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.
.. [#] 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.
.. code-block:: bash
mkdir pages
touch pages/about-me.rst
And throw some rST in that file.
.. code-block:: rst
About me
########
I like biscuits, especially custard creams.
This is the page that is referred to in our configuration YAML:
.. code-block:: yaml
pages:
- pages/about-me
Add all this stuff to Git and commit it:
.. code-block:: shell
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 ...
.. _Mako: http://www.makotemplates.org/
.. _posts:
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 [#]_.
There is bade utility command for creating a post for today, which runs like
this:
.. code-block:: shell
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:
.. code-block:: shell
git add blog
git commit -m 'Added blog post'
Let's render our micro-blog for the first time.
.. code-block:: shell
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 :ref:`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:
.. code-block:: shell
echo '_build' >> .gitignore
.. [#] See :ref:`configuration` for all the options.
Build
=====
When you build your site, rST is rendered to HTML and jammed into page or post
templates, the :ref:`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.
.. _GitHub: https://github.com/bmcorser/bade/tree/master/templates
First grab the remote ``index.html`` template and put it in ``templates`` [#]_
locally:
.. code-block:: shell
mkdir templates
curl https://raw.githubusercontent.com/bmcorser/bade/master/templates/index.html > templates/index.html
It looks like this:
.. code-block:: mako
<%inherit file="base.html"/>
<%block name="title_block">Index%block>
<%block name="header_block">%block>
<%block name="content_block">
%block>
Let's knock out the ``header`` block [#]_ to use the default inherited from
``base.html``. Let's also add a big welcome message. Your ``index.html`` will
now look like this:
.. code-block:: mako
<%inherit file="base.html"/>
<%block name="title_block">Yes, this is blog.%block>
<%block name="content_block">
Hello, computer!
%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.
.. [#] This is the default templates directory, but can be configured (see
:ref:`configuration`).
.. [#] 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:
.. code-block:: shell
mkdir -p assets/css
touch assets/css/styles.css
Red text? I rather think so. Everyone likes red text.
.. code-block:: css
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 ```` is specified. Let's
grab is like we did before:
.. code-block:: shell
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:
.. code-block:: mako
<%block name="title_block">${title_text}%block>
<%block name="header_block">
<%include file="header.html" />
%block>
<%block name="content_block" />
<%block name="footer_block" />
Add the ```` somewhere in the ```` the path should treat the build
directory as root:
.. code-block:: html
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:
.. code-block:: shell
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:
.. code-block:: rst
About me
########
I like biscuits, especially custard creams.
I write ...
.. image:: /assets/images/python.png
.. _dotgraph:
``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:
.. code-block:: rst
.. 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).
.. _`Graphviz`: http://www.graphviz.org/
.. _`a PDF`: http://www.graphviz.org/Documentation/dotguide.pdf
.. _`the Wikipedia article`: http://en.wikipedia.org/wiki/DOT_%28graph_description_language%29
.. _maths:
``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.
.. code-block:: rst
.. 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:
.. image:: https://raw.githubusercontent.com/bmcorser/bade/master/docs/source/_static/eqn.svg
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:
.. code-block:: rst
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