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.

Multiline paragraphs:

Para1line1 Para1line2

Para2line1 Para2line2

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:

Basic alignment support is also available:

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:

[Caption]

Emojis

GitHub flavored markdown supports emojis.

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

Anchored heading

And here we are.

Alerts

GitHub Markdown has an alert extension which is conceptually equivalent to AsciiDoc admonitions.

From most serious to least:

And how do alerts look with some code in them?

(how
  (does
    (this "look?)))

(how
  (does
    (this "look?)))

(how
  (does
    (this "look?)))

(how
  (does
    (this "look?)))

(how
  (does
    (this "look?)))

Since we wrote a flexmark extension to handle GitHub alerts, let's test out some scenarios.

These should render as a quotes because they have no content:

One line:

[!TIP]

Two line:

[!TIP]

Multi-line:

[!TIP]

These should render as alerts:

Content in first paragraph:

Content in subsequent paragraph

Content in subsequent paragraphs

Content in first and subsequent paragraphs:

Spaces and empty:

Too many spaces before alert type means not an alert:

[!TIP]

Not an alert

Nested alerts are not a thing:

Looks like alerts in lists are not a thing either:

1. list item 1

   [!TIP] A tip

   Normal, non-alert text.

2. list item 2

   A normal quote in a list

   Normal, unquoted text.

3. list item 3

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.

Cljdoc yanks JavaScript, for example:

Original content, JavaScript inactive.

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