Learning the AsciiDoc syntax

The AsciiDoc Language reference documentation is the go-to-guide for writing AsciiDoc content. Learn about the AsciiDoc syntax in small training exercises.

This is part of the step-by-step series to set up a technical writing environment with IntelliJ and the AsciiDoc plugin. See the page Setup for technical writing for an overview of all steps.

Prerequisites

This assumes that IntelliJ IDEA is open with a project with some existing content. See Opening a project in IntelliJ IDEA and Editing an AsciiDoc file in IntelliJ on how to do this.

Learning the AsciiDoc syntax with Kata

A kata is an exercise that focuses on learning something new.

The primary goals of this exercise are:

  1. Train the AsciiDoc syntax in several key areas.

  2. Learn how to use the AsciiDoc reference documentation.

To start the kata, check out the GitHub project https://github.com/ahus1/asciidoc-kata:

  1. Open the menu File  New  Project from Version Control.

    intellij clone kata repo

  2. As version control, choose Git.

  3. As URL, enter https://github.com/ahus1/asciidoc-kata.

  4. As Directory, enter an empty local folder.

  5. Choose the button Clone.

The repository contains several files with kata, with the first one named 01_formatting.adoc. Open the file, and it should show in the editor as seen below:

intellij first kata

The block between the ==== markings on the left contains the instructions. The same texts shows with a yellow background on the right in the preview. It contains links to the AsciiDoc language documentation which contain information to find a solution for the exercise. Click on the blue links in the preview to open them in the system browser.

At the end, indicated with tree dots (...), start typing the solution. Use the preview on the right to verify that the AsciiDoc content entered on the left renders the expected results.

After this first exercise, pick other exercises which are relevant to your day-to-day projects.

Variants of the exercise

Instead of practicing the AsciiDoc syntax alone, learners can team up with a second person to solve these exercises.

There’s also a collaborative web editor that has been designed for such a training. See this blog post for details on how to run such a training event.

Further reading

Continue to Using tables with AsciiDoc in IntelliJ for the next step of this series.