Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 7 additions & 16 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ on:
permissions:
contents: read

# The README says build, clean and test run under jolt as well as bb, so CI
# runs them under both. Pinned to a release so an overnight jolt change can't
# turn a docs-engine PR red; workflow_dispatch can try another version.
# The engine runs on jolt only. Pinned to a release so an overnight jolt
# change can't turn a docs-engine PR red; workflow_dispatch can try another
# version.
env:
JOLT_VERSION: ${{ inputs.jolt-version || '0.8.27' }}

Expand All @@ -32,14 +32,6 @@ jobs:
steps:
- uses: actions/checkout@v7

- name: Install babashka
uses: DeLaGuardo/setup-clojure@13.6.1
with:
bb: latest

- name: Test
run: bb test

# The prebuilt jolt binary is self-contained and lands in ~/.local/bin.
# The version comes in through env, not interpolated into the script,
# so the dispatch input can't inject shell.
Expand All @@ -52,10 +44,10 @@ jobs:
| bash -s -- --version "$JOLT_VERSION"
echo "$HOME/.local/bin" >> "$GITHUB_PATH"

- name: Test under jolt
- name: Test
run: |
jolt --version
jolt test
jolt run test

- name: Build under jolt
run: |
Expand All @@ -69,8 +61,7 @@ jobs:
grep -q 'href="/jolt-project/css/screen.css"' "$root/_site/guide/index.html" \
|| { echo "jolt build lost the base path"; exit 1; }

# serve binds with ring-chez-adapter under jolt (serve.jolt) and with
# http-kit under bb (serve.clj). This starts the jolt one on a free port
# serve binds with ring-chez-adapter. This starts it on a free port
# and checks it answers under the base path, 404s outside it, and
# returns a binary asset byte for byte.
- name: Serve under jolt
Expand Down Expand Up @@ -118,7 +109,7 @@ jobs:
> "$root/docs/templates/home.html"
printf 'GIF89a' > "$root/docs/media/x.gif"

bb build "$root"
jolt run build "$root"

out="$root/_site"
test -f "$out/index.html" || { echo "no homepage generated"; exit 1; }
Expand Down
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
_site/
.cpcache/
.bb/
.jolt/
.DS_Store
7 changes: 3 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ 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
`bb.edn` directly. External dependencies (`markdown-clj`, `selmer`, the
`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. Every task also still runs under babashka as `bb <task>`.
run.

## The idea

Expand Down Expand Up @@ -98,8 +98,7 @@ 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` under jolt and with `http-kit` under bb, so
`bb serve` works the same way.
with `ring-chez-adapter`.

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

Expand Down
26 changes: 10 additions & 16 deletions bb.edn → deps.edn
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
;; bb.edn — docs-engine, the shared static-site generator for jlt-commons
;; project documentation.
;; deps.edn: docs-engine, the shared static-site generator for jlt-commons
;; project documentation. It runs on jolt, which reads the :tasks below.
;;
;; Every task takes the path to a project checkout. The engine reads that
;; project's docs/ and writes its _site/, and touches nothing else.
Expand All @@ -10,9 +10,9 @@
;; resolvable under jolt. jolt-lang/yaml (below) supplies a
;; clj-yaml.core-compatible namespace that markdown.transformers'
;; own (:require [clj-yaml.core ...]) finds once the real one is
;; excluded, on both hosts -- no per-host branching needed.
;; excluded.
;;
;; Safe to exclude on EITHER host, not just untested-so-far: the
;; The exclusion is safe, not just untested-so-far: the
;; YAML branch only fires when a doc's first line is a literal
;; "---", and site.markdown's own unwrap-hard-wraps already
;; rewrites every "---"-only line to "***" before markdown-clj
Expand All @@ -27,24 +27,18 @@
:exclusions [clj-commons/clj-yaml]}
io.github.jolt-lang/yaml {:git/url "https://github.com/jolt-lang/yaml.git"
:git/sha "baeb011f040ea8167917b1d600ac601bb746fea2"}
;; babashka bundles selmer as a built-in, so this project never
;; needed to declare it before. jolt doesn't bundle it the same
;; way -- an explicit :mvn/version is what makes `jolt run build`
;; able to resolve selmer.parser at all (see docs-engine#3).
;; jolt doesn't bundle selmer, so an explicit :mvn/version is what
;; makes `jolt run build` able to resolve selmer.parser at all (see
;; docs-engine#3).
selmer/selmer {:mvn/version "1.13.5"}
;; Selmer's date filters reference java.time.format.FormatStyle at
;; namespace-load time (see docs-engine#3). jolt has no built-in
;; java.time shim, but requiring jolt-lang/time installs one, and
;; that happens below, before any task-specific require, so it's
;; in place before selmer.parser ever loads. Verified harmless
;; under bb too: pure Clojure, no jolt.ffi, tick.core/now works
;; unchanged (bb already has real java.time; this just adds tick's
;; API on top of it).
;; in place before selmer.parser ever loads.
io.github.jolt-lang/time {:git/url "https://github.com/jolt-lang/time.git"
:git/sha "cdd785069e0e08a16c1ea9aae60f9532de21fad8"}
;; The HTTP server behind `serve` under jolt. Only site/serve.jolt
;; requires it, and bb never loads that file (bb's serve.clj uses
;; http-kit, which bb bundles).
;; The HTTP server behind `serve`. Only site/serve.clj requires it.
io.github.jolt-lang/ring-chez-adapter {:git/url "https://github.com/jolt-lang/ring-chez-adapter.git"
:git/sha "387cf67ea7b6a8573c6ee6abca6026a45bc3b6bf"}}
:tasks
Expand All @@ -70,7 +64,7 @@
(println " jolt run test run the test suite")
(println " jolt run serve <project> [port] build, then serve at localhost:3000\n")
(println "Use jolt run <task>, not bare jolt <task>: build collides with jolt's own")
(println "build -m NS subcommand. Every task also runs under babashka as bb <task>.\n")
(println "build -m NS subcommand.\n")
(println "A project configures itself in docs/site.edn. See README.md."))}

test {:doc "Run the full test suite"
Expand Down
8 changes: 2 additions & 6 deletions src/site/core.clj
Original file line number Diff line number Diff line change
Expand Up @@ -380,12 +380,8 @@
;; Everything below builds a plain Ring handler `(fn [req]) -> {:status
;; :headers :body}` and touches no HTTP-server library at all, so it costs
;; build/clean/test nothing. site.serve is the thin wrapper that actually
;; binds a port: serve.clj with org.httpkit.server under bb/JVM, and
;; serve.jolt with ring-chez.adapter under jolt.
;; Splitting it this way is what makes build/clean/test loadable under jolt
;; at all — org.httpkit.server isn't resolvable there, and previously every
;; task here required it via this namespace regardless of whether it ever
;; started a server.
;; binds a port, with ring-chez.adapter. Only `serve` loads it, so
;; build/clean/test never pull in an HTTP server.

(defn- content-type [path]
(cond
Expand Down
21 changes: 9 additions & 12 deletions src/site/serve.clj
Original file line number Diff line number Diff line change
@@ -1,13 +1,9 @@
(ns site.serve
"The local preview server's bb/JVM half: the one function that actually
binds a port. site.core builds the Ring handler with no HTTP-server
library involved at all; this namespace is the thin wrapper around
org.httpkit.server that turns it into a running server.

Under jolt, site/serve.jolt replaces this file and binds with
ring-chez.adapter instead. No task other than `serve` requires this
namespace."
(:require [org.httpkit.server :as hk]
"The local preview server: the one function that actually binds a port.
site.core builds the Ring handler; this namespace binds it with
ring-chez.adapter, which runs over jolt's own sockets. No task other
than `serve` requires this namespace."
(:require [ring-chez.adapter :as adapter]
[site.core :as core]))

(defn serve!
Expand All @@ -18,8 +14,9 @@
(let [port (Integer/parseInt (or port-str "3000"))
output-dir (:output-dir project)
base (core/base-path (:base-path project))]
;; ring-chez binds 127.0.0.1 by default; :host says so explicitly, since
;; this is a local-only preview server.
(adapter/run-server (core/make-static-handler output-dir base)
{:port port :host "127.0.0.1"})
(println (str "Serving " output-dir " at http://localhost:" port base "/"))
;; :ip "127.0.0.1" — local-only dev preview server; without an
;; explicit :ip, http-kit binds all network interfaces by default.
(hk/run-server (core/make-static-handler output-dir base) {:port port :ip "127.0.0.1"})
@(promise)))
23 changes: 0 additions & 23 deletions src/site/serve.jolt

This file was deleted.

Loading