A Codox writer that generates Markdown documentation instead of HTML, designed for embedding API docs in Clojure library JARs as classpath resources.
Clojure libraries ship source in JARs, but not documentation. codox-md adds Markdown API docs to your JAR at build time, under a namespaced path (docs/<group>/<artifact>/) that avoids conflicts with other libraries. These docs can then be discovered and browsed at runtime using clj-doc-browse.
codox-md provides two things:
codox.writer.markdown— A Codox-compatible writer that emits.mdfiles instead of HTMLcodox.md.build— A build-time helper that integrates withclojure -T:build, usingcreate-basisandDynamicClassLoaderto load your project's dependencies and Codox in-process
;; deps.edn
:build {:deps {io.github.clojure/tools.build
{:git/tag "v0.10.10" :git/sha "deedd62"}
slipset/deps-deploy {:mvn/version "0.2.2"}
com.dcj/codox-md {:mvn/version "0.1.0"}}
:ns-default build}(ns build
(:refer-clojure :exclude [test])
(:require [clojure.tools.build.api :as b]
[codox.md.build :as doc]
[deps-deploy.deps-deploy :as dd]))
(def lib 'com.example/my-lib)
(def version "0.1.0")
(def class-dir "target/classes")
(defn ci [opts]
;; ... (test, delete target, write pom) ...
(let [opts (jar-opts opts)]
(b/write-pom opts)
;; Generate Markdown API docs
(doc/generate-docs {:lib lib :version version
:description (:description opts)
:source-uri (str (get-in opts [:scm :url])
"/blob/{git-commit}/{filepath}#L{line}")})
;; Include generated docs in the JAR
(b/copy-dir {:src-dirs ["resources" "src" "target/doc-resources"]
:target-dir class-dir})
(b/jar opts))
opts)clojure -T:build ciYour JAR now contains:
docs/com.example/my-lib/
index.md # Library overview + namespace listing
my.namespace.md # Full API docs per namespace
guides/ # Optional, from doc/ directory
Each namespace file includes:
- Namespace docstring
- All public vars sorted alphabetically
- Type badges (function, macro, protocol, multimethod, var)
- Full arglists as Clojure code blocks
- Docstrings
- Source links (using
{git-commit}for stable GitHub URLs) - Deprecation and version annotations
- Protocol members nested under their protocol
The :source-uri option supports these placeholders:
| Placeholder | Value |
|---|---|
{filepath} |
Path relative to project root (e.g. src/my/ns.clj) |
{classpath} |
Classpath-relative path (e.g. my/ns.clj) |
{line} |
Line number |
{version} |
Project version string |
{git-commit} |
Current HEAD commit SHA |
- Clojure 1.12+ (uses
DynamicClassLoaderfor in-process dep loading) - Codox 0.10.8 (loaded dynamically at build time, not a compile-time dependency)
Libraries with embedded docs become queryable by AI coding assistants. With Claude Code and clojure-mcp, a /deps-docs skill lets Claude read your dependency docs at the REPL instead of relying on training data or web search.
Create ~/.claude/commands/deps-docs.md with these capabilities:
/deps-docs— list libraries with embedded docs on the classpath/deps-docs some.namespace— fetch API docs for a namespace/deps-docs group/artifact— list documented namespaces in a library/deps-docs search query— full-text search across all docs/deps-docs setup— add clj-doc-browse to a project's:nreplalias and CLAUDE.md
The skill uses the clojure-mcp nREPL eval tool to call doc.browse functions. When Claude needs to understand a dependency's API, it can pull the docs directly instead of guessing. This is especially valuable for private or niche libraries that aren't in the model's training data.
See the deps-docs skill source for the full implementation.
- clj-doc-browse — Runtime classpath scanner that discovers and reads these embedded docs
- clj-doc-browse.el — Emacs/CIDER integration for browsing docs from the REPL
Copyright (C) 2026 Clark Communications Corporation