Skip to content
This repository has been archived by the owner. It is now read-only.
[Archived] static site generator written in Common Lisp
Common Lisp HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
content/default
layout/default
LICENSE
README.md
betterssg.asd
betterssg.lisp
build
config.lisp
finalbuild

README.md

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
You can’t perform that action at this time.