-------------------------------------------------------------------------------
The Static Blog Generator w/RSS
Turns individual HTML files into a full blog with RSS support
-------------------------------------------------------------------------------
Requirements: Python 3.6 or higher
Compatibility: Linux, macOS, *BSD and Windows
Setup: * Download blog.py and template.html
* put both in the same directory (it doesn't matter where)
* manually create ./posts/YYYY (where YYYY is the current year)
* write your first post as HTML in "./posts/YYYY"
* save the post as: MM.DD--title.html
-------------------------------------------------------------------------------
This is the ~/local/directory after the initial setup.
┌── blog.py (Creates the index*.html and rss.xml files. The only )
│ (files you upload. )
│
├── template.html (Comes with one template. Easy to create more. )
│
└── ./posts/ (All posts are organized here. The script will look )
│ (in this directory (configurable, default is ./posts))
│ (You manually create the entire tree. )
│
├── ./2025/
│ ├── 12.14--the.council.of.linux.greybeards.html (sample↗)
│ ├── 12.30--happy.new.year.bash.html (sample↗)
│ └── MM.DD--title.of.post.html
│
└── ./2026/
├── 03.30--summer.glau.a.sci-fi.fantasy.icon.html (sample↗)
├── 04.18--words.to.live.by.html (sample↗)
└── MM.DD--title.of.post.html
(File naming is critical because the script uses the )
(MM.DD prefix to control the post order. The full )
(filename is used to create anchor links. )
(The script is designed to be safe - never writing )
(to this directory tree - only read operations. )
-------------------------------------------------------------------------------
Running the script ("./blog.py" or "python blog.py" on windows)
* The script will ask for confirmation before deleting old files.
(Once you're comfortable, you can delete the safety check section. It's )
(clearly marked inside the script and easy to remove. )
* Delete old "index*.html" and "rss.xml".
* Generate the new "index*.html" and "rss.xml" files.
This is your /blog directory after you upload the newly created files
┌── index.html (Static HTML page created by ./blog.py)
├── index-2.html (page 2: older posts)
├── index-3.html (page 3: even older posts)
│
└── rss.xml (the last 10 full posts, default/configurable)
-------------------------------------------------------------------------------
Customize the template
* Edit "template.html" to:
- personalize it (template.html retains my site information)
- change the look of your blog.
* The only requirement: keep the following where you want your posts to appear.
The script looks for this specific string:
<!-- POSTS GO HERE -->
-------------------------------------------------------------------------------
Customize the script (blog.py)
Open "blog.py" in a text editor. All settings are at the top:
.----------------.-----------------------------------------------.
| Variable | Description |
|----------------+-----------------------------------------------|
| BLOG_BASE_URL | Change if your blog is not at "/blog/" |
|----------------+-----------------------------------------------|
| POSTS_PER_PAGE | Number of posts per page (default 20) |
|----------------+-----------------------------------------------|
| RSS_ITEMS | Number of posts in RSS feed (default 10) |
|----------------+-----------------------------------------------|
| POSTS_DIR | Where your posts are stored (default "posts") |
|----------------+-----------------------------------------------|
| TEMPLATE_FILE | Your template file (default "template.html") |
|----------------+-----------------------------------------------|
| SCRIPT_TITLE | Change to your blog name |
'----------------'-----------------------------------------------'
-------------------------------------------------------------------------------
notes: This is a custom built static blog generator w/RSS that is specific to
how I work. There are warts, for sure, because I just needed something
simple, for personal use, that would automate RSS. After I was done, I
thought someone else might find it useful.
The biggest complaint might be the lack of permalinks.
* The RSS file links each story in its XML file to an anchor link that
matches the relevant post inside index.html. I decided to do it this
way in order to simplify things. I didn't want to upload:
(1) the index*.html and rss.xml files (nice, simple) but
(2) also upload and track the entire ./posts/ tree and all the
individual posts, in addition to
(3) scripting for relative local linking when index.html is at
/blog/ and the permapost would be at /blog/posts/2026/
Other possible complaints:
* The individual posts are written as HTML. No markdown, no other
human-friendly syntax or even plain text that is converted.
* The current template is mid↗: https://640kb.neocities.org/blog↗
(It's easy to create new templates. Use the default as a guide)
Complaints beyond my control:
* RSS: element should not contain relative URL references. See:
https://validator.w3.org/feed/docs/warning/ContainsRelRef.html↗
(But... see page source, bottom of page for more information)
-----------------------------------------------------------------------------
Blue Oak Model License 1.0.0↗ | Script released: 11 May 2026
Documentation updated: 13 May 2026
-----------------------------------------------------------------------------