cljdoc CommonMark features

Introduction

A test CommonMark doc to exercise cljdoc formatting and features.

This document exists to compare basic features with AsciiDoctor. If you edit this doc please also edit its AsciiDoctor counterpart.

CommonMark is also supported in docstrings, have a look at cljdoc-exerciser namespace on cljdoc.org for some more examples.

Formatting marks

I have a strong feeling that I might be headstrong.

If I use italics does that make things more gleanable?

Does this ~~strike~~ you as a ~~cross~~word?

My code was encodeded.

Code blocks

Here we have some clojure code:

;; some sweet clojure code

(defn hello-earthling
  "Greet an earthling in a believable way."
  [name]
  (println "Hello earthling " (uppercase name)))

If we specify Clojure-Repl to CommonMark as our language, we can invoke special highlighting for a repl session:

user=> (require '[clojure.string :as string])
nil
user=> (string/reverse "step on no pets")
"step on no pets"
user=> (reduce + 0 [1 2 3 4 5 6 7 8 6])
42
user=>

Lists

Bulleted:

• apples
• orange
  • temple
  • navel
• bananas

Numbered:

1. first
   1. a
   2. b
      1. x
      2. y
2. second
3. third

Mixed:

• Hey
  1. one
  2. two
• Ho
  • Ho
    1. uno
    2. dos

With code:

1. one

   1. two

      I am a code block
      

   2. three

Quoted text

Quoted text.

Another paragraph in quote.

Images

This local image should work on github and cljdoc.

The same image can be referenced relative to this document:

Here's a remote image:

Links

Local link: cljdoc asciidoc features

Local link root relative: cljdoc markdown features

SCM link: scm link

SCM link root relative: scm link

External link: GitHub Flavored Markdown Spec

Link to anchor: Anchored heading

Note: WikiLinks to api functions [[do not work here]], they only work in docstrings. To illustrate: [[cljdoc-exerciser.ns2/whatever]]

Let's try referencing our APIs via fully qualified links:

1. A link to cljdoc-exerciser.core/excercise3
2. A link to cljdoc-exerciser.core

Headings

Level 3

Level 4

Level 5

Level 6

Horizontal rule

This is how a horizontal rule is rendered:

---

Tables

CommonMark tables are considered an extension to the CommonMark format.

Here is the most basic example:

Heading 1	Heading 2
col1, row1	col2, row1
col1, row2	col2, row2
col1, row3	col2, row3
col1, row4	col2, row4

Basic alignment support is also available:

Right aligned col	Centered col	Left aligned Col
am	is	any
I	this	thing
right?	centered?	left?

Cljdoc tries to match GitHub in syntaxes supported for tables. For example, cljdoc does not support tables without headers:

|---|---| | col1 | col2|

Nor tables with multi-line headers:

| col11 | col12| | col21 | col22| |---|---| | data1 | data2|

Nor tables with captions:

col1	col2
data1	data2

[Caption]

Emojis

GitHub flavored markdown supports emojis.

:space_invader: :apple: :space_invader: :tangerine: :space_invader:

Anchored heading

And here we are.

Admonitions

CommonMark does not support admonitions

Text Roles

There is no support for in CommonMark for coloring or custom styling of text.

Drawings

There is no support in CommonMark for drawings.

Embedded html

GitHub markdown renders some embedded html.

Let's try a definition list:

Term 1

The definition of term one

Happiness

This is the definition of happiness

And some keyboard inputs: q w e r t y

What can't you do in embedded HTML?

Is there any limits to what HTML you can use? It does not seem like it. Seems to me like you can reference existing CSS classes and also specify inline styles. I can't imagine that GitHub allows such freedom though and neither does cljdoc.

1

2

3

Cljdoc yanks JavaScript, for example:

Original content, JavaScript inactive.

Here we tell JavaScript to popup an alert, cljdoc does not allow this: