Lettersmith

A set of tools for static site generation. It comes with a static site generator bundled in. You can also use it as a library to build your own custom static site generator.

I built it for myself, because I found other solutions to be pretty baroque and difficult to customize. Right now, it's a simple set of fairly stable tools for personal use. I might package it up later.

Installing

Lettersmith requires Python 3+, and a version of pip compatible with Python 3.

git clone https://github.com/gordonbrander/lettersmith_py
cd lettersmith_py
pip3 install -e .

lettersmith_site

Lettersmith comes bundled with a static site generator lettersmith_site that can do most of what Jekyll, et al do.

lettersmith_site takes a single argument — a path to a yaml config file.

lettersmith_site lettersmith.yaml

lettersmith_scaffold

You can easily scaffold a site using lettersmith_scaffold.

lettersmith_scaffold . --type wiki

This will plop a yaml config file and a theme directory you can customize into your project directory. Right now there is just one type: "wiki", though I hope to add more for common site types (e.g. blog, portfolio, etc).

What it does

Lettersmith comes bundled with a static site generator, but it's really just a library of tools for transforming text. You can use these tools to create your own custom static site generators, build tools, project scaffolders, ebook generators, or wikis — whatever you like.

Lettersmith loads text files as Python namedtuples, so a markdown file like this:

---
title: "My post"
date: 2018-01-17
---

Some content

Becomes this:

Doc(
  id_path='path/to/post.md',
  output_path='path/to/post/index.html',
  input_path='content/path/to/post.md',
  created=datetime.datetime(2018, 12, 31, 16, 0),
  modified=datetime.datetime(2018, 12, 31, 16, 0),
  title='My post',
  content='Some content',
  section='path',
  meta={
    "title": "My post",
    "date": "2018-12-31"
  },
  templates=()
)

Plugins

Plugins are just functions that transform namedtuples.

To transform many files, you can load them into an iterable, then use list comprehensions, generator expressions, and map, filter, reduce:

# Get all markdown paths under source/
paths = Path("source").glob("*.md")
# Load them as Python dicts
docs = (Doc.load(path) for path in paths)
# Transform them with your function
docs = (my_plugin(doc) for doc in docs)

When you're done transforming things, you can pass the iterable to Docs.write, which takes care of writing out the files to an output directory.

Docs.write(docs, output_path=output_path)

That's it!