cljdoc-exerciser.core — org.cljdoc/cljdoc-exerciser 1.0.76

Here we look at cljdoc features for APIs

Namespace docstrings can contain markdown.

And should support links repo to articles and inline repo images

Wikilinks work from namespace docstrings:

• a var local to this namespace exercise7
• a different namespace cljdoc-exerciser.ns2
• a var in a different namespace cljdoc-exerciser.ns2/whatever

Wikilink syntax [[that does not resolve to any var or ns]] is not converted to a link, this includes any typos like [[cljdoc-exerciser.ns2/whatevs]] [[cljdoc-exorcisor.core]]

exercise1 clj/s

(exercise1 d e f)

Will someone ever link to me?

exercise2 clj/s

(exercise2)

A function docstring can contain CommonMark formatted text.

Lists

1. one
2. two
   • buckle
     • my
       • shoe

Blockquotes

A quote

a nested quote

a very nested quote

Paragraphs

If you want a paragraph to include a linebreak,
you can do that.

Tables

Tables are a CommonMark extension but supported by cljdoc

Left	Centered	Right
lets	peanut butter	100
fill	and	10
this	pickles	1

Code blocks

(defn exercise
  "A docstring can contain CommonMark formatted text."
  []
  (+ 4 5 6))

Links

An external link to the CommonMark website.

A docstring can reference resources on GitHub. You'll need to use a GitHub root relative link for this. Root relative links start with /. A root relative link has the following benefits:

• it will also work when users decide to download your cljdocs into an offline bundle
• does not specify project coords, making it GitHub fork friendly

Examples:

• an imported article will be shown on cljdoc
• another resource will link you to GitHub
• specifying a relative link results in error link

Wikilinks

Wikilinks are a cljdoc extension to CommonMark and allow you to link to API functions. They only work in docstrings:

• a var local to this namespace exercise1
• a different namespace cljdoc-exerciser.ns2
• a var in a different namespace cljdoc-exerciser.ns2/whatever

Wikilink syntax [[that does not resolve to any var or ns]] is not converted to a link, this includes any typos like [[cljdoc-exerciser.ns2/whatevs]] [[cljdoc-exorcisor.core]]

exercise3 clj/s

(exercise3 x y z)

Linking to images might be of interest.

Specify your images as root relative (starting with a /):

Otherwise they will result in errored references:

An external image should work fine too:

exercise4 clj/s

(exercise4 a b c)

Using headings in a docstring might be ridiculous, but you can do it.

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

this is too much, I am heading home.

exercise5 cljs

(exercise5 j s)

This function is for ClojureScript only.

exercise6 clj

(exercise6 j v m)

This function is for Clojure only.

exercise7 clj/s

(exercise7)

How does a docstring handle embedded html?

It is not <b>bold</b> enough to render it.