Booklit

Booklit is a tool for building static websites from semantic documents.

Booklit enforces a tidy separation between content, logic, and presentation that makes it easy to write and refactor websites for anything from technical documentation to slide decks to blogs.

For live examples, check out Bass, Concourse CI, and the site you're currently viewing (src).

You're probably wondering "why does the world need another static site generator?" The truth is I built this for myself; I had a lot of technical content to maintain, and I didn't like the state of the art. I wanted something more like Scribble so I could write code to minimize toil.

Booklit has been serving me well across multiple projects for years with little modification needed, so I think it's good enough to share.

content in *.lit

Booklit documents are text files which evaluate \functions to generate content, ultimately resulting in a tree of sections.

Sections are easy to move around, allowing you to continuously refactor and restructure your content without having to tweak header sizes and update internal links.

\title{Hello}{index}

Hello, world! I'm a Booklit document.

Check out my favorite \reference{quotes}!

\include-section{quotes.lit}

\title{Quotes}
\use-plugin{example}

\quote{
  It's lit!
}{Travis Scott}

logic in *.go

Sections use plugins to invoke \functions written Go. Go is a simple and fast language with plenty of packages around if you need them.

Plugins allow your content to be semantic - saying what it means, decoupled from how it should be computed or displayed.

func (Example) Quote(
  quote, source booklit.Content,
) booklit.Content {
  return booklit.Styled{
    Style: "quote",
    Content: quote,
    Partials: booklit.Partials{
      "Source": source,
    },
  }
}

presentation in *.tmpl

Booklit separates presentation into a final rendering phase which determines the output format.

The HTML Renderer is powered by Go's standard html/template package. More renderers may be implemented in the future.

All base templates can be overridden, sections can be individually \styled, and plugins can return booklit.Styled content, giving the author full control over what comes out.

<!DOCTYPE html>
<html>
  <head>
    <title>{{.Title.String}}</title>
  </head>
  <body>
    {{. | render}}
  </body>
</html>

<blockquote class="quote">
  {{.Content | render}}

  <footer>
    {{.Partial "Source" | render}}
  </footer>
</blockquote>

build with booklit

The booklit CLI is a single command which loads Booklit documents and renders them.

When an error occurs, Booklit will show the location of the error and try to suggest a fix.

$ booklit -i ./index.lit -o ./public/
INFO[0000] rendering

$ booklit -i ./to-err-is-human.lit
to-err-is-human.lit:5: unknown tag 'helo'

   5| Say \reference{helo}!
          ^^^^^^^^^^
These tags seem similar:

- hello

Did you mean one of these?

serve with booklit -s $PORT

In server mode, Booklit renders content on each request with only plugin changes requiring a server restart.

The feedback loop is wicked fast.

$ booklit -i ./index.lit -s 3000
INFO[0000] listening

This website is written with Booklit. Want to write your own? Let's get started!