Writing AsciiDoc

How does authoring with AsciiDoc work, for beginners

The AsciiDoc/Asciidoctor approach Metanorma suggests for authoring standards is not WYSIWYG—meaning that you’ll be dealing with a plain-text editor and a command line, rather than something that resembles, say, a Microsoft Word document.

The text you’ll be authoring would look more like HTML or Markdown, and it will be formatted like the end document during build stage.

This might look confusing at first, but the upside, in our opinion, far outweighs that: with documents formatted using semantic markup like Asciidoctor it is much easier to automate key validation and formatting processes such as checking for missing document components, automatic numbering, and generating output in multiple formats from one source text.

Read more about Metanorma’s approach for why we chose AsciiDoc.

If you are new to AsciiDoc (and maybe if you aren’t), you might want to use the Asciidoctor manual alongside this guidance.

Some editors that have been reported to work well for writing Metanorma documents in AsciiDoc:

Generally, it’s perfecty possible to use any plain-text editor, although you won’t be able to see live preview and for syntax issues you’d have to rely on log output from Metanorma CLI during document generation.