FAQ

Short answers to common questions.

How do I set SCM info for my project?

Source Control Management (SCM) info is information about where the source of your project is stored. cljdoc extracts this information from the pom.xml that is uploaded to Clojars and usually generated by your build tool of choice. Below you can find some instructions on how to do so using Leiningen and Boot.

• Leiningen: Add a :scm key to your defproject, see sample.project.clj. Usually that might just look like

  :scm {:name "git" :url "https://github.com/your-username/your-project"}
  

• Boot: Pass the :scm option to the pom task, see example.

The resulting pom.xml should look somewhat like this although the exact fields may vary:

<scm>
  <connection>scm:git:git://github.com/laforge49/aatree.git</connection>
  <developerConnection>scm:git:ssh://git@github.com/laforge49/aatree.git</developerConnection>
  <tag>edb7cefa9a01852b101ed742b278aaba8d832b02</tag>
  <url>https://github.com/laforge49/aatree</url>
</scm>

Why do it?

1. It's nice because it shows up on Clojars and people will find your project more easily.
2. cljdoc uses your Git repo to gather additional information, without the SCM info we can only show API documentation and cannot provide a backlink to your Git repo.

Can we have badges?

Sure thing! cljdoc provides badges that will show the latest release version as well as an endpoint that redirects to it.

• Badge URL: https://cljdoc.org/badge/re-frame
• Redirect URL: https://cljdoc.org/jump/release/re-frame

Using it in a Markdown file may look like this:

[![](https://cljdoc.org/badge/re-frame)](https://cljdoc.org/jump/release/re-frame)

How to update documentation?

Sometimes you make adjustments to documentation after cutting a release. In these situations it would be nice to update the docs on cljdoc as well.

Now when cljdoc reads documentation from your Git repository it does not simply read it from master but instead tries to find a Git tag or a revision in your project's .pom. This means you can build documentation for older releases and generally decouples the output of the build from the time it was done.

This also means that to update documentation you need to cut a new release (for now).

I'd like to support some way to update docs after a release but it needs to be explicit and hasn't been decided upon yet, see issue #31 for some additional discussion.

SNAPSHOT releases will use master as Git revision as they usually have no tag in your repo or sha in a .pom. This can be useful for experimenting with cljdoc.

How does cljdoc compare to clojuredocs.org?

cljdoc has in many ways been inspired by clojuredocs.org but besides documenting Clojure itself, cljdoc tries to provide documentation for the library ecosystem around Clojure.

The projects are not related besides both pushing documentation in the Clojure ecosystem forward :hugs: