__     __     __
.-----.-----.|  |--.|  |--.|  |.-----.
|  _  |  -__||  _  ||  _  ||  ||  -__|
|   __|_____||_____||_____||__||_____|
|__|

pebble is a static site generator written in CHICKEN Scheme that's hopefully fun and easy to use!

What is this?

A static site generator converts text input files into static HTML for quick deployment of websites. Pebble supports Markdown (CommonMark) and HTML or SXML fragments by default, but pandoc can be used for extended Markdown or to additionally support Org, AsciiDoc, and reStructuredText. The aim is to stay out of your way while providing reasonable configuration and convenience features.

Quickstart

  1. DownloadYou can also build it from source after inspecting the build.sh script yourself the static executable for your platform from the latest release page, rename it, and make it executable. 
    mv pebble-1.0.1-x86_64-alpine-linux-musl pebble
chmod +x pebble
  2. Run pebble. You should see it create two directories: SOURCE and SITE. Any new or modified Markdown files in SOURCE will be published as HTML in SITE the next time you run pebble. Any other files in SOURCE are linked or copied to SITE. 
    ./pebble
[Fri Oct  2 13:02:04 2026] SOURCE=/private/tmp/source/
[Fri Oct  2 13:02:04 2026] SITE=/private/tmp/site/
  3. Edit index.md, then run pebble again. Your site's home page, index.html, has been created! 
    ./pebble
[Fri Oct  2 13:08:18 2026] SOURCE=/private/tmp/source/
[Fri Oct  2 13:08:18 2026] SITE=/private/tmp/site/
[Fri Oct  2 13:08:18 2026] Publishing $SOURCE/index.md to $SITE/index.html
  4. Default styling and scripting goes in source/static/pebble.css and source/static/pebble.js.
  5. You can use --server to start up a server on localhost to preview your changes. If it's supported on your platform, you can use --watch to automatically publish files as you edit them, freeing you of having to run pebble manually. 
    ./pebble --server --watch
[Sat Oct  3 10:30:06 2026] SOURCE=/tmp/source/
[Sat Oct  3 10:30:06 2026] SITE=/tmp/site/
[Sat Oct  3 10:30:06 2026] Publishing $SOURCE/index.md to $SITE/index.html
[Sat Oct  3 10:30:06 2026] Starting server on http://localhost:8080
  6. See pebble --help or read on for more configuration options.
  7. Enjoy!

Configuration

Changing the source and site directories

You can change the source and site directories by passing --source=SOURCE-DIR and --site=SITE-DIR to pebble:

./pebble --source=./markdown --site=/var/www/example.com

Styles and scripts

The default CSS and JS files are in SOURCE/static/pebble.css and SOURCE/static/pebble.js. There are a couple other ways to include extra styles and scripts:

Example: source code syntax highlighting

For example, source code syntax highlighting on this site is currently done using highlight.js. The only thing required to enable this was to add the following to SOURCE/pebble/head.html:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/styles/default.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.12.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

Example: MathJax

Maybe you want to enable MathJax to render Latex expressions like this:

$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

into pretty math like this:

$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

Simply add the followingYep, you don't usually need a value to the async attribute, but there's a small bug in one of the libraries I'm using... to SOURCE/pebble/head.html:

<script id="MathJax-script" async="" src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js"></script>

Header and footer

A header (like the fancy pebble title above) or footer can be configured in the SOURCE/pebble directory. This can be arbitrary content; if you want a proper header or footer you must include those tags yourself. pebble will look for them in this order, and insert the (possibly translated) contents for the first one found:

Other text formats

You can write your pages in other text formats using pandoc. Currently only Org, AsciiDoc, and reStructuredText are supported, though more may be added.This might be changed to behave more flexibly or support other programs Note that this will use pandoc's own extended Markdown syntax instead of the default CommonMark.

If pandoc installed and in your PATH, you can tell pebble to use it as follows:

./pebble --pandoc

Pre-processing source text files

Text files in SOURCE can be pre-processed, e.g. to support special syntax or create a search DB as a side effect. This is done using the file SOURCE/pebble/preprocess. This must be an executable program that will be invoked with the file to process as the first argument, for example:

preprocess SOURCE/index.md

Example: sidenotes

Say, for whatever reason, you simply must have sidenotes in some bespoke syntax like !​{A footnote ...}.You know who you are... I'm recommending the ! prefix to avoid parsing woes with code blocks though One simple way to achieve this might be to make SOURCE/pebble/preprocess a Python script:

Show Python script 
#!/usr/bin/env python3

import sys
import re

FN_INDEX=1

def make_footnote(match):
    global FN_INDEX
    string = match.group(1)
    i = str(FN_INDEX)
    html = f"""<sup class="fnref"></sup><span class="fn">{string}</span>"""
    FN_INDEX+=1
    return html

with open(sys.argv[1]) as f:
    file = f.read()

print(re.sub(r"!\{([^}]+)\}", make_footnote, file), end='',flush=True)

Then, add the appropriate CSSModified from: https://gwern.net/sidenote.

Show CSS 
.fnref::before {
    counter-increment: fnref;
    content: counter(fnref)
}

.fn::before {
    counter-increment: fn;
    content: counter(fn) '. ';
}

.fn {
    float: right;
    clear: right;
    margin-right: -50%;
    width: 50%;
    margin-top: 0.3rem;
    margin-bottom: 0;
    font-size: .85rem;
    line-height: 1.3;
    vertical-align: baseline;
    position: relative;
}


@media (max-width: 160ch) {
    .fn {
        display: block;
        float: left;
        left: 1rem;
        clear: both;
        width: 95%;
        margin: 1rem 2.5%;
        vertical-align: baseline;
        position: relative;
    }
}

Sources

You can find sources for pebble and report bugs on the project page here:

The pebble-example repository is this site, and may provide a template for how to set up a pebble site and host it on sourcehut pages.Note that sourcehut has a strict Content Securty Policy that doesn't allow for external JS/CSS, so I have to bundle the given examples with the site itself.

Other sites generated with pebble

This site was generated using pebble!