forked from github.com/blag
98 lines
2.3 KiB
ReStructuredText
98 lines
2.3 KiB
ReStructuredText
Manual
|
|
======
|
|
|
|
Quickstart
|
|
----------
|
|
|
|
Install blag from PyPI_
|
|
|
|
.. code-block:: sh
|
|
|
|
$ pip install blag
|
|
|
|
.. _pypi: https://pypi.org/project/blag/
|
|
|
|
Run blag's quickstart command to create the configuration needed
|
|
|
|
.. code-block:: sh
|
|
|
|
$ blag quickstart
|
|
|
|
Create some content
|
|
|
|
.. code-block:: sh
|
|
|
|
$ mkdir content
|
|
$ edit content/hello-world.md
|
|
|
|
Generate the website
|
|
|
|
.. code-block:: sh
|
|
|
|
$ blag build
|
|
|
|
By default, blag will search for content in ``content`` and the output will be
|
|
generated in ``build``. All markdown files in ``content`` will be converted to
|
|
html, all other files (i.e. static files) will be copied over).
|
|
|
|
If you want more separation between the static files and the markdown content,
|
|
you can put all static files into the ``static`` directory. Blag will copy
|
|
them over to the ``build`` directory.
|
|
|
|
If you want to customize the looks of the generated site, create a
|
|
``template`` directory and put your jinja2 templates here.
|
|
|
|
Those directories can be changed via command line arguments. See
|
|
|
|
.. code-block:: sh
|
|
|
|
$ blag --help
|
|
|
|
|
|
Manual
|
|
------
|
|
|
|
some text
|
|
|
|
|
|
Templating
|
|
----------
|
|
|
|
Metadata
|
|
---------
|
|
|
|
blag supports metadata elements in the markdown files. They must come before
|
|
the content and should be separated from the content with a blank line:
|
|
|
|
.. code-block:: markdown
|
|
|
|
title: foo
|
|
date: 2020-02-02
|
|
tags: this, is, a, test
|
|
description: some subtitle
|
|
|
|
this is my content.
|
|
[...]
|
|
|
|
blag supports *arbitrary* metadata in your documents, and you can use them
|
|
freely in you templates. However, some metadata elements are treated special:
|
|
|
|
``date``
|
|
If a document contains the ``date`` element, it is treated as an
|
|
**article**, otherwise as a **page**. Additionally, ``date`` elements are
|
|
expected to be in ISO format (e.g. ``1980-05-05 21:58``). They are
|
|
automatically converted into ``datetime`` objects with the local timezone
|
|
attached.
|
|
|
|
``tags``
|
|
Tags are interpreted as a comma separated list. All elements are stripped
|
|
and converted to lower-case: ``tags: foo, Foo Bar, BAZ`` becomes: ``[foo,
|
|
foo bar, baz]``.
|
|
|
|
Tags in **articles** are also used to generate the tag-pages, that
|
|
aggregate all articles per tag.
|
|
|
|
``title`` and ``description``
|
|
The title and description are used in the html header and in the atom
|
|
feed.
|