How I Manage Content on This Site

I had been toying with the idea of using something like Hugo. I wanted the site to be static. Hugo is simple, fast, and has a shallow learning curve. However, it was a bit more overhead than I wanted. I highly recommend Hugo if you're looking for a full-featured static site generator. For me, it was just too much.

I wanted to satisfy some simple criteria:

1. One template
2. Text content managed in Markdown files
3. Scriptable. Write content, generate the static site, push to live.

I wanted to explore a few things in Javascript on the client-side. I initially though about using client-side routing and having only markdown files on the server. Fetch the Markdown files when requested, convert them to HTML, and display them to the reader all on the client. I explored this but stopped because I would have to have something on the server to map all requests to the same html file. I didn't want anything on the server.

So I decided I'd create a simple Python script to convert the Markdown content to HTML. That's what will get published.

The process is simple enough. Details of how it works and the first version of the script are below.

How it works

The script exists and runs from the current directory. It will clean and It reads in the _template.html file. The final rendered content will be written to the docs/ folder. This could be any folder really. I'm using GitHub Pages to host the site. My options were to use the root of the repository or the docs/ folder. I opted for the docs/ folder so that all of the content, the script, and the final site can be hosted in the same repository.

simple directory structure

• mdsite.py (below)
• _template.html
• static/
  • site.css
  • site.js
  • ...
• content
  • index.md
  • _ignore-as-draft.md
  • code/
    • index.md
    • this-site.md
    • ...
  • .../

static/

The contents of the static folder in the root of the site will be copied to the docs/static/ folder. This folder houses CSS, JavaScript, and any other static resource. It will be copied as is so files can be in subfolders.

templates/

This is the HTML template that will be used for every page of the site. It has a <content /> element somewhere in it that will be replaced with the rendered html from processing the Markdown files.

Currently just uses the basic.html template, but a future point of extension may be to render the same content with a different template for trtying things out, etc. It was also easier to add the watch service in the serve component.

content/

All of the files and folders in the content/ folder will be processed and the rendered html will be output in a corresponding location in the docs/ folder. Any file name that starts with an underscore will be ignored as those are considered drafts. I use Visual Studio Code to manage the content. I create links within the Markdown files to other Markdown files. Those links allow me to navigate the site in the editor efficiently. A simple find and replace for .md to .html will enable the rendered html to navigate correctly as well.

mdsite.py

This script converts the _template.html file and all the Markdown files in the content/ folder into the final rendered site. The script works by the conventions outlined above. The idea is to keep overhead as light as possible and work for the way I want to work.

With the Python files it is simple to create the site, try it out locally, and publish to GitHub. It is hosted with GitHub pages so it is all fairly simple. I didn't want to put all of the code in one Python file even though that would make it easier to share. So here we are. View contents of all the Python files here.

lightly tested

The Markdown extension modules are lightly tested. Just run pytest to run the few tests that are there.