→ ↺ λ

Collards Manual

Table of Contents

[in package COLLARDS.DOCS]

← ↑ → ↺ λ

1 Introduction

A static site generator for those who love Markdown and parens.

A long time ago, I wrote a blog engine called Coleslaw. It was written on a lark as I and two friends all resolved to get off Wordpress. We scheduled a lunch and learn for our unwritten blog engines a week later. The initial implementation was thrown together in a weekend. For many years, it was enough.

Collards is a simple static site generator. It offers:

← ↑ → ↺ λ

1.1 Links

[builds]: https://builds.sr.ht/~kingcons/collards The official repository and [CI builds][builds] are available.

← ↑ → ↺ λ

2 Making your first site

← ↑ → ↺ λ

2.1 Installation

While Collards should be portable to any OS that runs Lisp, it is only tested on Linux. Notably, the serve command may not work on non-linux OSes.

The only way to install Collards today is building it yourself. Cloning the repository and running make app should be enough. After that, place bin/collards anywhere on your $PATH.

While the Makefile builds with SBCL by default, passing LISP=ccl as an argument to make app should be sufficient to build with Clozure CL. Other lisps have not been tested.

For users of Guix, a package is provided in the repo so running guix shell will get you a working environment.

At some point, collards may become available via binaries or Quicklisp.

← ↑ → ↺ λ

2.2 Creating a collards site

Once collards is installed, building a site involves creating a folder (or git repo if preferred), adding a .collards file, and then adding markdown files to generate posts and pages, lisp files to generate pages with custom templates, and feed and collection files to generate RSS feeds or index pages.

When collards tries to build your site, it will look for a folder named "init" and load any lisp files within it that define custom templates or content types. Other than the init dir, collards will create a build dir and an assets dir if they are not present.

The assets dir is useful because any files placed under it are easy to generate URLs for both in markdown content using wikilinks like so, [[asset:example.jpg]], or from lisp with (site-url "asset:example.jpg").

The default templates expect a style.css file within the assets folder but if you don't want to have your CSS in assets you can customize the templates by writing your init files however you like. Feel free to take a peek at my init files as an example.

Once the config file is written, the collards command can be run anywhere within that site folder. Your config might be as simple as:

(:author "Melissa Rogers"
 :domain "melissa.website"
 :ignored ("drafts")
 :title "Adventures in Code")

The config file itself strives to be small, requiring only values for an Author, Domain, and Title. You can also provide a list of Ignored subfolders. If you wish to use the deploy command to rsync your build output to a server, then you must also supply Server settings. Subdomains can optionally be specified to send specific directories output to different paths on the server.

An example config file can be viewed here. The other files in that example directory in the collards repo are used as data for the test suite. For a look at a "production" site that may be more realistic, the repo for my homepage may be of interest.

← ↑ → ↺ λ

2.3 Adding Content

When collards builds a site, it will process all files that it recognizes and copy any other files to an output directory. Then, that output directory can be freely copied to a public webserver either with the deploy command built into collards or manually. The files in the output directory will be organized the same way they were in the site folder. If all your markdown post files are in a blog folder, then the HTML files will go in a blog output subfolder.

Collards recognizes files by extension (see: Content Types) and currently knows about .lisp files which are treated as pages, .md files which are treated as posts, and some custom files like rss.feed which generates RSS feeds and tag.collection or recent.collection which generate indexes of posts with specific tags or posts in reverse chronological order.

As mentioned above, the examples folder in the project repo or my personal site may be useful to see examples of a live site.

← ↑ → ↺ λ

2.4 Templates

init: https://git.sr.ht/~kingcons/kingcons.io/tree/collards/item/init Collards uses Spinneret for HTML generation. There are default templates lightly modified from my personal site that are provided as of verison 0.5 but you are encouraged to write your own by defining render methods in your init files if you are so inclined. My init files may be a useful guide.

No styling or CSS is provided by collards out of the box. The intent of this is merely to encourage people to design sites according to their own style. I think the web is better when we come to it authentically, offering a part of ourselves. I hope collards encourages that ethos.

Templates are methods on COLLARDS.CONTENT:RENDER that take a content subclass and a site instance as arguments and generate HTML using spinneret.

Collards will load all lisp files from the user's init directory before building so template definition and custom behavior can be defined there.

A simple post template with next/prev navigation might be:

;; Note: I recommend using package nicknames for convenience.
;; I.e. To allow for post:body instead of collards.post:body,
;; md:render-markdown instead of collards.markdown:render-markdown, etc
(defmethod content:render ((content post:post)
                           (site site:site))
  (spinneret:with-html
    (:doctype)
    (:html
      (:head
        (:title "foo")
        (:link :href css-path :rel "stylesheet" :type "text/css"))
      (:body
        (:div.navigation
         (:p "Nav goes here"))
        (:section
          (:div.article-content
           (:raw (md:render-markdown (post:body content))))
          (:div.neighbors
           (util:when-let (prev (registry:prev content))
             (:a :href (content:url-for prev) (content:title prev)))
           (util:when-let (next (registry:next content))
             (:a :href (content:url-for next) (content:title next)))))
        (:div.fineprint
         (:hr)
         "Unless otherwise credited all material CC-BY-SA"
         (site:author site)))))

← ↑ → ↺ λ

2.4.1 Template Utilities

[in package COLLARDS.TEMPLATES.HELPERS]

Writing custom templates for different content types is encouraged for Collards, but doing so without some helper utilities isn't a pleasant process. The following functions are provided to provide some quality of life tools and ensure you're able to focus on the styling of your site rather than getting basic details of content on the page.

← ↑ → ↺ λ

3 Content Formats

As mentioned in Adding Content, Collards associates the extension of a file with a particular parser. Markdown is particularly noteworthy both because our parser provides some useful extensions and because it can be used to create Pages as well as Posts based on the frontmatter. A good example of how to write pages using Spinneret will be forthcoming in a future release.

← ↑ → ↺ λ

3.1 Markdown

Since Collards uses 3bmd for markdown parsing, their docs will be the most authoritative source of info on our markdown support. That said, the behavior of frontmatter in .md files is unique to collards and it is valuable to have a brief overview of the useful extensions from 3bmd we have enabled.

← ↑ → ↺ λ

3.1.1 Frontmatter

It is critical to supply metadata for content generated from markdown. All markdown files intended for processing by Collards are expected to have an initial frontmatter section written in YAML, which you may be familiar with from other blogware like Jekyll.

← ↑ → ↺ λ

Example Post

Frontmatter is separated from the main content by ---. For example:

---
title: Writing a Static Site Generator
tags: lisp, software-dev
date: 2025-02-03 08:00:00
draft: true
summary: Some experiences writing a static site generator for personal use.
---
## A Sensible Build System

In many ways, static site generators can be viewed as build tools to
turn arbitrary content formats into HTML...

This example demonstrates all the available metadata for our post format. Title is the only required field but comma-separated tags, date, draft, and summary are all supported. Collards does not handle actual Date parsing yet so a date format beginning with YYYY-MM-DD is recommended for now.

← ↑ → ↺ λ

Example Page

example: https://git.sr.ht/~kingcons/kingcons.io/tree/main/item/init/slides.lisp The only important attribute not demonstrated in the previous example is the type attribute. type is an escape hatch to allow using markdown files for generating Pages though nothing prevents you from using it to generate new kinds of content defined in your config, like a remark.js powered slideshow. My personal config actually does just that.

Much more common though is the desire to generate a Page from markdown which is useful since they don't participate in tag, year, or recent collections.

---
title: About Me
type: page
---
## Hobbies and Projects
...

← ↑ → ↺ λ

3.1.2 Markdown Extensions

[pygments]: https://pygments.org/ Two 3bmd extensions are used: Code blocks and Wikilinks. Code blocks are highlighted by Colorize but Pygments or Chroma can be used instead by throwing one of the following snippets in your init files: (setf 3bmd-code-blocks:*renderer* :pygments) or (setf 3bmd-code-blocks:*renderer* :chroma)

For further details, consult the 3bmd documentation.

Wikilinks will come in handy when you want to link between pieces of content within a collards site. Using a Content ID between double brackets will look up the specified content in the site registry and link to it. For example: [[page:about]] or [[post:2024-reflections]].

Additional arguments can be passed to wikilinks by separating them with the pipe character (|). The first argument will be used as the title, the second controls whether an 'a' tag or 'img' tag is used for the content. Thus, you can easily embed image assets in your posts: `[[asset:jurgen.jpg|jurgen|img]].

It is also possible for users to define their own markdown extensions by following the 3bmd grammar and enabling them in collards via the helper functions described in Markdown Utilities. One example to support easy bandcamp embeds can be seen here.

← ↑ → ↺ λ

3.1.3 Markdown Utilities

[in package COLLARDS.MARKDOWN]

If you are writing custom templates or custom markdown extensions, these utility functions will support parsing frontmatter in markdown, rendering markdown, and enabling or disabling the user-defined extensions.

← ↑ → ↺ λ

4 CLI Commands

Answering the siren song of my own laziness, rather than laboriously writing docs about the CLI commands, I have repurposed the usage docs generated by Clingon. If anything is unclear, feel free to ask me questions via email or mastodon. I may be slow to respond.

← ↑ → ↺ λ

4.1 The Collards command

← ↑ → ↺ λ

4.2 The Build subcommand

[in package COLLARDS.BUILD]

← ↑ → ↺ λ

4.3 The Serve subcommand

[in package COLLARDS.SERVE]

← ↑ → ↺ λ

4.4 The Deploy subcommand

[in package COLLARDS.DEPLOY]

← ↑ → ↺ λ

4.5 The Help subcommand

[in package COLLARDS.HELP]

Help takes a single topic as an argument and displays the documentation for that topic. If no topic is supplied, the list of available topics is shown.

← ↑ → ↺ λ

5 The Core API

It is time that we described the interfaces that power Collards.

The docs from this point forward are targeted towards developers more than users and describe the API of the data types and build process rather than details of using the CLI and building a site.

← ↑ → ↺ λ

5.1 Building a Site

[in package COLLARDS.SITE]

Before doing anything else, collards needs a site object. The site object holds basic configuration info as well as a registry of Content Objects that will be used to build the site.

[config]: https://git.sr.ht/~kingcons/collards/tree/main/item/examples/.collards A site can be built from any folder with a .collards file which serves as a configuration file that the site is created from. An example collards config can be found [here][config].

The folder with the .collards file is considered to be the 'site root'. This is significant because Collards places rendered files in the build folder relative to where they were under the site root.

As a consequence, it is essential that the .collards file can be found and useful to have helpers for determining the relative path of site files. Errors will be raised if the .collards file cannot be found or if there are any missing arguments needed to construct a functioning site.

The *SITE* instance is dynamically bound during the build process but should not be interacted with by user code. LOAD-CONFIG is used behind the scenes to create the site instance.

For situations where there is a need to iterate over the files in the site a helper macro named DO-FILES is provided. It automatically ignores the build, asset, and init folders, any .git folder within the site, and hidden files.

A lower-level CALL-WITH-FILES function is also provided for special cases.

← ↑ → ↺ λ

5.2 Content Objects

[in package COLLARDS.CONTENT]

Content Objects are what collards uses to represent files it will render, usually to HTML, to build the site. All Content objects must have at least a source file they are loaded from and a title used to generate a slug.

As part of HTML generation, collards finds all files to process in the site folder and builds content objects with them. To make a content object, we first determine the file extension and call PARSE on it, then take the result of parsing and give that to GET-TYPE which determines what class to BUILD an instance of. NOTE: The collection and feed types are treated specially since they generate multiple HTML files from a single input file and are also populated dynamically based on other registered content.

Consequently, user-defined content types can be created by defining:

  1. A new subclass of CONTENT

  2. A GET-TYPE method with an eql-specialized file extension returning the class to instantiate

  3. A PARSE method on that extension returning a plist of initargs

  4. A RENDER method to accept an instance of the content and generate HTML (i.e. a template)

Nothing is required to "inform" collards about the new content type because we introspect the content methods at runtime to determine what files have the necessary machinery for parsing and building.

All this can be done in an init file so no upstream modification to collards is needed.

Since pages need to have unique, safe URLs we provide ID and PATH functions that help determine where content should reside on the site and provide a shorthand for uniquely identifying it. SLUGIFY is run on the TITLE of all content during BUILD to help determine its output path.

Finally, there are some internal helpers for determining urls and whether URLs should be relative or absolute, mostly for the build and serve commands.

← ↑ → ↺ λ

5.3 The Site Registry

[in package COLLARDS.REGISTRY]

The Registry supports storing and retrieving content objects along with a number of utility functions useful for building the site.

The most relevant functions are REGISTER and LOOKUP for storage and retrieval. There is also a low-level macro, DO-CONTENT, for iterating over the registry items matching a condition, utility functions to FETCH or PURGE all content matching a condition, and SIBLINGS for finding other items of the same type.

Because it is often interesting to view "related" content, content types can define a method on the RELATED-KEY generic function. RELATED-KEY should return an accessor for the content type suitable for use with SORT.

Currently, all sorting is performed by STRING> to support chronological order for posts, year collections, etc. To make it easier to write templates that link to other content objects, PREV and NEXT functions take content and return the previous or next content object according to RELATED-KEY.

There are conditions signalled in the event of failed lookups or attempts to register duplicate content IDs and a condition handler to LIST-CONTENT-IDS.

← ↑ → ↺ λ

6 Content Types

← ↑ → ↺ λ

6.1 Static Assets

[in package COLLARDS.ASSET]

← ↑ → ↺ λ

6.2 Pages

[in package COLLARDS.PAGE]

← ↑ → ↺ λ

6.3 Blog Posts

[in package COLLARDS.POST]

← ↑ → ↺ λ

6.4 RSS Feeds

[in package COLLARDS.FEED]

← ↑ → ↺ λ

6.5 Collections

[in package COLLARDS.COLLECTION]

Most sites have interest in grouping subsets of content together by different means. Tags are one way to accomplish this but collards also models groupings by date as a kind of collection. You may decide to define other groupings.

Collections are created in a second phase after all other content is loaded. Currently tag, yearly, and reverse chronological collections are supported. Only post objects participate in collections but it is possible to define custom collection subclasses in your site that specialize on other types. (Or to override the GATHER and POPULATE methods for the existing collections.)

Since collections are special-cased in the build process, it makes sense to share some of those details here. First, type.collection files are found during the regular content loading step. Second, after site content is loaded, GENERATE is called to build and register instances matching the supplied type. So if the filename was tag.collection it would build instances of TAG.

Because collections usually generate multiple HTML files from a single input file, collards cannot rely on its normal convention of computing a slug from the input file. As a result, each collection implements GATHER to query the registry for how many pages a collection will have and their titles. (E.g. A list of distinct tags, or months when posts were made.) GENERATE then uses this information to produce a list of the instances to build and finally calls POPULATE on each one to fill them with matching content before registration.

← ↑ ↺ λ

7 Glossary