#Extremely simple static site generator

Converts files in a directory into a website of posts. Assumes you're willing to edit html.

There are 3 tools here:

• gen_pages.lua -- wraps files in a consistent layout
• gen_index.lua -- creates paginated index (front) pages
• gen_feeds.lua -- puts most recent pages in XML and HTML formats that can notify subscribers of new posts

You'll need Lua (any version after 5.1) and a terminal running some Unix derivative. Linux, BSD, Mac OS or Bash on Windows.

sample/ shows how you might want to organize the directory where you do your writing. To add a new page to it:

• cd sample
• create a file for your new page
• add the filename to the file file_list (more recent files higher up)
• run lua ../gen_pages.lua file_list layout output to generate webpages for a single post each.
• run lua ../gen_index.lua file_list site_layout post_layout index to generate paginated index pages for the site.
• run lua ../gen_feeds.lua file_list feed.xml feed.html to generate feeds for the site that contain links to the most recent posts.

Try running these scripts without inputs to see what the words mean, e.g. lua ../gen_index.lua. gen_index.lua and gen_feeds.lua have some variables you can configure up top.

To give all your pages some shared structure, put it in the file layout.

It won't delete existing files. To regenerate all files, first run rm output/*

Adjust names like file_list, layout and output to taste. Just use names consistently. Don't forget to mkdir the directory you want to store the output in.

Each file you create should have a section up top containing header lines of the form "key: value" with properties of each post. Below the header lines should be a delimiter line containing just "---". Below the delimiter line go the actual contents you want to write. Put anything there.

gen_site uses the following properties at the top of the file (though you can add others for yourself):

• title
• date -- human-readable date to show in your posts
• filename -- the name of the file you want to create
• permalink -- the final URL of the file you create (after say you copy it to your webhost)
• xml_date -- date in the format "13 May 2024 04:33:29 CST" (RFC 822)
• html_date -- date in the format "2024-05-13" (ISO 8601)

Most of these properties are optional most of the time. gen_index.lua and gen_feeds.lua are kinda meaningless without permalink. gen_feeds.lua will not generate valid XML feeds without xml_date, and will not generate valid HTML Journal feeds without html_date.[1] filename will default to the name of the source file if not provided.

Sometimes you'll want to truncate a post's contents on the frontpage to make your website easy to skim. To do that, insert the following line to mark the truncation point.

<!-- more -->

See sample/ for example uses.

#Forks

There can be a lot more to a static site generator. If you add features to your site/generator, please show it to me and I'll link to it here.

• joeldn/reading_time shows an estimate of reading time for every post.

[1] The precise date formats ensure other computers can read them correctly. Read more about the feed formats:

• XML feeds
• HTML journal feeds