The clojuredocs.org webapp
A few ways to contribute:
- Find & report bugs: https://github.com/nubank/clojuredocs/issues
- Suggestions on how to make development on the site more friendly (docs, codebase organization).
Docs under docs/ follow a metadata convention (see CLAUDE.md);
run bin/install-hooks once to enable the pre-commit check, or validate with
bb tools/validate_metadata.clj.
If you're looking for a project:
- Content for namespaces (see
src/md/namespaces) needs to be added / edited. Example of clojure.core.async - Listing of clojure training / classes / events on home page
- Stand-alone example page, maybe have the var info (signature, doc string, etc) at the top.
- Source-linking on libs not included in the standard library e.g. core.async.
Production runs on an AWS EC2 instance with nginx proxying to a single systemd-managed JVM process.
Every minute ./bin/deploy.sh runs and deploys the website if a new version is available.
See docs/release-protocol.md for the full release checklist, SSH setup, and smoke tests.
- Java (JDK 8+) (note prod build installs and runs
openjdk-17-jdk) - JCE Unlimited Strength Jurisdiction Policy Files
- lein
- entr (available in homebrew)
- babashka (
bb) (repo tooling + doc-metadata hook) - MongoDB
Start MongoDB, a backend REPL, and the CLJS build in separate terminals:
# terminal 1 — MongoDB
mongod --dbpath ./dev-db
# terminal 2 — backend REPL
source bin/.devenv
lein repl
# terminal 3 — ClojureScript build (only needed if you're touching src/cljs)
source bin/.devenv
lein fig:buildVisit http://localhost:4000 to verify.
See docs/dev-setup.md and docs/dev-setup-vscode.md for more.
The app uses a MongoDB database named clojuredocs to store data. Run bin/db-reset to seed the database with a recent production export (you must be running mongod for this to work).
The ClojureDocs project is set-up to emit source-maps for compiled javascript. To enable in Chrome, check the 'Enable JS source maps' option in the Developer Tools settings pane.
Clojure vars are pulled directly from the runtime, and are not stored in the database. When new versions of Clojure are released:
- Change the Clojure dep in
project.clj - Update the version string, source base url, and gh tag url in
clojuredocs.search/clojure-lib - Update the version for the mobile nav in
clojuredocs.pages.common - Update the github URL in
clojuredocs.pages.vars/source-url.
Interesting files:
src/clj/clojuredocs/main.clj-- Main entry-point into the app, starts the jetty serversrc/clj/clojuredocs/entry.clj-- Root routes and middlewaresrc/clj/clojuredocs/pages.clj-- User-facing HTML pagessrc/clj/clojuredocs/api.clj-- API endpoints for ajax calls from the frontend.src/cljs/clojuredocs/main.cljs-- Main js entry-point into the app
- Functions that return hiccup structures should be prefixed with a
$, like$layout. - Mutable state should be prefixed with a
!, ex:!my-atom.
Most vars are picked up from Clojure at runtime, using core namespace
and var introspection utilities. Special forms and namespaces to
include on the site are specified explicitly in the
clojuredocs.search.static namespace.
Vars are picked up automatically based on the namespaces specified in
clojuredocs.search.static/clojure-namespaces vector. Any namespace
in this vector will be queried for public vars to be made searchable
and displayable on the site.
Special forms are specified in the
clojuredocs.search.static/special-forms list, and require a server
restart to be picked up in a dev environment.
Sometimes we'd like to add core libraries that are not part of the standard Clojure distribution (like core.async) to the site. Here's how to do that:
- Add dependency to
project.clj - Add ns sym to
clojure-namespacesinclojuredocs.search.static - Add a short description + links to community articles / videos /
other resources to
src/md/namespaces/
- Dev starts the environment using
lein repl :headless, prod useslein run -m clojuredocs.main. See:repl-optionsinproject.cljfor initialization options.
- See also relations (ns/name -> [ns/name]), results cached for 1 minute.
Zachary Kim, Lee Hinman, and more.
Copyright © 2010-2025 Zachary Kim Copyright © 2025-present Nubank
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.