Using blag to host a small static blog site

Using blag to host a small static blog site

Set-up directories and install blag

I use an older Macbook Air running Sonoma as my local desktop. The focus of this article is how to set up blag on this local Mac. Blag is a blog-aware, static site generator – it uses Markdown and is written in Python. Because it also uses Jinja2 as its templating engine, it should be relatively easy to modify the menus and even the theme later on. Later the generated static html and css are uploaded to a server that uses caddy to securely serve static files.

Here are the steps to get started with blag. Create a working directory – I just created blag/ in my usual projects directory. Create and activate a Python virtual environment and then activate the environment. Once activated, install blag.

  python3 -m venv .venv
  source .venv/bin/activate
  python3 -m pip install blag

To exit the virtual environment, use deactivate. I always forget and type ‘exit’, which will just close your terminal window. Probably not what you want! Also, don’t forget that you will have to do source .venv/bin/activate any time you want to use the blag program.

Modify blag to support footnotes

Currently, the version of blag available via PyPi for installation via pip does not contain support for footnotes. To enable footnote support in the downloaded version, do the following:

cd .venv/lib/python3.14/site-packages/blag

Open markdown.py in your favorite editor and locate these lines:

    md = Markdown(
        extensions=[
            "meta",
            "fenced_code",
            "codehilite",
            "smarty",
            MarkdownLinkExtension(),
        ],
        output_format="html",
    )
    return md

Modify the file to activate the footnotes extension:

    md = Markdown(
        extensions=[
            "meta",
            "fenced_code",
            "codehilite",
            "smarty",
            "footnotes",
            MarkdownLinkExtension(),
        ],
        output_format="html",
    )
    return md

Save the file and you have now enabled support for footnotes¹. Blag uses the Python system-default markdown library and extensions, so you can turn on (or off) support for various features. See the markdown extensions documentation for more detail.

At some point, the blag author may release his updated version; in that case, pip will install the latest version with footnote support built in and you won’t need to hand-edit the file, unless you want to turn on support for other extensions.

Minor template modifications

Blag is a very simple system. Both “pages” and “articles” can be kept in the same content folder. “Articles”, which contain a header at the top of the document with the date, are blog posts. “Pages” are static pages, such as an “About” page, etc. They do not contain a date header. Read the manual for all of the details and don’t forget to edit the config.ini to add in default blog information.

I decided to create a folder in the content directory called posts for blog content, as well as a folder called pages for static content.

I edited the template very slightly to display the about page on the main menu. Here’s how to do that. Edit templates/base.html and locate the nav section of the template file. Add in a new line for the about page, so that the section now looks like this:

<nav>
  <h2>{{ site.description }}</h2>
  <ul>
  <li><h2><a href="/">Blog</a></h2></li>
  <li><h2><a href="/archive.html">Archive</a></h2></li>
  <li><h2><a href="/tags/">Tags</a></h2></li>
  <li><h2><a href="/pages/about.html">About</a></h2></li>
  </ul>
</nav>

Save the file, rebuild, and you should now have a link on the navbar of the home page.

I also changed from a serif to a sans-serif font and made other tiny tweaks to the style page for the site, which is located in static/style.css.

Configure settings to ease file generation and upload

I set up a Makefile to make it easier for me to generate and publish documents. I used the Makefile from another and much more complicated static site generator, Pelican, and modified it to work with blag and it simplifies the process a good bit. Here’s the modified file if you want to take a look at it.

Workflow for publishing

Blag is such a simple system that there is no concept of “draft” vs. “published” articles. If the document is in the content folder or one of its subfolders, it will get published. I’ve just created a folder at the root of the blag folder called drafts, where I keep draft Markdown files. This works for me.

Once I’m satisfied with my work, I move the document into the content/posts folder and then do make ssh_upload which rebuilds and posts everything to the server.

Blag is about perfect for my needs right now. Thanks to Bastian Venthur for writing and sharing it!