forked from github.com/blag
265 lines
6.3 KiB
Markdown
265 lines
6.3 KiB
Markdown
# 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
|
|
```
|