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. According to asciidoctor, images are resolved relative to the document or at the path specified by the imagesdir asciidoctor attribute.

Current value of imagesdir:

../../images

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

External link: AsciiDoc vs Markdown

Link to anchor: Anchored heading

As far as I can figure, Asciidoctor does not support root relative http links - so we need to fully qualify links to our APIs:

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

  2. A link to cljdoc-exerciser.core

If they are not already, these will soon be converted to root relative links by cljdoc to support local testing.

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

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 )
                     `─'   `─'   `─'
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