updated docs

README.md

@@ -20,12 +20,14 @@ blag is named after [the blag of the webcomic xkcd][blagxkcd].
 * Generation of Atom feeds for blog content
 * Fenced code blocks and syntax highlighting using [Pygments][]
 * Integrated devserver
+* Available on [PyPI][]
 
 blag runs on Linux, Mac and Windows and requires Python >= 3.8
 
 [markdown]: https://daringfireball.net/projects/markdown/
 [jinja2]: https://palletsprojects.com/p/jinja/
 [pygments]: https://pygments.org/
+[pypi]: https://pypi.org/project/blag/
 
 
 ## Quickstart

docs/index.rst

@@ -3,15 +3,47 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to blag's documentation!
-================================
+Welcome to blag!
+================
+
+blag is a blog-aware, static site generator, written in Python_. An example
+"deployment" can be found here_.
+
+blag is named after the blag of the webcomic xkcd_.
+
+.. _python: https://python.org
+.. _xkcd: https://blog.xkcd.com
+.. _here: https://venthur.de
+
+
+Features
+--------
+
+* Write content in Markdown_
+* Theming support using Jinja2_ templates
+* Generation of Atom feeds for blog content
+* Fenced code blocks and syntax highlighting using Pygments_
+* Integrated devserver
+* Available on PyPI_
+
+blag runs on Linux, Mac and Windows and requires Python >= 3.8
+
+.. _markdown: https://daringfireball.net/projects/markdown/
+.. _jinja2: https://palletsprojects.com/p/jinja/
+.. _pygments: https://pygments.org/
+.. _pypi: https://pypi.org/project/blag/
+
+
+Documentation
+=============
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   api.rst
 
+   quickstart.rst
+   api.rst
 
 Indices and tables
 ==================

docs/quickstart.rst

@@ -0,0 +1,29 @@
+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
+
+