1 Overview

Codox is a documentation generation tool for the Clojure programming language. It parses Clojure source files, extracts function definitions, macros, and type annotations, and produces static HTML or Markdown documentation. Widely used within the Clojure ecosystem, Codox emphasizes minimal configuration and supports custom themes and namespace grouping. It is maintained as an open-source project and is often integrated into Clojure build pipelines via Leiningen or deps.edn.

1.1 Purpose

Codox was created to address the need for a lightweight, low‑friction documentation generator tailored to Clojure projects. Its primary purpose is to automatically produce human‑readable reference documentation from the docstrings, metadata, and type annotations present in source code. By parsing namespaces, vars, macros, and protocols, Codox surfaces the intended API to developers and end‑users without requiring them to read the source directly. It aims to be configurable enough to fit various project layouts and decorative preferences while remaining simple to set up.

1.2 History

1.2.1 Origin and development

Codox was first released in 2012 by Justin Balthrop (known in the Clojure community as “weavejester”). Motivated by the shortcomings of existing tools—particularly their heavy reliance on runtime reflection and complex configuration—Balthrop designed Codox as a static analyzer that could work reliably with just the source files. The initial version focused on HTML output and a single built‑in theme. Over time the project gained community contributions, including support for Markdown export and additional customization hooks.

1.2.2 Key versions

  • 0.6.x (2013): Introduced support for custom themes and namespace grouping.
  • 0.8.x (2015): Added Markdown output as a separate renderer; improved handling of multimethods and protocols.
  • 0.9.x (2017): Switched the default render engine to use Clojure’s hiccup library, making theme development easier; added support for :exclude patterns.
  • 0.10.x (2019): Officially supported deps.edn integration alongside Leiningen; improved Windows compatibility.
  • 1.0.x (2022): Stabilised the API with backward‑compatible enhancements, better error reporting, and updated default theme.

2 Features

2.1 Source code analysis

Codox works by reading Clojure source files as static data, using Clojure’s built‑in reader to parse the code into forms. It then walks those forms to locate definitions of vars, functions, macros, multimethods, protocols, and types. The analysis respects the project’s classpath but does not require compiling or loading the code, making the process fast and side‑effect‑free.

2.1.1 Parsing metadata and docstrings

Each top‑level def form in Clojure can carry metadata, including the :doc key that holds a docstring. Codox extracts all such metadata and renders it in the documentation output. It also recognizes and presents custom metadata keys (e.g., :deprecated, :see-also) when they are defined in the namespace’s metadata or in a separate configuration file. The tool preserves formatting of multiline docstrings, optionally converting them to proper HTML paragraphs or Markdown.

2.1.2 Handling multimethods and protocols

Multimethods and protocols are first‑class constructs in Clojure, and Codox parses them with appropriate structure. For a multimethod, it records the dispatch function (or method) and lists all associated defmethod implementations that appear in the source. For a protocol, it extracts each method signature defined in the defprotocol form, including its docstring and argument names. Implementations (via extend-type or extend-protocol) are not automatically collected unless they are in the scanned source; Codox focuses on the abstract definition rather than every concrete extension.

2.2 Output formats

2.2.1 HTML generation

The default output of Codox is a set of static HTML files. It generates a main index page displaying all documented namespaces, with sidebars for navigation and a searchable list of vars. Each namespace gets its own page containing an alphabetic listing of its public vars, including their signatures, docstrings, source code links, and metadata. The HTML is styled using the built‑in “default” theme, but can be overridden with custom themes.

2.2.2 Markdown export

When configured with the :output :markdown option, Codox produces Markdown files instead of HTML. This is useful for projects that publish documentation on platforms like GitHub (where .md files are automatically rendered) or for integration with static site generators. The Markdown output preserves the same information structure: a top‑level index file and per‑namespace files, with code blocks for signatures and inline formatting for docstrings.

2.3 Customization

2.3.1 Themes and styling

Codox supports custom themes, which are Clojure namespaces that implement a specific protocol for rendering HTML pages. A theme can override the overall layout, the CSS, the navigation sidebar, and the way individual vars are displayed. The default theme is codox.theme.default. Users can create their own theme by copying the default and modifying the Hiccup templates. The theme is selected via the :theme configuration key.

2.3.2 Namespace grouping and ordering

By default, Codox lists namespaces in alphabetical order. Users can define custom groups with the :namespaces configuration option, which accepts a map of group labels to a list of namespace symbols. Groups are displayed as separate sections in the output; namespaces not assigned to any group are placed in a generic “Other” section. The order of groups and namespaces within groups follows the order given in the configuration map.

3 Usage

3.1 Installation

3.1.1 Leiningen plugin

For projects using Leiningen, add the following to project.clj under the :plugins vector:

[lein-codox "0.10.8"]

Then run lein codox to generate documentation. The plugin automatically picks up the project’s source paths.

3.1.2 deps.edn integration

In a deps.edn project, include Codox as an alias:

{:aliases {:codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
                   :main-opts ["-m" "codox.main"]}}}

Invoke with clojure -M:codox (or clojure -X:codox for tools.deps execution).

3.2 Configuration

3.2.1 Basic options

The simplest configuration requires only the project name and version. In Leiningen project.clj, these are read automatically. For deps.edn, they are set in a codox.edn file or passed as arguments. Key basic options include:

  • :name – project name (default: from project metadata)
  • :version – project version (default: from project metadata)
  • :source-uri – a template for linking source files (e.g., "https://github.com/…/blob/main/{filepath}#L{line}")

3.2.2 Advanced options (source paths, exclude patterns)

Codox accepts a :source-paths vector to specify which directories to scan. By default it scans all paths listed in the project configuration (e.g., src). Exclude patterns can be provided via :exclude-vars (a regex matching var names) or :exclude-namespaces (a regex matching namespace symbols). Additionally, :metadata entries can be merged into every var’s metadata (useful for adding a :doc to undocumented vars that should appear anyway).

3.3 Running Codox

3.3.1 Command‑line invocation

Regardless of the build tool, running Codox produces a doc (or custom‑named) directory containing the HTML or Markdown output. For example:

lein codox
# or
clojure -M:codox

The tool prints a summary of scanned namespaces and generated files. If errors occur (e.g., a file cannot be parsed), Codox reports them to stderr but continues with other files.

3.3.2 Integration with CI/CD

Codox is commonly added as a step in continuous integration pipelines. A typical workflow: generate documentation on every push to the main branch, then deploy the doc directory to GitHub Pages or upload it to Clojars. Leiningen users can create a separate profile (:deploy-doc) that includes the lein-codox plugin and runs codox during the release process.

4 Project structure

4.1 Documentation source code layout

There is no mandatory layout for documentation sources in Codox; the tool operates directly on the project’s Clojure source files. However, projects often place additional Markdown or HTML assets (e.g., a README.md to be included as a landing page) in a doc/ directory at the project root. Codox can be configured to include such files via the :doc-files option.

4.2 Generated output directory

By default, Codox writes all generated files to a doc/ directory in the project root. The structure inside is:

doc/
├── index.html          (or index.md for Markdown)
├── css/
│   └── default.css     (or custom theme CSS)
├── js/
│   └── search.js       (for client‑side search in HTML output)
└── namespaces/
    ├── my-namespace.html
    └── another.namespace.html

Users can change the output directory with the :output-dir configuration key.

5.1 Comparison with other Clojure documentation tools

5.1.1 Marginalia

Marginalia is an older documentation generator that produces a single HTML page with code and documentation (docstrings, comments) interleaved. It focuses on literate programming style. Compared to Codox, Marginalia requires the project to be compiled (it uses AOT) and produces less structured output (no per‑namespace pages, no search). Codox is preferred for API reference documentation, while Marginalia suits tutorials or annotated source walkthroughs.

5.1.2 Autodoc

Autodoc is a comprehensive, multi‑language tool (part of the Quicklisp family) that supports Clojure through a plugin. It offers more advanced features like cross‑referencing between projects and automatic changelog generation. However, Autodoc is heavier to configure (requiring a YAML file) and its Clojure support has not been actively maintained as of the 2020s. Codox remains more popular within the Clojure community due to its simplicity and tight integration with the Clojure toolchain.

5.2 Integrations

5.2.1 GitHub Pages deployment

Many Clojure projects host their Codox output on GitHub Pages. The typical setup involves a CI job (e.g., GitHub Actions) that runs lein codox or clojure -M:codox, then pushes the doc directory to the gh-pages branch. Alternatively, projects can use a static site generator like Jekyll to incorporate the generated Markdown pages.

5.2.2 Clojars hosting

Clojars, the primary Clojure artifact repository, allows documentation to be uploaded alongside JAR files. A project can include a doc/ directory in its deployed JAR, and Clojars will serve it at a URL like https://clojars.org/my-group/my-project/doc/. Codox’s output is ideal for this because it is self‑contained (no server‑side dependencies). Many libraries on Clojars use this feature to provide quick‑access API docs without needing a separate website.

6 Community and maintenance

6.1 Repository and contribution guidelines

Codox is hosted on GitHub at weavejester/codox. The repository contains the source code, issue tracker, and wiki. Contributions are welcome; the maintainers ask that changes be accompanied by tests and that any new features be discussed via issues before submission. Pull requests are reviewed for code quality, backward compatibility, and alignment with the project’s minimal‑configuration philosophy.

6.2 License

Codox is distributed under the Eclipse Public License (EPL), version 1.0 (the same license as Clojure itself). This allows anyone to use, modify, and redistribute the tool, provided they include the original copyright notice and disclaimer.

6.3 Notable projects using Codox

Several prominent Clojure libraries and frameworks rely on Codox for their documentation, including:

  • Ring – The web application library uses Codox for its API reference.
  • Compojure – A routing library built on Ring.
  • ClojureScript core libraries (e.g., cljs.core documentation) historically have used Codox to generate pages.
  • Luminus – A web framework that generates Codox documentation as part of its project templates.
  • Hiccup – The HTML templating library (also by Balthrop) is documented with Codox.

These projects demonstrate Codox’s role as the de‑facto standard documentation generator for Clojure libraries that value clarity and simplicity.