cljdoc: automated documentation hosting for the Clojure ecosystem

The problem is that publishing docs is manual and then goes stale

The README's rationale section is the clearest statement of the problem. Publishing Clojure library documentation is an often manual and error prone process. Library authors who want to provide documentation need to set up tooling to create such documentation, host it and keep it updated. In combination, all these steps introduce a significant amount of friction that often leads to there not being any HTML documentation at all. And if there is documentation it is often only a matter of time until it is out of date with the latest release. The summary line is blunt: publishing documentation is hard, and harder than it has to be. The proposed answer is to fully automate the process of publishing documentation, take that burden off library maintainers and let them focus on shipping libraries with good documentation. The secondary argument is about discovery, since a central place with a consistent user interface makes it easier for developers to find and work with documentation at all.

Goals that range from hosting to an ecosystem database

The goals list is broader than a docs site, and the third and fourth items are the ones that reach beyond documentation pages. The first goal is to provide an easy way to host library documentation for Clojure and ClojureScript library authors. The second is to deal with all the boring stuff, which the README names as hosting, updating and keeping old versions around. The third is to build an ecosystem-encompassing database, plus an API, of artifacts, namespaces and their contents. The fourth is to support API documentation, articles and examples. And the fifth is to encourage the writing of more and better documentation. That third goal is the ambitious one, because it is not a hosting arrangement but a data layer over the whole ecosystem, and it is what makes a central index of namespaces and their contents possible rather than just a set of rendered pages. The README suggests that centralising the publishing process lets the project build up a global understanding of the Clojure and ClojureScript ecosystem, enabling more interesting use cases down the road.

The comparison that is actually available: hosting docs yourself

There is a real alternative available here, and it is the one the README itself describes as the status quo. A library can ship its own documentation: the author picks a documentation generator, runs it in their build, and publishes the result to a static host or a CI artifact, with a badge in the README pointing at it. The difference in approach is exactly what the project is arguing about. The self-hosted route puts the tooling, the hosting and the keeping-updated on the maintainer, which is the friction the project names. The cljdoc route moves publishing to a service that observes the artifact repository and builds documentation from a released version, so the thing the reader sees tracks what was actually released. The cost of the centralised route is that the library's documentation now depends on a third party being up, and on that service choosing a configuration the maintainer accepts.

What is in the repository, and how a contributor gets oriented

The top-level layout shows a full Clojure application. There is a src directory for the server side, a front-end directory, a modules directory, a resources directory and a doc directory, alongside build.clj and build_shared.clj for the build, deps.edn, bb.edn for a bb task runner, and a tests.edn. There are also several tool configuration files that suggest the project keeps its own house style: a .cljfmt.edn, a .clj-kondo directory for the linter, a .lsp directory, a .prettierrc.json for the front end, an .editorconfig, a .sdkmanrc and a .tool-versions, and a .circleci directory for continuous integration. The contributing section points at three things in order. Read the contributing document, get up and running by following the steps in the document about running cljdoc locally, and understand why things are the way they are by reading the architecture decision records linked from the contributing document. That last one is unusual to call out and worth taking seriously, because it tells you the project expects contributions to be argued for, not just submitted.

A Preact front end over a Clojure server

The front end is deliberately small. The package manifest for the web part lists three dependencies.

{
  "name": "cljdoc",
  "type": "module",
  "dependencies": {
    "elasticlunr": "0.9.5",
    "idb": "8.0.4",
    "preact": "11.0.1"
  }
}

That is elasticlunr at 0.9.5, which is the Lunr search implementation, idb at 8.0.4, which is a wrapper over the browser's IndexedDB, and preact at 11.0.1. The choice of Preact over a larger framework is consistent with a documentation site that needs to render API pages and a search box rather than an application. The IndexedDB dependency is the interesting one for the scale of the project, because a client-side store is what lets you search a large namespace index without a round trip for every keystroke, which is the piece that makes the third goal, an ecosystem-encompassing database of artifacts and namespaces, usable in a browser. cljdoc itself is EPL-2.0 licensed, and the repository is not archived, with the last push on 2026-10-22.

A community project with a small core team and a large contributor list

The contributor list in the README is long and includes some of the most recognisable names in the Clojure community, with the count kept in the document as a generated field rather than typed by hand. The project was started by Martin Klepsch, and the README points to his ClojuTRE talk as a good introduction to what cljdoc is and why it exists, with a text version of the rationale in the same document for anyone who would rather not watch a video. Support runs through several channels at once: a Telegram group, a Twitter account and the Clojurians Slack channel in a dedicated cljdoc room, and the question in the README is framed as a greeting rather than a support request, which says something about the culture the project wants. The licence is EPL-2.0, and there are no GitHub releases, so the deployment history is not visible from the repository.

Editorial conclusion

cljdoc fits a Clojure library maintainer who wants hosted, always-current API documentation without maintaining a docs toolchain, and a reader who wants one searchable place for the ecosystem. It does not fit a team whose library already has a working docs pipeline, and it does not fit a non-Clojure project. Read the library author guide before you add a badge, because the site expects a particular configuration rather than any HTML it is given.

Frequently asked questions

Official sources

1. cljdoc/cljdoc on GitHub
2. Issues
3. License: EPL-2.0
4. Project website
5. README