Codox Documentation

You can use Clojure metadata to influence how Codox generates documentation:

• ^:no-doc true: Skips a var or a namespace from being documented. (Note: :no-doc on namespaces currently only works for Clojure, not ClojureScript).
• ^:added "1.0": Denotes the version in which the var was added.
• ^:deprecated "2.0": Denotes that the var is deprecated.

;; Skip documentation for this var
(defn ^:no-doc hidden-square [x] (* x x))

;; Mark version and deprecation
(defn square
  {:added "1.0" :deprecated "2.0"}
  [x] (* x x))

To use Codox with Boot, add boot-codox to your build.boot dependencies and require the codox.boot namespace. You can run the codox task via the Boot CLI or directly in a REPL. To ensure files are written to the correct location, use the target task.

(set-env! :dependencies '[[boot-codox "0.10.8" :scope "test"]])
(require '[codox.boot :refer [codox]])

# View help
boot codox -h

# Run codox and output to target
boot codox target

To use Codox in a Leiningen project, add the lein-codox plugin to your project.clj file or your global profile. You can then generate documentation by running the lein codox command. By default, the documentation is generated in the target/doc directory (or your project's configured :target-path).

:plugins [[lein-codox "0.10.8"]]

lein codox

When using the :markdown docstring format, you can use wikilink-style relative links to reference other vars. Codox will first attempt to match the link within the current namespace, and if no match is found, it will search across all documented vars for the best match.

(defn bar
  "See [[foo]] and [[user/square]] for other examples."
  {:doc/format :markdown}
  [x])

By default, Codox renders docstrings as fixed-width plain text. You can override this to use markdown format, which supports code blocks, tables, and automatic URL linking.

You can set the format in two ways:

1. Per-var: Use the :doc/format metadata option on a specific function or variable.
2. Globally: Set the :doc/format in the :metadata map within your :codox configuration in project.clj.

;; Per-var configuration
(defn foo
  "A **markdown** formatted docstring."
  {:doc/format :markdown}
  [x])

;; Global configuration in project.clj
:codox {:metadata {:doc/format :markdown}}

To use Codox with deps.edn, define a :codox alias. This alias must include :extra-deps, :exec-fn (pointing to codox.main/generate-docs), and :exec-args for configuration.

Note: When using deps.edn, all project options (like :source-paths or :output-path) must be placed inside the :exec-args map. Additionally, Codox requires the code it analyzes to be on the classpath, so you may need to include additional aliases (e.g., clojure -X:dev:codox).

:codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
        :exec-fn codox.main/generate-docs
        :exec-args {:source-paths ["path/to/src"]}}

clojure -X:codox

Codox can include Markdown files (.md or .markdown) in the documentation.

• :doc-paths: A vector of directories to search for documentation files (default is doc).
• :doc-files: A vector of specific files to include. If this is set, :doc-paths is ignored.
• :output-path: Specifies the directory where documentation is written (default is target/doc).
• :writer: The fully qualified symbol of a custom writer function (e.g., codox.writer.html/write-docs).
• :project: A map to override default project metadata: {:name "Name", :version "1.0", :description "Desc"}.

:codox {:doc-paths ["path/to/docs"]
        :output-path "codox"
        :project {:name "Example" :version "1.0" :description "N/A"}}

The :source-uri option allows you to create links from the documentation back to the source code. It accepts a URI template containing several placeholders:

• {filepath}: File path from the repository root.
• {basename}: The basename of the file.
• {classpath}: Relative path within the source directory.
• {line}: The line number.
• {version}: The project version.
• {git-commit}: The Git commit ID.

You can provide a single template or a map of regex-to-template to handle different parts of your source tree differently.

:codox {:source-uri "https://github.com/foo/bar/blob/{version}/{filepath}#L{line}"}

;; Mapping different templates to different paths
:codox {:source-uri
       {"target/classes" "https://github.com/foo/bar/blob/master/src/{classpath}x#L{line}"
        ".*"             "https://github.com/foo/bar/blob/master/{filepath}#L{line}"}}

Codox uses :source-paths to find source files. You can restrict which namespaces are documented using the :namespaces option.

Supported values for :namespaces:

• A vector of specific namespaces: [library.core library.io]
• A regular expression: [#"^library\."]
• A negative lookahead regex to exclude specific patterns: [#"^library\.(?!internal)"]
• The keyword :all (default) to include everything.

You can also exclude specific vars using :exclude-vars with a regular expression. By default, record constructor functions (e.g., ->Foo) are excluded.

;; Set source paths
:codox {:source-paths ["path/to/source"]}

;; Restrict to specific namespaces
:codox {:namespaces [library.core library.io]}

;; Use regex for namespaces
:codox {:namespaces [#"^library\."]}

;; Exclude specific vars
:codox {:exclude-vars "^(map)?->\p{Upper}"}