Editing

Every file should start with a metadata block that looks like this:

The first lines indicate the title, author, and creation date. The last two lines are necessary boilerplate metadata attributes.

To get a line break without a paragraph change, append + to the end of the line:

force
line break

If you have many lines in a row that will need breaks you can prefix them with [%hardbreaks]:

first line
second line

There are a number of ways to handle escaping in Asciidoc but one of the most helpful is to omit all formatting by using:

*ns*

Create an anchor in a page:

Link to another internal page (note the trailing # after the page - this is required in our generator!):

Resources

There is a bug in the parser used in the current version of JBake for links to a page in a parent directory. For example, to link to a page at ../reference/java_interop.adoc, you can use a link like this:

This goes to a (fictitious) subdirectory xref, then back a directory, and then finally the path you wish to follow. While the choice of "xref" here is arbitrary, please use only this string so that we can more easily find and update these upward cross references later when there is a version that fixes this issue.

Link to an anchor in an internal page:

Books

Link to an external page:

defn

Images should be placed in the assets/images/content directory in a subdirectory corresponding to the page location.

Reference the image in a page as follows:

You can insert a Clojure formatted code block as follows:

There are a lot of options for creating lists. Only the most common ones are shown here:

Bulleted lists:

Ordered lists:

Mixed lists:

Use the line break advice from the text formatting section to create lists with multi-line items.

Tables are another large Asciidoc topic with extensive formatting options. This is a basic table example however:

Horizontal rule:

Insert table of contents, which should generally be done at the top of your file (the page template will position this appropriately):

Asciidoc is an extensive language and there is likely some way to do anything you want to do. Below are some more Asciidoc resources to answer more advanced questions.