[Archived] static site generator written in Common Lisp
Update readme with project status
Updated styling on default website to match wrycode.com

refs

master
browse log

clone

read-only
https://git.sr.ht/~wrycode/betterssg
read/write
git@git.sr.ht:~wrycode/betterssg

Archived Project

This program has a special place in my heart. It was my introduction to Common Lisp (a beautiful, if sometimes horrifying language) and my first 'real' programming project. In light of the poor documentation and nonexistent consistency in the CL ecosystem, I can't justify maintaining it. However, CL newcomers might find the code more useful than the decades-old books and blog posts that pass as documentation within the CL community.

Description

betterssg is good for generating simple websites like tom.preston-werner.com and osa1.net. Use betterssg if you want to avoid The Bullshit Web.

UPDATE June 2019: I'm not planning to continue developing this project, although I'm still using it for my personal website: wrycode.com. As of now, all documented features work well, but I have not done extensive testing.

Installation

To build from source, install the dependencies via Quicklisp, and run ./build.

Support for Windows and macOS is planned, but I have not tested on either platform. The source code is already cross-platform (in theory), so if you want to test it you can (asdf:load-system :betterssg) and then use (betterssg:main) to build your site instead of running the executable.

Usage

$ ./betterssg

There are currently no command-line arguments; all configuration is done in the file config.lisp.

To view a preview of the website, I recommend using Python's built-in HTTP server. From the shell:

$ python -m http.server 8080 --directory website/

File Organization

Inspect the files in the folders content/default/ and layout/default/. The content folder stores the markdown files that betterssg will process into finished HTML pages. The layout folder stores the HTML (and CSS, and, if you must, Javascript) that makes up each finished webpage.

I recommend copying content/default/ and layout/default/ into two new folders named after your website (like content/my-website/ and layout/my-website/). Make sure to change the variables :content-folder and :layout-folder in the config.lisp file.

Content

The name of each markdown file in the content folder represents the title of the webpage. example-title.md will become EXAMPLE TITLE. To group pages under a generated blog-style page, simply copy them to a directory named after the page (e.g. blog/). To date a page, prefix the filename with ten digits representing the date (e.g. 2019-03-13-my-first-post.md).

Ergo, all metadata is stored using the filesystem.

The top-level file home.md will become the homepage of the website.

media/ is a separate folder that will get copied into website/ when betterssg is run. It can include files of any type, including HTML.

Layout

Currently, the layout folder is very simple. The file page.html is the template for each generated webpage. It is a normal HTML file with four optional variables:

  • head: the contents of the head.html file (which can sometimes get quite large)
  • title: the title of the page, or nothing if there is no title
  • date: the date of the page, or nothing if there is no date
  • content: the content from each markdown file (converted to html, of course)

About

betterssg is opinionated. Simplicity is a priority. Want tags, complex user-defined taxonomies, a domain-specific language, thousands of themes, and a program that calls itself an engine? Use Hugo. Want to just make your website, already? Use betterssg.

Planned Features

  • HTML or plain text files in the content folder
  • Javascript-free syntax highlighting of code blocks
  • RSS feed generation
  • XML sitemap generation
  • --server argument for running and refreshing a local webserver
  • options regarding title case and date format

Idiosyncrasies

  • dated pages with no title must still have the trailing dash in the date: 2019-03-13-.md
  • for preformatted code, you must indent the region four spaces in the markdown file. Triple backticks and <pre> are not working correctly

Other TODOs

  • release for Windows and macOS