| BLAG(1) | blag | BLAG(1) |
blag - blag 1.4.1
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.
blag runs on Linux, Mac and Windows and requires Python >= 3.8
Install blag from PyPI
$ pip install 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. 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
$ blag --help
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 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 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 create a 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
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.
[...] this is a [link](foo.md) to an internal page foo.
becomes
<p>this is a <a href="foo.html">link</a> to an internal page foo.</p>
Custom templates are optional and stored by default in the templates directory. blag will search the templates directory first, and fall back to blag's default built-in templates.
| Template | Used For | Variables |
| page.html | pages (i.e. non-articles) | site, content, meta |
| article.html | articles (i.e. blog posts) | site, content, meta |
| archive.html | archive- and landing 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.
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:
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:
Tags in articles are also used to generate the tag-pages, that aggregate all articles per tag.
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.
$ blag serve
| blag.__init__ | Initialize self. |
| blag.version | |
| blag.blag | blag's core methods. |
| blag.markdown | Markdown Processing. |
| blag.devserver | Development Server. |
| blag.quickstart | Helper methods for blag's quickstart command. |
blag's core methods.
Functions
| build(args) | Build the site. |
| environment_factory([template_dir, globals_]) | Environment factory. |
| generate_archive(articles, template, output_dir) | Generate the archive page. |
| generate_feed(articles, output_dir, ...) | Generate Atom feed. |
| generate_tags(articles, tags_template, ...) | Generate the tags page. |
| get_config(configfile) | Load site configuration from configfile. |
| main([arguments]) | Main entrypoint for the CLI. |
| parse_args([args]) | Parse command line arguments. |
| process_markdown(convertibles, input_dir, ...) | Process markdown files. |
This is blag's main method that builds the site, generates the feed etc.
Creates a Jinja2 Environment with the default templates and additional templates from template_dir loaded. If globals are provided, they are attached to the environment and thus available to all contexts.
This method parses the CLI arguments and executes the respective commands.
This method processes the convertibles, converts them to html and saves them to the respective destination paths.
If a markdown file has a date metadata field it will be recognized as article otherwise as page.
Markdown Processing.
This module contains the methods responsible for blag's markdown processing.
Functions
| convert_markdown(md, markdown) | Convert markdown into html and extract meta data. |
| markdown_factory() | Create a Markdown instance. |
Classes
| MarkdownLinkExtension(**kwargs) | markdown.extension that converts relative .md- to .html-links. |
| MarkdownLinkTreeprocessor([md]) | Converts relative links to .md files to .html |
This method must be overridden by every extension.
Keyword arguments:
This method exists only to ensure we use the same Markdown instance for tests as for the actual thing.
Development Server.
This module provides functionality for blag's development server. It automatically detects changes in certain directories and rebuilds the site if necessary.
Functions
| autoreload(args) | Start the autoreloader. |
| get_last_modified(dirs) | Get the last modified time. |
| serve(args) | Start the webserver and the autoreloader. |
This method monitors the given directories for changes (i.e. the last modified time). If the last modified time has changed, a rebuild is triggered.
A rebuild is also performed immediately when this method is called to avoid serving stale contents.
This method recursively goes through dirs and returns the most recent modification time time found.
Helper methods for blag's quickstart command.
Functions
| get_input(question, default) | Prompt for user input. |
| quickstart(args) | Quickstart. |
This is a wrapper around the input-builtin. It will show the default answer in the prompt and -- if no answer was given -- use the default.
This method asks the user some questions and generates a configuration file that is needed in order to run blag.
Bastian Venthur
2022, Bastian Venthur
| September 29, 2022 |