AsciiDoc authoring for RISC-V contributors

AsciiDoc is the markup language and Asciidoctor is a set of toolchains that support publishing from AsciiDoc.

Asciidoctor toolchains:

  • asciidoctor, which is well-established and written in ruby.

  • antora, which is newer and written in javascript.

  • Python-based, which is legacy and in maintenance mode.

RISC-V AsciiDoc authoring assets

Please view the readme in the docs-spec-template repo for information about the automated build processes.

The docs-spec-template repo contains assets such as fonts, styles, directory structure, and themes needed for RISC-V specifications. It uses an Antora-compatible directory structure with source files in modules/ROOT/pages/. See [antora-structure] for a full description of the layout.

A local build guide takes you through the local install process that supports all of the required features.

Although testing your markup by building a PDF is a good practice, you can catch many common errors by downloading Asciidoctor and building the HTML output using the following command from the repository root:

asciidoctor modules/ROOT/pages/spec-sample.adoc

Or more simply, using the Makefile:

make

Writing

To begin writing in AsciiDoc, select a text editor. Here’s Text editors with AsciiDoc support.

For quick reference, see AsciiDoc Syntax Quick Reference. Most of the markup for the specifications is simple and should have a familiar feel to those who have used Git-flavored Markdown. For RISC-V specifications, it is the procedures for [graphics] that add complexity.

The AsciiDoc Writers Guide contains details about AsciiDoc markup.

Here are a few additional, useful links:

Text editors with AsciiDoc support

There isn’t a true WYSIWYG editor for AsciiDoc. However, there are live preview options that are listed in the Asciidoctor documentation that can help you see what the output looks like. You can also use your favorite text editor, or perhaps switch to one that has good AsciiDoc linting.

The following list contains links to resources for text editors/IDEs support of AsciiDoc: