Fabricate


Form by art and labor

Introducing Fabricate, a Clojure library for making static websites, using Clojure.

Fabricate takes a different approach than markdown and notebook-based tools, which frequently assume a one-size fits all approach to displaying code: if there's code in a markdown block, it's included in the output. I made Fabricate so that I could program more of my layout, and so that I could choose when and where to display both Clojure expressions and their results.

Rather than deriving the layout from a generic approach that treats "code blocks" and "text" as distinct entities, Fabricate lets you embed the results of any expression right in the text, eschewing markup formats in favor of inline Hiccup elements.

Examples



(let
 [s "output"]
 [:h4 (format "a form evaluated and displayed with its %s" s)])

a form evaluated and displayed with its output



Documentation


Tutorials

These guides will get you up and running with Fabricate, so you can use it as a writing and creative tool. Hopefully you find them useful.

Tutorial 1: Using Fabricate to add documentation to an existing Clojure project

This first tutorial allows you to use Fabricate to document a project or library you've built.

Tutorial 2: Using Fabricate to create a website

🏗️ To be published.

In the second tutorial, you will learn how to publish all the pages you create using Fabricate as a website.

How-to guides


Supporting Fabricate in Emacs

Consult this guide to add support for Fabricate's templates to Emacs.

Further guides (to be published 🏗.)

Reference

Background Information

Namespaces


The namespace descriptions, automatically generated from the namespace forms, introduce the functionality that fabricate assembles to create pages.

  • site.fabricate.prototype.schema

    :doc
    Utility namespace for working with malli schemas.
  • site.fabricate.prototype.html

    :doc
    Namespace for creating HTML forms using Hiccup data structures and for verifying their structural correctness using malli schemas. The schemas in this namespace implement a non-interactive subset of the MDN HTML spec.
  • site.fabricate.prototype.read

    :doc
    Parsing + evaluation utilities for embedded Clojure forms. The functions in this namespace split the text into a sequence of Hiccup forms and embedded expressions, which is then traversed again to evaluate it, embedding (or not) the results of those expressions within the Hiccup document.
  • site.fabricate.prototype.read.grammar

    :doc
    Instaparse grammar for Fabricate's page templates.
  • site.fabricate.prototype.page

    :doc
    Functions for transforming processed page contents.
  • site.fabricate.prototype.fsm

    :doc
    Namespace for defining finite schema machines. A finite schema machine is a method of organizing the functions to be called in a program by the state of the data passing through the program. Those states are defined using malli schemas. It is similar in concept to the idea of a state-action behavior in Leslie Lamport's 2008 paper 'Computation and State Machines', but the formalism is not as rigorous.