Skip to content
Clojure documentation tool
Clojure CSS JavaScript
Latest commit 5de3303 May 7, 2016 @weavejester Merge pull request #124 from metametadata/master
Suppress ClojureScript analyzer warnings
Failed to load latest commit information.
boot-codox Release 0.9.5 Apr 25, 2016
codox Suppress ClojureScript analyzer warnings May 6, 2016
example Release 0.9.5 Apr 25, 2016
lein-codox Release 0.9.5 Apr 25, 2016
.gitignore Add topic list to primary sidebar Oct 15, 2015 Release 0.9.5 Apr 25, 2016 Release 0.9.5 Apr 25, 2016


A tool for generating API documentation from Clojure or ClojureScript source code.



Include the following plugin in your project.clj file or your global profile:

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

Then run:

lein codox

This will generate API documentation in the "target/doc" subdirectory (or wherever your project :target-path is set to).


Add boot-codox to your build.boot dependencies and require the namespace:

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

You can see the options available on the command line:

$ boot codox -h

or in the REPL:

boot.user=> (doc codox)

Remember to output files to the target directory with boot's built-in target task:

$ boot codox target

Breaking Changes in 0.9

In preparation for a 1.0 release, Codox 0.9 has a number of breaking changes:

  • The Leiningen plugin has been changed from codox to lein-codox
  • The Leiningen task has been changed from lein doc to lein codox
  • The default output path has been changed from doc to target/doc
  • The :sources option has been renamed to :source-paths
  • The :output-dir option has been renamed to :output-path
  • The :defaults option has been renamed to :metadata
  • The :include and :exclude options have been replaced with :namespaces
  • All the :src-* options have been replaced with :source-uri

See the "Source Files" section for information on the :namespaces option, and the "Source Links" section for information on the :source-uri option.


Some examples of API docs generated by Codox in real projects:

AOT Compilation

AOT-compiled namespaces will lose their metadata, which mean you'll lose documentation for namespaces. Avoid having global :aot directives in your project; instead, place them in a specialized profile, such as :uberjar.

Project Options

Codox can generate documentation from Clojure or ClojureScript. By default it looks for Clojure source files, but you can change this to ClojureScript by setting the :language key:

:codox {:language :clojurescript}

Source Files

By default Codox looks for source files in the :source-paths of your project, but you can change this just for Codox by placing the following in your project.clj file:

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

The :namespaces option can be used to restrict the documentation to a specific set of namespaces:

:codox {:namespaces [library.core]}

Regular expressions can also be used for more general matching:

:codox {:namespaces [#"^library\."]}

For excluding only internal namespaces, it's sometimes useful to use negative lookahead:

:codox {:namespaces [#"^library\.(?!internal)"]}

To override the namespaces list and include all namespaces, use :all (the default):

:codox {:namespaces :all}

Codox constructs documentation from metadata on vars and namespaces. You can specify a set of default metadata using the :metadata map:

:codox {:metadata {:doc "FIXME: write docs"}}

Documentation Files

As well as source files, Codox also tries to include documentation files as well. By default it looks for these in the doc directory, but you can change this with:

:codox {:doc-paths ["path/to/docs"]}

Documentation files will appear in the output sorted by their filename, so if you want a particular order, prefix your files with 01, 02, etc.

Currently only markdown files (.md or .markdown) are supported.

Output Files

To write output to a directory other than the default, use the :output-path key:

:codox {:output-path "codox"}

To use a different output writer, specify the fully qualified symbol of the writer function in the :writer key:

:codox {:writer codox.writer.html/write-docs}

By default the writer will include the project name, version and description in the output. You can override these by specifying a :project map in your Codox configuration:

:codox {:project {:name "Example", :version "1.0", :description "N/A"}}

Source Links

If you have the source available at a URI and would like to have links to the function's source file in the documentation, you can set the :source-uri key:

:codox {:source-uri "{version}/{filepath}#L{line}"}

The URI is a template that may contain the following keys:

  • {filepath} - the file path from the root of the repository
  • {basename} - the basename of the file
  • {classpath} - the relative path of the file within the source directory
  • {line} - the line number of the source file
  • {version} - the version of the project

You can also assign different URI templates to different paths of your source tree. This is particularly useful for created source links from generated source code, such as is the case with cljx.

For example, perhaps your Clojure source files are generated in target/classes. To link back to the original .cljx file, you could do:

 {#"target/classes" "{classpath}x#L{line}"
  #".*"             "{filepath}#L{line}"}

HTML Transformations

The HTML writer can be customized using Enlive-style transformations. You can use these to modify the HTML documents produced in arbitrary ways, but the most common use is to add in new stylesheets or scripts.

The transforms live in the :transforms key, in the :html map, and consist of a vector that matches selectors to transformations, in the same way that let matches symbols to values.

For example, the following code adds a new <script> element as the last child of the <head> element:

:html {:transforms [[:head] [:append [:script "console.log('foo');"]]]}

The selectors follow the Enlive selector syntax.

The transformations are a little different. There are five transforms, :append, :prepend, :after, :before and :substitute. These match to the corresponding Enlive transformations, but expect Hiccup-style arguments.

HTML Output Options

The HTML writer also has one other customization option.

By default the namespace list is nested, unless there is only one namespace in the library. To override this, set the :namespace-list option in the :html map to either :nested or :flat.

:html {:namespace-list :flat}

Metadata Options

To force Codox to skip a public var, add :no-doc true to the var's metadata. For example:

;; Documented
(defn square
  "Squares the supplied number."
  (* x x)

;; Not documented
(defn ^:no-doc hidden-square
  "Squares the supplied number."
  (* x x))

You can also skip namespaces by adding :no-doc true to the namespace's metadata. This currently only works for Clojure code, not ClojureScript. For example:

(ns ^:no-doc hidden-ns)

To denote the library version the var was added in, use the :added metadata key:

(defn square
  "Squares the supplied number."
  {:added "1.0"}
  (* x x))

Similar, deprecated vars can be denoted with the :deprecated metadata key:

(defn square
  "Squares the supplied number."
  {:deprecated "2.0"}
  (* x x))

Docstring Formats

By default, docstrings are rendered by Codox as fixed-width plain text, as they would be on a terminal. However, you can override this behavior by specifying an explicit format for your docstrings.

Currently there are only two formats for docstrings: plaintext and markdown. The markdown format includes extensions for code blocks, tables, and, like the plaintext format, URLs are automatically encoded as links.

You can specify docstring formats via a var's metadata, using the :doc/format option:

(defn foo
  "A **markdown** formatted docstring."
  {:doc/format :markdown}

Or you can specify the docstring format globally by adding it to the :metadata map in your project.clj file:

:codox {:metadata {:doc/format :markdown}}

Markdown docstrings also support wikilink-style relative links, for referencing other vars. Vars in the current namespace will be matched first, and then Codox will try and find a best match out of all the vars its documenting.

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


Copyright © 2016 James Reeves

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

Something went wrong with that request. Please try again.