a better static site generator
Updated styling on default website to match wrycode.com
Fix incorrect ordering on agregate pages and implement the media folder.
Remove outdated instructions for downloading binary.

refs

master
browse log

clone

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

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.

Release of version 1.0 (a very stable release) is planned for May 2019.

As of now, all documented features work well, but I have not done extensive testing. I use it for my personal website: wrycode.com.

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

Bugs

  • 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
  • Integrate a more complete markdown parser or document all supported markdown features
  • implement testing