KISS static blog site generator

Pseudo abandoned, re-implemented as a flask project

For blog.node5.net, Made for my speceific use case, but otherwise generalized.

Table of contents

• KISS static blog site generator
• Table of contents
• Features
• Installation
• Creating content
• Articles
• Templates
• Static
• Usage
• TODO

Features

• live reload Preview changes live in your browser
• Jinja2 Templating
• Markdown Content writing
• Code blocks syntax hightlighting

Installation

git clone https://git.node5.net/blog-generator.git
cd blog-generator
make

If it throws an error like path not found or you otherwise don't have ~/.local/bin in echo $PATH run the following, for an explaination see this StackExchange post

mkdir ~/.local/bin
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.profile

Creating content

All the of the site content is derived from one folder e.g. default page this containts 3 folders:

• articles
• templates
• static

To make your own site simply, copy the Default page, and pass this to the blog generator blog_generator.py "Default page" live_reload

Articles

Any markdown file with the extension .md will be used, it can be in the root, or it can be in a folder and be named index.md, in which case the folder name will be used as the article name, this is useful, if you wish to have media e.g. images for an aricle.

Meta data is defined at the top of the article in YAML format enclosed in ---

---
description: Example description
created: 2024-01-30
modified: 2024-02-01
---

Todays date can be generated in this format using the following command

date +%F

Templates

These are Jinja2 templates, which makes them very flexible.

Static

All files in this folder will be copied over to the output folder

Usage

make generate to delete the output folder and generate page make live_reload to first generate and locally host the site and regenerate on file change make deploy to remove meta data from media in this directory and sub directories (warning overwrites media)

The generate and live_reload both generate the site and outputs it to the output folder. Which can be served, or copied to the web server you host it on.

TODO Feature creep galore

• Refactor code, split out logic
• Refactor code, add comments
• Code highlight theme, based on blog color theme
• Headlines ids, for URL #reference
• Move more stuff to config(s), e.g. port, dateformat, sort
• Pretty format logging
• Propagate additional article meta data to be
• Split out article meta data to seperate class, do this once the desired features are more well known
• Build test pipeline
• Page source content root defined in one dir, pass arg with this, so it's easy to make a new page
• Text to diagrams
• Package code
• Default page code highlight
• Default page CSS
• Publish node5.net source
• Fix Debian install, it doesn't have user writable bin folder in $PATH by default like Arch's ~/.local/bin
• Tags, article meta data tags
• RSS feed, auto generated
• Support other markdown files extentions
• Command line arguments for creating articles with meta data pre-filled
• Table of contents, auto generated
• Use modified date
• Add tree directory structure ascii art explaining folder structure
• Article source versioning
  • Sites as a sub repo? What about big media files like images?
  • Versioning git integration for markdown change history + derive modified meta data from git history
  • PEP8 check
  • CI/CD git deploy pipeline
• Categories
  • Derive values from directory structure
  • Allow for sub categories e.g. hardware/keyboards
  • Display the sub categories like folder structure
• Done
  • Make install
  • Describe insertion of HTML like for videos
  • Allow no arguments, by using current working directory to derive the source folder from, and default to live reload
  • On file change, generate only the specific file, don't regenerate the entire site
  • Allow an article to not have a directory, but just be a markdown file in the source directory