March 5, 2023
This blog was created by me hand-writing HTML and CSS. This is an experiment. The idea is basically: keep it simple, stupid.
Below, I've listed some tips for getting this set up. Click here to skip my commentary and skip straight to to them.
My requirements for a blog:
In a previous iteration, I used WordPress. WordPress indeed checks all of the above boxes. However, my current solution is free, whereas WordPress was costing me a whopping $2/month. Also, I didn't super love the editing experience of WordPress. Right now, I'm using my favorite editor (Visual Studio Code) to write this post, which is ideal.
I've also tried Hugo. It's cool, but I quickly ran into an issue when I wanted to create an About page, and the theme that I liked didn't include one. I could easily create new posts, but not a stupid About page. I gave up after a few hours of attempting (and failing) to add one to the theme myself.
So here we are. It's taken me a couple of hours to stand everything up: I did some initial research on where to host it, relearned some basic CSS stuff (I used to do frontend development, but it's been a few years), found a comment box I like, and figured out syntax highlighting.
While this approach is simple, it's not without downsides. The primary one is that future refactoring will be tedious. This is the primary reason I was looking into static site generators like Hugo.
I've considered writing a very simple templating program using Jinja that would allow me to save the header, footer, and other repeated content in separate files, and then reference them in each page. This would be much more DRY, and it'd probably be easy, but it's more effort than I want to make right now.
While refactoring will be a little painful, we're likely talking tens of pages at max, not hundreds or thousands. I'm ok with that for now. And when I'm not, I'll fix it.
My current workflow: run a server, and then start writing HTML. When done, push to GitLab, which is integrated with Cloudflare Pages - Cloudflare will deal with the rest. GitHub Pages would have also worked (I think it supports custom domains), but I just don't like GitHub.
Here's a quick command to run an HTTP server in the current directory. Note that this requires
Python 3 - the invocation for Python 2 is different.
python3 -m http.server 80 --bind 0.0.0.0
I'm using macOS. On Linux, you'll probably have to sudo or otherwise obtain permissions
to bind port 80. Not sure about Windows. Binding to 0.0.0.0 allows me to access
the site over my local network, for mobile testing.
Update (2023-03-12): while the above works, it turns out that Cloudflare Pages is rewriting
my links to .html pages to remove the extension. (I believe Github Pages will do the same thing.)
While I don't mind this, it breaks using the above simple strategy to serve pages. So, here's a quick
python script that modifies the basic Python http server to remove html extensions for my About page and
for anything in the posts/ directory:
import http.server
import socketserver
class MyHandler(http.server.SimpleHTTPRequestHandler):
def do_GET(self):
if self.path == "/about" or "/posts" in self.path:
self.path += ".html"
super().do_GET()
PORT = 80
with socketserver.TCPServer(("", PORT), MyHandler) as httpd:
print("serving at port", PORT)
try:
httpd.serve_forever()
except KeyboardInterrupt:
httpd.shutdown()
I dislike CSS as much as everyone else, so I've attempted to keep it to a minimum. Feel free to use my styles as a jumping off point for your blog if you want to try this. But, no promises regarding quality. It seems I've forgotten nearly everything I once knew about CSS.
I went with Prism.js based on a quick web search. It was pretty easy to set up -
add a couple of snippets in the page, and then wrap things in code tags with class language-python
and such. Here's a quick CSS snippet for styling the syntax highlighting (Consolas 16px looks too big next to
Georgia 16px to my eyes):
code[class*="language-"] {
font-size: 14px !important;
}!important - since I'm overriding someone else's
styles, I think this is a valid use of it.
I had to add overflow-x: auto to the div that contains all of my content to
fix code snippets with long lines on mobile. Without it, the content wouldn't collapse
horizontally. I also had to then add overflow-y to avoid a scrollbar being introduced.
Did I mention that I hate CSS?
Also, how to change the color scheme wasn't obvious from the documentation. It turns out that you just link
a different stylesheet for the theme. In my case, this would involve loading prism-okaidia.min.css
instead of prism.min.css, for example.
I'm using htmlcommentbox.com, which involves signing up, and pasting some HTML in your page where you want the box. It appears to be free for just basic commenting functionality.
Be advised that I have no idea what I'm talking about here.
My goal here is to spend about 15 minutes setting up some basics to encourage search engines to crawl and display my site. I'm not trying to game SEO or anything.
Adding a meta description is a good practice for search purposes. It summarizes a page's content and presents that to users in the search results.
<meta name="description" content="A description of this page's content.">A sitemap indicates a map of the pages on your website. It's more important for large sites with thousands of pages, but creating one and submitting it to Google can help Google find your site. Here's mine. I created this manually, and will have to update it when I make new posts.
sitemaps.org seems like a good resource for more info.
A robots.txt can indicate certain pages that shouldn't be crawled. This is primarily to avoid issues with too much crawling traffic on certain pages. More importantly for me, it specifies the location of the sitemap to crawlers. Here's mine.
Here's a neat little site that you can use to generate a favicon based on a letter: favicon.io
If I keep up with this blogging habit, I'll report back in after a few posts on how I'm feeling about this approach.