Skip to content

About

The shared static-site generator behind jlt-commons project documentation

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

54 Commits

Folders and files

docs-engine

The static-site generator behind jlt-commons project documentation. A project writes markdown, and this turns it into a site that GitHub Pages serves.

It is a small Clojure program that runs on jolt, which reads the tasks in deps.edn directly. External dependencies (markdown-clj, selmer, the jolt-lang/yaml/jolt-lang/time shims that make those two resolve under jolt, and ring-chez-adapter for the preview server) are fetched on first run.

The idea

A project keeps its own docs, its own config and its own homepage. The engine keeps the rendering. Nothing about a project lives in this repository, because in this organization the person maintaining a project is usually not the person maintaining the engine.

Each project's CI checks this repo out at a pinned tag, builds, and deploys to that project's own Pages site. No repository ever pushes into another, so no cross-repo tokens exist to leak.

Onboarding a project

Give the project a docs/ directory:

your-project/
  docs/
    site.edn            # config, all keys optional
    guide/
      index.md          # pinned first in the nav
      other-page.md
    templates/          # optional, only if you want a bespoke homepage
      home.html
    demos/              # optional, any assets your pages reference

Then docs/site.edn:

{:base-path   "/your-project"
 :title       "your-project"
 :description "One sentence. It becomes the meta description and the footer."
 :asset-dirs  ["demos"]
 :home-template "home.html"}

:base-path is the key people get wrong. A project site is served at jlt-commons.github.io/your-project/. Leave the base path out and every stylesheet, script and nav link resolves against the organization site instead. The page still renders, just with the wrong styles, so the mistake is easy to ship. site.core-test covers it.

Leave :base-path as "" only for a site served at a domain root.

Key Default What it does
:base-path "" Prefix for every URL the engine emits
:title the README's first H1, else the directory name Site title and brand
:description the title Meta description and footer line
:github-url git remote get-url origin, as https The nav's GitHub link
:asset-dirs none Directories under docs/ copied into the build verbatim
:templates-dir templates Where project templates live, relative to docs/
:home-template none, so the generic homepage A file in the templates dir
:search true false turns off the search index, the nav search box and the script tag

:asset-dirs is an allowlist, and each entry names one directory directly under docs/, with no separators, no leading dot and no ... The list decides what gets copied into a published site, so a project that could write ["../../.ssh"] would publish it.

An entry is copied to the site root under its own name, so docs/images ends up at <base-path>/images. When the homepage is rendered from README.md, its src and href values that start with docs/<entry>/ (or ./docs/<entry>/) are rewritten to that copy. The README's images then show on the site and on GitHub alike, and a path into a directory that isn't listed stays as written.

The same homepage's links to guide pages are rewritten too: docs/guide/x.md (or ./docs/guide/x.md, with or without a #fragment) becomes <base-path>/guide/x.html, the page the build writes. A link to any other file in the repository stays as written and has no page on the site, so give it a full GitHub URL if the homepage should reach it.

Markdown pages get GitHub's alerts too. A blockquote opening with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] renders as a titled callout.

Building

jolt run build ../your-project     # generate ../your-project/_site/
jolt run clean ../your-project     # delete the build output
jolt run test                      # the test suite
jolt run serve ../your-project     # build, then serve, honouring :base-path
jolt run serve ../your-project 4000

Use jolt run <task>, not bare jolt <task>, because build collides with jolt's own native build -m NS compiler subcommand. The preview server binds with ring-chez-adapter.

_site/ is generated. Add it to the project's .gitignore.

jolt run serve mounts the build at the project's configured :base-path, so the local URL matches the deployed one. A project with :base-path "/your-project" previews at http://localhost:3000/your-project/, and the server prints that full URL when it starts. A root-hosted project is served at / as before.

The base path is baked into every generated URL. Serve the build at the server's root instead and the homepage renders unstyled with every link dead, even though the site itself is fine.

Homepages

Ship no template and the engine renders docs/guide/index.md (falling back to README.md) into a plain, readable page. That is enough for most projects, and onboarding one needs nothing but markdown.

Ship docs/templates/home.html and it is used instead. Write it as a Selmer template extending the engine's chrome:

{% extends "base.html" %}
{% block title %}your-project{% endblock %}
{% block body-class %}home{% endblock %}
{% block content %}
  <h1>...</h1>
  <a href="{{site-base}}/guide/index.html">Read the guide</a>
  <img src="{{site-base}}/demos/thing.gif">
{% endblock %}

Every internal URL goes through {{site-base}}. A bare /guide/index.html in a project template points at the organization site.

Available variables: site-title, site-brand, site-tagline, site-github-url, site-base, site-docs-href, search (a boolean, true unless the project sets :search false).

A project template overrides any engine template of the same name, so a bespoke 404.html or docs.html works the same way. Overriding base.html means inheriting none of the engine's later fixes to it, so prefer a block override where one will do.

Search

Every site gets client-side search with nothing to configure. A magnifier in the nav opens it, / focuses the box, the arrow keys and Enter pick a hit, and a hit inside a collapsed section opens that section when you land on it.

The build writes _site/search-documents.json, one record per page, per h2 and per h3. It covers every guide page, including the engine's default ones such as Contributing, and the generic homepage when that is rendered from README.md. Two things stay out. A bespoke :home-template isn't indexed, because it is a Selmer template and not rendered markdown. A generic homepage rendered from docs/guide/index.md isn't either, since that guide page is already indexed and a second copy would return every hit twice. Records are sorted by href so a rebuild is byte-identical, and each href carries the :base-path.

lunr.js (vendored, 2.3.9, MIT) and the index load only when a reader first opens search, so someone who never searches downloads neither.

To turn it off, put :search false in docs/site.edn. The build then writes no index file, and the nav has no search box and no search.js tag.

A project that overrides base.html gets no search box, because the box lives in the engine's copy. Add one by hand or use a block override instead (see Homepages above).

The search is adapted from jolt-lang.net's own (jolt-lang/jolt-lang.github.io).

The default Contributing page

Every project's guide gets a guide/contributing.html, in the nav right after index.md, even without writing one. It comes from the engine's own resources/content/contributing.md and is treated like base.html or 404.html, as shared chrome. How to open an issue against a jlt-commons project has the same answer everywhere, so the page lives in one place rather than in a copy per project that drifts.

A project with something project-specific to say (a note on known-broken areas, its own escalation path, anything beyond the shared etiquette) writes its own docs/guide/contributing.md. That file is discovered the same way as any other guide page, and it replaces the engine's default outright.

This is the general shape for any future default page: the engine's discover-doc-ids adds its own basenames to a project's guide-dir root group (never a nested subdirectory) for names the project has not written itself, and doc-source resolves each one to the project's file if it exists, else the engine's bundled default. contributing.md is the only one today.

Markdown

Standard markdown through markdown-clj, plus:

  • Syntax highlighting for Clojure and Scheme, via a vendored highlight.js.
  • A ```mermaid fence becomes a rendered diagram, themed to match the reader's light or dark setting.
  • Links between guide pages are rewritten from .md to .html, including across subdirectories.
  • Long reference pages get their <h2> sections wrapped in collapsible <details>. Anchors, in-page find and printing still work.
  • Every <h1>/<h2>/<h3> gets a small # link to that section, hidden until you hover or tab to it, like the ones GitHub and Sphinx put on their headings. It's a plain hash link with no clipboard script.

Publishing

The project's own workflow does the deploying. See raylib-jlt for a working one to copy: it checks this repo out at a tag, builds, asserts the output is not empty, and deploys to Pages from main only.

Pin a tag rather than tracking main, so a change here cannot break a project's docs build without someone choosing it.

Where this came from

A trimmed port of a private single-author engine, reduced to one site and given base-path support for the organization site (jlt-commons.github.io), then extracted here and generalized: project-supplied config and templates, asset directories, a generic homepage, and mermaid.

The organization site still carries its own copy of the earlier port. Moving it onto this engine is worth doing and has not been done yet.

About

The shared static-site generator behind jlt-commons project documentation

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages