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:
- One template
- Text content managed in Markdown files
- Scriptable. Write content, generate the static site, push to live.
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)
The contents of the static folder in the root of the site will be copied to the
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.
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
.html will enable the rendered html to navigate correctly as well.
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.
The Markdown extension modules are lightly tested. Just run
pytest to run the few tests that are there.