Skip to content

Latest commit

 

History

History
139 lines (86 loc) · 4.61 KB

a_few_basics.adoc

File metadata and controls

139 lines (86 loc) · 4.61 KB
Raw

A few basics

Asciidoc is fully documented, and its documentation is actively maintained. This document contains some information on asciidoc markup to get you started.

For details and additional options:

In addition, you have the option of asking questions in the asciidoctor discussion list:

As is true of any complex process, asciidoc/asciidoctor has some quirks. Please be certain to make use of these templates because they provide you with files that will result in fully featured pdf output.

Best practice is to test the pdf build frequently to ensure that you have not accidentally introduced something that breaks the build.

Warning
 PDFs require the use of Ruby 2.7.2.

Headers

In asciidoc you cannot jump directly from a Head 1 to a Head 3 or 4. Your headers must appear in numerical sequence from Head 1 to Head 2, and onward. If you skip over a header in the sequence, asciidoctor throws an error.

= Title head (book or report title)

[colophon]
= Colophon head (in frontmatter, used for preface)

[[chapter_title]]
== Head 1 (chapter)

=== Head 2 (section)

==== Head 3 (subsection)

===== Head 4 (sub-subsection)

[appendix]
== Appendix title

[index]
Index
Note
 Settings in the header file trigger auto-generation of Appendix prefixes and of the Index (among other things).

Code Blocks

Asciidoc/asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example:

[source,python]
....
mono-spaced code block
add a1,a2,a3; # do an ADD
....

renders as follows:

mono-spaced code block
add a1,a2,a3; # do an ADD

Hyperlinks and cross references

Asciidoctor recognizes hyperlinks to Web pages and shortens them for readability. Cross references (links within a document) are supported by macros.

Stem content

The :stem: latexmath setting works for HTML output from asciidoc, however, it doesn’t yet work for asciidoctor-pdf output.

As a workaround, you will need to create image files rendered equations and import the images for pdfs.

[stem]
++++
sqrt(4) = 2
++++
\$sqrt(4) = 2\$

It looks like there is not much need for actual equations in the specifications. Rather, there is a set of specific unicode characters that are used:

Asciidoctor PDF currently only supports decimal character references. See asciidoctor/asciidoctor-pdf#486

Hexadecimal unicode looks like it has problems in the pdf. This is gnarley.

Asciidoctor Mathematical

Asciidoctor Mathematical is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros. After the document has been parsed, the extension locates each asciimath, latexmath, and stem block and inline macro, converts the expression to an image, and replaces the expression with an image. It uses Mathematical to render the LaTeX notation as an image. If the expression is AsciiMath, it first uses AsciiMath gem to convert to LaTeX. Conversion then proceeds as normal.

Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the installation section in the Asciidoctor Mathematical README to learn how to install it.

Once Asciidoctor Mathematical is installed, you can enable it when invoking Asciidoctor PDF using the -r flag:

$ asciidoctor-pdf -r asciidoctor-mathematical sample.adoc

To get started, first create a Gemfile in the root of your project. In that file, declare the gem source, the asciidoctor-pdf gem, and the prawn-table gem (plus any other development gems you want to use).

Gemfile

gem 'asciidoctor-pdf'
gem 'prawn-table', github: 'prawnpdf/prawn-table'

You can then install the gems into your project using the bundle command:

$ bundle config set --local path .bundle/gems && bundle

Since you’re using Bundler to manage the gems, you’ll need to prefix all commands with bundle exec. For example:

$ bundle exec asciidoctor-pdf -v

Thus, to any command present in the following sections, be sure to include this prefix.