Liking cljdoc? Tell your friends :D

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.

«A local test image should appear here»

The same image can be referenced relative to this document:

«A local test image should appear here»

Here's a remote image:

«A remote test image should appear here»

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 1Heading 2
col1, row1col2, row1
col1, row2col2, row2
col1, row3col2, row3
col1, row4col2, row4

Basic alignment support is also available:

Right aligned colCentered colLeft aligned Col
amisany
Ithisthing
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:

col1col2
data1data2

[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:

important

Important things are said here.

warning

Warning to the wise.

caution

Aren't you a caution?

note

Note that this note is a note.

tip

Tip the scales with a tip.

And how do alerts look with some code in them?

important

This alert has some code in it.

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

warning

This alert has some code in it.

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

caution

This alert has some code in it.

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

note

This alert has some code in it.

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

tip

This alert has some code in it.

(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:

tip

para1line1

tip

para1line1 para1line2

Content in subsequent paragraph

tip

para1line1

tip

para1line1 para1line2

Content in subsequent paragraphs

tip

para1line1 para1line2

para2line1 para2line2

Content in first and subsequent paragraphs:

tip

para1line1 para1line2

para2line1

para3line1 para3line2

Spaces and empty:

tip

para3line1 para3line2

Too many spaces before alert type means not an alert:

[!TIP]

Not an alert

Nested alerts are not a thing:

tip

A tip

[!NOTE] not a nested alert

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.

123

Cljdoc yanks JavaScript, for example:

Original content, JavaScript inactive.

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

Can you improve this documentation? These fine people already did:
lread & Lee Read
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close