Liking cljdoc? Tell your friends :D

cljdoc AsciiDoctor features

Introduction

A test AsciiDoctor doc to exercise cljdoc formatting and features.

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

AsciiDoctor offers a very rich set of formatting options, see the AsciiDoctor User Manual for all the details.

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 crossword?

My code was encodeded.

I am super excited about this subroutine.

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 asciidoctor 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=>

Asciidoctor also supports callouts and titles:

code-block-title
;; some sweet clojure code

(defn hello-earthling
  "Greet an earthling in a believable way."  (1)
  [name]
  (println "Hello earthling " (uppercase name))) (2)
1a docstring comes before the arguments
2check with an earthling if uppercasing is soothing

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.

«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»

How about captions, do we display those nicely?

Test image caption

«A local test image should appear here»

Links

Local link: cljdoc markdown features

Local link root relative: cljdoc markdown features

SCM link: scm link

SCM link root relative: scm link

External link: AsciiDoc vs Markdown

Link to anchor: Anchored heading

Wikilinks are only for CommonMark in docstrings.

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

Asciidoc tables are quite full featured.

Here is the most basic example:

Heading 1Heading 2

col1, row1

col2, row1

col1, row2

col2, row2

col1, row3

col2, row3

col1, row4

col2, row4

Sophisticated alignment support is also available, here is a basic example:

Right aligned colCentered colLeft aligned Col

am

is

any

I

this

thing

right?

centered?

left?

Here’s the same table with a title

Table 1. This time with a title
Heading 1Heading 2

col1, row1

col2, row1

col1, row2

col2, row2

And here’s a nested table example from asciidoctor user manual:

Col 1Col 2

Cell 1.1

Cell 1.2

Cell 2.1

Cell 2.2

Col1Col2

C11

C12

Here’s a table with custom sizing:

10% width40% width20% widthremaining

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

An autowidth table will only be as wide as it needs to be.[1]

Name of Column 1Name of Column 2Name of Column 3

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 3, row 2

Emojis

Asciidoctor does not support codes like GitHub flavored markdown does, but it does have support for icons when font-awesome is enabled.

Anchored heading

And here we are.

Admonitions

From most serious to least:

Important things are said here.
Warning to the wise.
Aren’t you a caution?
Note that this note is a note.
Tip the scales with a tip.

And how do admonitions look with some code in them?

This admonition has some code in it.

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

This admonition has some code in it.

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

This admonition has some code in it.

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

This admonition has some code in it.

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

This admonition has some code in it.

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

Text Roles

size

Text can be Big or small.

lines

We can add underline, overline and line-through.

foreground color

We have a choice of 16 foreground colors: aqua black blue fuschia gray green lime maroon navy olive purple red silver teal white yellow.

background color

The same 16 colors are available as background colors: aqua black blue fuschia gray green lime maroon navy olive purple red silver teal white yellow

combinations

Roles can be combined, some examples: white on black-background red on yellow background big blue line-through maroon-background

Math

AsciiDoc STEM supports mathematical equations via MathJax.

To enable stem support for your doc add in the :stem: document attribute. This is where you can provide your default syntax for example:

:stem: latexmath

Specifying nothing sets the default for stem blocks to asciimath. But, you can always be specific. Instead of specifying stem for your formulas, you can explicitly specify asciimath or latexmath instead. To each is own, but I think I’d be specific.

Here is a Latex example:

\[ f(n) = \begin{cases} n/2 & \quad \text{if } n \text{ is even}\\ -(n+1)/2 & \quad \text{if } n \text{ is odd} \end{cases} \]

And one for AsciiMath:

\$sum_(i=1)^n i^3=((n(n+1))/2)^2\$

And AsciiMath again using stem instead of being specific:

\$sum_(i=1)^n i^3=((n(n+1))/2)^2\$

Here’s an example \(\forall x \in X, \quad \exists y \leq \epsilon\) of an inlined expression.

Drawings

Do we support svgbob? Not yet but if we someday decide to, this sample from the svgbob demo site won’t look like ASCII art.

              .─.
             ( 0 )
              `-'
            /     \
           /       \
          V         V
         .─.         .─.
        ( 1 )       ( 4 )
         `-'         `-' .
       /   \         |  \ `.
      /     \        |   \  `.
     V       V       |    \   `.
    .─.      .─.     V     V    V
   ( 2 )    ( 3 )    .─.   .─.   .─.
    `─'      `─'    ( 5 ) ( 6 ) ( 7 )
                     `─'   `─'   `─'

Embedded html

Although it is discouraged, AsciiDoctor does support passthroughs.

AsciiDoctor renders passed through embedded html.

1. file,grabbed from asciidoctor user manual
❮Document testsCommonMark features❯

Can you improve this documentation?Edit on GitHub

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

Keyboard shortcutsReport a problemcljdoc on GitHub
× close