2024-02-14 | [alnwlsn-com]
It might be spaghetti code flavored!
Writing markdown is easier than html, and more readable if not rendered. For making notes, short articles, etc. it's more than enough. I did used to use mediawiki for my site but it's kind of overkill for a single user writing something that might as well be a text file. Markdown is easier than writing wikitext. I wish I could make my web server just serve up .md files instead of having to write html every time. Turns out there are lots of tools that do this (Hugo, Jekyll, 11ty, Gatsby), and work by rendering all the markdown to html first and serving up that (called a static site generator). So why make my own when there are lots of others that do this?
This is all done in Python. The heavy lifting of rendering the markdown to HTML is done with https://github.com/frostming/marko. I use the built in code highlighter extension. All the rest - linking, metadata, tags, image scaling, etc. is done my me.
It's a horrible mess of shell commands, regular expressions, and probably SQL injection vulnerable code. But, since it all runs on my local machine, there's not really any security problems to worry about.
My RSS feed is just the text output of lynx from the rendered pages. Perhaps I will learn to do it properly one day.
I do like to write things down sometimes, because I can't remember everything (that's what this page is for)
Start by writing markdown normally
Links like this http://alnwsln.com can be written as just text, and the script will automatically turn them into a link.
At the end of the file, put a code block like this:
```alnwlsn-ssg
title: the Alnwlsn static site generator
subtitle: why and reference
date: 2024-02-14
labels: alnwlsn-com
```
The ```alnwlsn-ssg part is where the markdown file ends and where the metadata begins. Using yaml-ish here mostly because I don't want to have to put quotes around all my item keys like in JSON.
hidden: key will keep from generating tags, or appearing in the list of all pages. The rendered files will still be there though.
labels: list of comma separated tags (will generate tags page). Current version can't have spaces in the tag.
comments: if included, will enable comments at the end of the page
series: if specified, will make links to the next and previous items in the series. If no name is specified, will use the first label
title: will go in the html <title> field and will also become the link text where the post is listed
subtitle: will become plain text next to the link text
ext: Allows you to specify a different file extension to generate: ext: php will change the extension to php, etc.
js: will include a js file in the <head> section, with type "text/javascript"
noinfo: will suppress generation of the info line (the parts with the date and links to other labels), which is normally placed at the top, or under the first heading.
nofooter removes the comments | Alnwlsn link at the bottom
To make a post, just add a directory into the input folder with your post content. Any markdown files inside will become rendered .html instead.
Any pictures referenced in the same folder as the markdown file will get downscaled and placed into the special 'i' folder. These images, within the rendered html, will display the downscaled version, with a link to the full res version. Display references to other images (referenced relative ../some-other-folder) will also be redirected to that folder's 'i' downscaled version
The script will also always try to pick an index.html file:
The comments section below (and on the other pages) is done with PHP and sqlite3. One php file does it all - accepting the comments forms on POST and displaying them on GET. Also, it can generate an rss feed for the comments section on each page, although if you click the link below it will probably look like gibberish because your browser does not know it is supposed to be looking at xml. Pasting the link into an RSS reader does seem to work properly.
If you want to see the code for the SSG / Comments processor, I don't have an issue with sharing it, but I'm not going to do so straight away because there's a lot of personal / system information I will need to redact. If even one person wants to see it that badly, please say so in the comments below.
Edit 2024-08: nobody leaves comments, so I turned them off on all the pages and just made one page with them on.