diff --git a/docs/blag.rst b/docs/blag.rst
new file mode 100644
index 0000000..e5a0a86
--- /dev/null
+++ b/docs/blag.rst
@@ -0,0 +1,97 @@
+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.
diff --git a/docs/index.rst b/docs/index.rst
index 7b99e96..731814f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -42,7 +42,7 @@ Documentation
    :caption: Contents:
 
 
-   quickstart.rst
+   blag.rst
    api.rst
 
 Indices and tables
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
deleted file mode 100644
index 21c8573..0000000
--- a/docs/quickstart.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-Quickstart
-==========
-
-Install blag from PyPI_::
-
-    $ pip install blag
-
-.. _pypi: https://pypi.org/project/blag/
-
-Run blag's quickstart command to create the configuration needed::
-
-    $ blag quickstart
-
-Create some content::
-
-    $ mkdir content
-    $ edit content/hello-world.md
-
-Generate the website::
-
-    $ blag build
-
-By default, blag will search for content in ``content`` and the output will be
-generated in ``build``. Those directories can be changed via command line
-arguments. See::
-
-    $ blag --help
-
-