bb-tasks

Reusable babashka tasks for Outskirts Labs projects.

Available tasks

gen-api-docs

Generates AsciiDoc API reference pages from Clojure source using clj-kondo static analysis. Produces one .adoc page per public namespace, a machine-readable API index for cross-project links, and a nav partial for Antora.

sync-readme

Syncs a project's README.adoc as its Antora index page, rewriting relative doc links to Antora xrefs. If present, it also syncs CHANGELOG.adoc, CONTRIBUTING.adoc, and SECURITY.adoc into Antora pages.

sync-top-level-docs

Alias task for non-Clojure repos that only need top-level AsciiDoc docs synced into the Antora tree (README.adoc, optional CHANGELOG.adoc, CONTRIBUTING.adoc, SECURITY.adoc).

publish-clojars

Prompts for a Clojars deploy token, exports CLOJARS_USERNAME and CLOJARS_PASSWORD, then runs clojure -T:build deploy.

gen-manifest

Generates <antora-start-path>/manifest.edn from deps.edn [:aliases :neil :project] metadata and doc/antora.yml.

Setup

Add bb-tasks as a git dependency in your project's bb.edn:

{:deps {outskirtslabs/bb-tasks
        {:git/url "https://github.com/outskirtslabs/bb-tasks"
         :git/sha "<commit-sha>"}}
 :pods {clj-kondo/clj-kondo {:version "2026.01.19"}}
 :tasks
 {:requires ([ol.bb-tasks.gen-api-docs :as gen-api]
             [ol.bb-tasks.gen-manifest :as gen-manifest]
             [ol.bb-tasks.publish-clojars :as publish-clojars]
             [ol.bb-tasks.sync-readme :as sync-readme])
  sync-readme
  {:doc "Sync README.adoc as Antora index page"
   :task (sync-readme/sync! {:antora-start-path "doc"})}
  gen-api-docs
  {:doc "Generate API docs"
   :task (gen-api/generate! {:project-root "."
                             :source-paths ["src"]
                             :antora-start-path "doc"
                             :github-repo "https://github.com/your-org/your-repo"
                             :git-branch "main"})}
  gen-manifest
  {:doc "Generate doc/manifest.edn"
   :task (gen-manifest/generate! {:antora-start-path "doc"})}
  publish
  {:doc "Publish the jar to Clojars"
   :depends [jar]
   :task (publish-clojars/publish!)}}}

The clj-kondo pod declaration is required in the consuming project's bb.edn -- pods cannot be transitively loaded from dependencies.

gen-api-docs options

generate! accepts a map with:

Key	Description
:project-root	Absolute or relative path to the project root
:source-paths	Vector of source paths relative to project-root
:antora-start-path	Path to the Antora component root (e.g. "doc")
:github-repo	GitHub repo URL for source links
:git-branch	Git branch name for source links
:external-api-index-paths	Explicit paths to other projects' <antora-start-path>/api-index.edn files. Only these documented projects are eligible for cross-project [[...]] xrefs.
:external-api-indexes	Already-loaded API index maps, useful for programmatic callers and tests.
:fail-on-unresolved-wikilinks?	When true, throw for any unresolved [[...]]; otherwise unknown refs render as inline code. Known local/external docs targets still throw when the namespace exists but the var does not.

Cross-project Clojure wikilinks use explicit API indexes. Example:

(gen-api/generate!
 {:antora-start-path "doc"
  :external-api-index-paths ["../clave/doc/api-index.edn"]})

With that index loaded, [[ol.clave.certificate]] emits an Antora xref like xref:next@ol.clave::api/ol-clave-certificate.adoc[...], which Antora later turns into the correct relative HTML link.

sync-readme options

sync! accepts a map with:

Key	Description
:readme-path	Path to the README file (default "README.adoc")
:changelog-path	Optional path to changelog file (default "CHANGELOG.adoc")
:contributing-path	Optional path to contributing file (default "CONTRIBUTING.adoc")
:security-path	Optional path to security file (default "SECURITY.adoc")
:antora-start-path	Path to the Antora component root (default "doc")

For non-Clojure repos (or repos that only need top-level docs sync):

sync-top-level-docs
{:doc "Sync top-level AsciiDoc docs into Antora pages"
 :task (sync-readme/sync-top-level-docs! {:antora-start-path "doc"})}

gen-manifest options

generate! accepts a map with:

Key	Description
:project-root	Absolute or relative path to the project root (default ".")
:antora-start-path	Path to the Antora component root (default "doc")
:github-repo	Optional explicit GitHub repo URL override

publish-clojars options

publish! accepts a map with:

Key	Description
:project-root	Directory to run the deploy command from (default ".")
:username	Clojars username (default "ramblurr")
:token	Optional deploy token override. If omitted, bb-tasks prompts for it
:prompt	Prompt string shown when asking for the token
:command	Command vector to run instead of ["clojure" "-T:build" "deploy"]

Output

gen-api-docs produces (for each public namespace, excluding :no-doc and :skip-wiki):

• <antora-start-path>/modules/ROOT/pages/api/<ns-slug>.adoc -- one page per namespace
• <antora-start-path>/modules/ROOT/pages/api.adoc and <antora-start-path>/modules/ROOT/pages/api/index.adoc -- API landing pages
• <antora-start-path>/modules/ROOT/partials/api-nav.adoc -- hierarchical nav snippet
• <antora-start-path>/api-index.edn -- machine-readable namespace/page/var-anchor index for cross-project wikilinks

The pages/api/ directory is cleared before each run to remove stale pages.

sync-readme produces:

• <antora-start-path>/modules/ROOT/pages/index.adoc -- copy of README.adoc with rewritten links
• <antora-start-path>/modules/ROOT/pages/changelog.adoc -- copy of CHANGELOG.adoc (if present)
• <antora-start-path>/modules/ROOT/pages/contributing.adoc -- copy of CONTRIBUTING.adoc (if present)
• <antora-start-path>/modules/ROOT/pages/security.adoc -- copy of SECURITY.adoc (if present)

gen-manifest produces:

• <antora-start-path>/manifest.edn -- normalized project metadata consumed by docs aggregation

Manifest :project contains:

• :id from doc/antora.yml component name.
• :coord from deps.edn [:aliases :neil :project :name] (group/artifact coordinate).
• :created from deps.edn [:aliases :neil :project :created] (ISO date YYYY-MM-DD).

Required metadata in deps.edn:

{:aliases
 {:neil
  {:project
   {:name "com.outskirtslabs/your-lib"
    :description "..."
    :license {:id "MIT"} ; SPDX identifier
    :platforms [:clj :bb]
    :created "2026-02-16"
    :status :maturing}}}}

Allowed status values:

• :experimental
• :maturing
• :stable
• :retired
• :static

License

Copyright (C) 2025 Casey Link https://casey.link

Licensed under the EUPL-1.2.