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.

A line break
can be useful.

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

Description list:

Clojure

Clojure for the JVM

ClojureScript

Clojure for JavaScript compiled by the JVM

Plank

Clojure for JavaScript compiled by JavaScript

Babashka

Clojure for the command line

Description list (horizontal):

Clojure

Clojure for the JVM

ClojureScript

Clojure for JavaScript compiled by the JVM

Plank

Clojure for JavaScript compiled by JavaScript

Babashka::bb

Clojure for the command line

Description list (Q&A):

  1. Why?

    Because

  2. How?

    Dunno

Quoted text

Quoted text.

Another paragraph in quote.

In Asciidoctor, quotes can also include the author and citation:

I never said most of the things I said.

— Yogi Berra
life

CommonMark syntax

Another paragraph in quote.

nested quote

back to non-nested

And yet another syntax:

I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11

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?

«A local test image should appear here»
Test image caption

And here’s an inline «A remote test image should appear here» image.

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.

Note that GitHub does support their own emojis in adoc files as a post-processing feature:

bear :bear: smirk :smirk: grin :grin:

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

In the days of yore, Asciidoctor supported various text roles. Today, the Asciidoctor team recommends you setup what makes sense for your docs in your CSS. For now, we do not support these legacy roles for cljdoc.

The following subsections demonstrate that we do not support these roles. Well, except for underline.

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.

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

Like GitHub, cljdoc sanitizes HTML, removing any JavaScript. For example:

Original content, JavaScript inactive.

Here we tell JavaScript to popup and alert, something that cljdoc will not allow:

Keyboard keys

Asciidoctor supports the keyboard macro which is a handy way to show what keys to press.

q w e r t y

On macOS press ⌘+⌥+space to bring up Finder search.

Menu selections

Select View  Zoom  Reset to reset the zoom level to the default setting.

UI buttons

Press the OK button when you are finished.

Index terms

Asciidoctor supports defining index terms but does not yet support generating an index catalog via its html converter. So we don’t either.

This example term1-should-show contains some index terms just to make sure we don’t barf on them.

Example Block

An example block can be used to illustrate some syntax or usage.

Example 1. I am a sample

Do I look like a subdoc?

Some syntax here

Blah blah

An example can also be collapsible

I am a sample

Do I look like a subdoc?

Some syntax here

Blah blah

Verse

     I am not
    adverse
   to
  testing
 verse

 or
   am
      I?
— Lee
Testing Verse

Side bars

Side bars are for content outside the normal flow of your document.

How much chuck?

How much wood could a woodchuck chuck If a woodchuck could chuck wood? As much wood as a woodchuck could chuck, If a woodchuck could chuck wood.

Open blocks

Not sure why adoc has these, but they can exist. They are blocks that masquerade as other blocks. I think they are here for extensibility?

I am abstract.

What am I?

Video

Asciidoctor explicitly supports videos with a variety of options, something that cljdoc does not currently support.

Here’s a youtube video with default options:

Simplicity Matters by Rich Hickey

And here’s one from vimeo:

Introduction to Clojure by Stuart Halloway

And one from the archive.org:

Big Buck Bunny
Your browser does not support the video tag.

Audio

Asciidoctor also allows audio play, cljdoc does not currently support this.

Your browser does not support the audio tag.

Things we ignore

Page breaks <<<

Discrete Heading

If you want the visual affect of a heading without the semantics.

This header is not part of the hierarchy and will not be part of toc

Ditto for this header

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

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

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

Keyboard shortcutsReport a problemcljdoc on GitHub
× close