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 🏗.)
- Visualizing data using inline SVGs
- Syncing your website with a web server
- Publishing your website on Netlify
Reference
Background Information
- Organizing Computation With Finite Schema Machines
A description of how Fabricate arranges the sequence of transformations to get a HTML page from an input template.
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.
site.fabricate.prototype.write:doc- Fabricate's namespace for writing HTML pages. This file combines fabricate's other namespaces for reading source files, parsing & restructuring their contents, and generating HTML pages with additional functions for input and output in order to achieve the purpose of the library: create HTML documents. The central method that it uses to combine these functions from other namespaces is a finite-state-machine.