replaced sphinx with mkdocs

docs/manual.md

@@ -0,0 +1,264 @@
+# Manual
+
+
+## Quickstart
+
+Install blag from [PyPI][]
+
+```sh
+$ pip install blag
+```
+
+[pypi]: https://pypi.org/project/blag/
+
+Run blag's quickstart command to create the configuration, templates and some
+initial content.
+
+```sh
+$ blag quickstart
+```
+
+Create some content
+
+```sh
+$ edit content/hello-world.md
+```
+
+Generate the website
+
+```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 look of the generated site, visit the `template`
+directory. It contains jinja2 templates and can be modified as needed.
+
+Those directories can be changed via command line arguments. See
+
+```sh
+$ blag --help
+```
+
+
+## Manual
+
+### Pages and Articles
+
+Internally, blag differentiates between **pages** and **articles**.
+Intuitively, pages are simple pages and articles are blog posts. The decision
+whether a document is a page or an article is made depending on the presence of
+the `date` metadata element: Any document that contains the `date` metadata
+element is an article, everything else a page.
+
+This differentiation has consequences:
+
+* blag uses different templates: `page.html` and `article.html`
+* only articles are collected in the Atom feed
+* only articles are aggregated in the tag pages
+
+blag does **not** enforce a certain directory structure for pages and articles.
+You can mix and match them freely or structure them in different directories.
+blag will mirror the structure found in the `content` directory
+
+```
+content/
+    article1.md
+    article2.md
+    page1.md
+```
+
+results in:
+
+```
+build/
+    article1.html
+    article2.html
+    page1.html
+```
+
+Arbitrary complex structures are possible too:
+
+```
+content/
+    posts/
+        2020/
+            2020-01-01-foo.md
+            2020-02-01-foo.md
+    pages/
+        foo.md
+        bar.md
+```
+
+results in:
+
+```
+build/
+    posts/
+        2020/
+            2020-01-01-foo.html
+            2020-02-01-foo.html
+    pages/
+        foo.html
+        bar.html
+```
+
+
+### Static Files
+
+Static files can be put into the `content` directory and will be copied over to
+the `build` directory as well. If you want better separation between content
+and static files, you can use the `static` directory and put the files there.
+All files and directories found in the `static` directory will be copied over
+to `build`.
+
+```
+content/
+    foo.md
+    bar.md
+    kitty.jpg
+```
+
+results in:
+
+```
+build/
+    foo.html
+    bar.html
+    kitty.jpg
+```
+
+Alternatively:
+
+```
+content/
+    foo.md
+    bar.md
+static/
+    kitty.jpg
+```
+
+results in:
+
+```
+build/
+    foo.html
+    bar.html
+    kitty.jpg
+```
+
+
+### Internal Links
+
+In contrast to most other static blog generators, blag will automatically
+convert **relative** markdown links. That means you can link you content using
+relative markdown links and blag will convert them to html automatically. The
+advantage is that your content tree in markdown is consistent and
+self-contained even if you don't generate html from it.
+
+
+```markdown
+[...]
+this is a [link](foo.md) to an internal page foo.
+```
+
+becomes
+
+```html
+<p>this is a <a href="foo.html">link</a> to an internal page foo.</p>
+```
+
+```python
+def this_is_a(test):
+    pass
+```
+
+### Templating
+
+Templates are stored by default in the `templates` directory.
+
+Template     | Used For                               | Variables
+------------ | -------------------------------------- | -------------------
+page.html    | pages (i.e. non-articles)              | site, content, meta
+article.html | articles (i.e. blog posts)             | site, content, meta
+index.html   | landing page of the blog               | site, archive
+archive.html | archive page of the blog               | site, archive
+tags.html    | list of tags                           | site, tags
+tag.html     | archive of Articles with a certain tag | site, archive, tag
+
+If you make use of Jinja2's template inheritance, you can of course have more
+template files in the `templates` directory.
+
+
+#### Variables
+
+* `site`: This dictionary contains the site configuration, namely: `base_url`,
+  `title`, `description` and `author`. Don't confuse the site-title and
+  -description with the title and description of individual pages or articles.
+
+* `content`: HTML, converted from markdown.
+
+* `meta`: stands for all metadata elements available in the article or page.
+  Please be aware that those are not wrapped in a dictionary, but **directly**
+  available as variables.
+
+* `archive`: A list of `[destination path, context]` tuples, where the context
+  are the respective variables that would be provided to the individual page or
+  article.
+
+* `tags`: List of tags.
+
+* `tag`: A tag.
+
+
+### 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:
+
+```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-09 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.
+
+
+## Devserver
+
+blag provides a devserver which you can use for local web-development. The
+devserver provides a simple web server, serving your site in
+http://localhost:8000 and will automatically rebuild the project when it
+detects modifications in one of the `content`, `static` and `templates`
+directories.
+
+```sh
+$ blag serve
+```