Welcome to my blog!
· Metablog
Hello, and welcome to my new blog!
I’ve owned the domain name winslowjosiah.com for just over a year, and up until this point, I’ve only used it for hosting a few small projects. But now that I have a blog, I’ll be using it to talk about whatever tech stuff I’ve been getting into lately. (I code a lot, but you wouldn’t know it from my GitHub activity. 😅)
First, I think I should blog about how I made this blog. Buckle up for some technical details…
Static site generator
There are countless blog websites that are made using some kind of “static site generator”. A static site generator will take content written in some format (like Markdown or reStructuredText), and use it to create a complete website – all the HTML, CSS, JavaScript, everything.
Many static site generators are available, and when I asked for suggestions on Mastodon, a few helpful folks threw out these examples:
-
Written in Ruby. Write content in Markdown or HTML. Can deploy from GitHub using GitHub Pages.
-
Written in Go. Write content in Markdown (though several other formats are supported). Site generation is apparently pretty speedy.
-
Written in JavaScript. Write content in any of 11 different formats (including Markdown, and the whimsically named “Mustache” and “Handlebars”). Projects can be as complex – or as simple – as needed.
-
Written in Python. Write content in Markdown, reStructuredText, or HTML. Very customizable, with many plugins and themes.
-
Written in JavaScript. Write content in Markdown, HTML, Word documents, and Google Docs. The most frictionless static site generator I’ve seen.
In the end, I decided to go with Pelican, because I’m pretty comfortable with Python (and also, because I run another website called The Pelicanizer, the name was very on the nose).
Content format
My static pages and blog posts are written in Markdown, which makes them simple to write. The only thing for me to remember is to put any metadata I need at the beginning of the file, like so:
Title: Example Blog Post
Author: Josiah Winslow
Date: 2024-04-26 21:32
Slug: example-blog-post
Category: Misc
Tags: example, blog, post
This is the _content_ of my **blog post**!
Note
Only the Title field is technically necessary – and even then, I could
avoid that with some config option – but I like having the metadata there.
Even in some other Markdown viewer, you’d know exactly what this file is
for.
For styling the website, there is a community-managed collection of Pelican Themes to choose from. However, I chose to use a custom theme instead; theme templates are written in Jinja, which was straightforward enough for me to learn the basics of.
One interesting application for Jinja templates is using them to write content
directly in HTML/Jinja. Pelican is able to use HTML files as content, but the
way they’re parsed doesn’t allow for a lot of flexibility. However, if I specify
a Template field in the metadata of a Markdown file, I can effectively change
the content of that page by changing that template file. In fact, here is the
entire Markdown source for my “Projects” page:
Title: Projects
Slug: projects
Template: pages/projects
(All of that page’s content was written in a theme template!)
Directory structure
After spending a long time trying to customize my site to my liking, this is the directory structure of my Pelican project. It’s not exactly ideal, but hey, it’s mine.
| Directory | What’s in here? |
|---|---|
/content/articles |
Blog articles, in Markdown |
/content/images |
Images to include on the website |
/content/pages |
Static pages, in Markdown |
/content/scripts |
JavaScript files to include on the website |
/plugins |
Pelican plugins, in Python |
/themes/winslowjosiah/static |
Static files necessary for the theme (like CSS) |
/themes/winslowjosiah/templates |
Page templates, in Jinja |
/themes/winslowjosiah/templates/pages |
Page templates used for some static pages (with content written in Jinja) |
Pelican plugins
Pelican supports plugins that can alter or extend its functionality without modifying its core directly.
At the moment, my Pelican project only uses two plugins: Neighbors (which adds a Previous/Next link to blog articles), and a custom plugin that extends the Markdown parser.
Tip
Originally, I had actually written a plugin to replace the default Markdown parser (Python-Markdown) with a faster one called mistletoe, but it turned out to have fewer features by default, and be harder to work with in general.
However, you could write a plugin in the same vein that reads content written in a different format. One person made a Pelican plugin that reads content in a custom format they call “Mau”.
My custom plugin adds four extensions to the Markdown parser:
- one that formats text
==like this==into highlighted text like this, - one that formats text
~~like this~~into crossed-out textlike this, - one that makes various text substitutions, like changing
(C)to ©, - and one that wraps
<table>tags in containers that can scroll horizontally when they need to.
Future work
One thing I’d love to add to this blog is a way for users to add comments. Pelican does support adding a comment section with Disqus, but I’m hesitant to actually set it up. Cusdis seems like a better option, but I will have to spend time figuring out how it works. And one interesting solution I’ve seen is to pull replies to a Mastodon post and display those as comments.
What do you think I should do here? I’d ask you to write a comment about it…but as of now, my blog doesn’t have a comment section. So I guess you can tell me about it on my Mastodon or Twitter accounts? I dunno.