Introduction to .adoc

Dear readers,

today’s topic will be about setting up of .adoc file extension (Asciidoctor) and how to use it. .adoc documents are like your Microsoft Word document for you to write stuff like reports, guides, etc. Unlike your normal writing in Microsoft Word document, Asciidoctor is a little bit closer to writing your document in HTML. It has its own syntax. It is similar to MarkDown but much more powerful. After your finished writing content in your Asciidoctor file, you can convert them into PDF or HTML.

Setup

List of files to download:

  1. pycharm IDE
  2. Asciidoctor plugin

To write in Asciidoctor easily, firstly, down pycharm here. You can download the community edition if you do not want to pay for the professional edition. After downloading, install it.

Next, download the Asciidoctor plugin here. Do not unzip the ZIP file after downloading it. Run pycharm and choose “Open File or  Project”. Select the folder where you want to store your Asciidoctor document. In pycharm main window, press hotkey CTRL+ALT+S to open the settings window (see Figure 1a).

adoc

Figure 1a: Settings window in pycharm

In the settings window, navigate to Plugins > Install Plugin from Disk… (can be found in the gear icon). You should see a Choose Plugin File window appear (see Figure 1b). Click on the asciidoctor ZIP file you have downloaded previously.

adoc1

Figure 1b: Choose Plugin File window to choose the download asciidoctor ZIP file

Once you have selected the right ZIP file, your Settings window should appear on the AsciiDoc plugin page. Click on the button “Restart IDE” (see Figure 1c).

adoc2

Figure 1c: Restart IDE after successful adding of AsciiDoc ZIP file

After restarting pycharm, you have finished setting up your environment for AsciiDoctor documents.

Create .adoc File

To create a .adoc file, right-click on the folder you want to create your document in and navigate to New > File (see Figure 2a).

adoc3

Figure 2a: Create a new .adoc file

A small window should pop up. Input a file name you want and remember to end the name with the “.adoc” file extension (see Figure 2b).

adoc4

Figure 2b: Set a name for the new .adoc file

You should see two windows appear (see Figure 2c). The left window is for you to write your code while the right window will be the output appearance.

adoc5

Figure 2c: AsciiDoctor editor

As you start to write on .adoc, if the syntax is correct, a preview of the output of the document will appear on the right window (see Figure 2d).

ss

Figure 2d: Example of correct syntax with preview document

Writing in .adoc file

In this section, I will only be covering the basics of writing in .adoc file. This should help you to quickly get started with some of the basics and useful tips. For the full documentation of the usage of .adoc file, refer to this documentation from their official website.

Let’s take a look at a short PDF document I have created from Asciidoctor:

pdf

Figure 3a: Example of PDF document created from .adoc (part 1)

pdf1

Figure 3b: Example of PDF document created from .adoc (part 2)

pdf2

Figure 3c: Example of PDF document created from .adoc (part 3)

List of examples:

  1. Title
  2. Table of content
  3. Headings
  4. Plain text + new paragraph
  5. Bold text
  6. Italic text
  7. Emphasis text
  8. Ordered list
  9. Unordered list
  10. Continue ordered list numbering
  11. Append text
  12. Literal block
  13. Highlight source code
  14. Jump to local file section/anchor
  15. Hyperlink
  16. Table
  17. Image
  18. Center text in paragraph

Title

To create a title you have to use a single equal, =, symbol and follow have the sentence for the title. The title’s size will automatically be set and places the title in the middle of the document.

Usage:

= <Your title>

Example:

= Writeup on .adoc

Click here for documentation of the title for more usage.

Table of content

To include a table of content, you have to include :toc: into your .adoc document in a new line.

Example:

= Writeup on .adoc
:toc:

Click here for documentation of the table of content for more usage.

Headings

Similar to creating the title, equal, =, symbol is used to indicate the text/sentence after it is headings. For 2 equal symbols, it is equivalent to Heading One in Microsoft Word document. For 3 equal symbols, it is equivalent to Heading Two, and so on. The more the number of equal symbols, the smaller the heading is. As you create headings, the table of content will automatically be updated with indentations for different headings.

Usage:

== <Sentence/title of heading one>
=== <Sentence/title of heading two>

Example:

== 1.1. Section one
=== 1.1.1. Sub-section one

Click here for documentation of the headings for more usage.

Plain text + new paragraph

For plain text, it is similar to a Microsoft Word document. All you have to do to write a paragraph is to type it in a new line in .adoc. To start a new paragraph in the output document, you have to type after one new line in .adoc.

Example:

NewParagraphExample

Figure 3d: Example of a new paragraph

In Figure 3d, “This is a normal text.” is a paragraph that can be created when writing it in a new line (write inline 5 instead of line 4). To write in a new paragraph, the new paragraph should be written in the 2nd new line (line 7 instead of line 6).

 

Bold text

To bold a word/sentence, including asterisks, *, on both ends of the word/sentence.

Example:

*Text*
*Bold text.*

Result:

Text
Bold text.

To bold a letter or a few characters inside a word, you have to include two asterisks, *, on both ends the letter or characters.

Example:

Bold in the **m**iddle

Result:

Bold in the middle

Click here for documentation of the bold text for more usage.

Italic text

To create italic text, including underscore, _, on both ends of the word/sentence.

Example:

_Text_
_Italic text._

Result:

Text
Italic text.

To create a letter or a few characters inside a word that is in italic format, you have to include two underscores, _, on both ends the letter or characters.

Example:

Italic letter in the __m__iddle

Result:

Italic letter in the middle

Click here for documentation of the italic text for more usage.

Emphasis text

To emphasis, a word/sentence, include grave accent, `, on both ends of the word/sentence.

Example:

`Text`
`Bold text.`

Result:

Text
Bold text.

To emphasis a letter or a few characters inside a word, you have to include two grave accents, `, on both ends the letter or characters.

Example:

Bold in the ``m``iddle

Result:

Bold in the middle

Click here for documentation of the emphasis text for more usage.

Ordered list

To create an ordered list, you have to include a dot, ., followed by one space before you write your sentence.

Usage:

. <Your sentence>

Example:

. Sentence 1
. Sentence 2
. Sentence 3

Result:

1. Sentence 1
2. Sentence 2
3. Sentence 3

Click here for documentation of the creation of an ordered list for more usage.

 

Unordered list

To create an unordered list, you have to include an asterisk, *, followed by one space before you write your sentence.

Usage:

* <Your sentence>

Example:

* Sentence 1
* Sentence 2
* Sentence 3

Result:

• Sentence 1
• Sentence 2
• Sentence 3

To include an unordered list as a sub-list of an ordered list, include an indentation before adding an unordered list.

Usage:

. <Your sentence>
     * <Your sub-sentence>

Example:

. Sentence 1
     * Sub-sentence

Result:

1. Sentence 1
     ○ Sub-sentence

Click here for documentation of the creation of an unordered list for more usage.

Continue ordered list numbering

During the use of the order list, you might be interested to add an image or a paragraph between ordered list items. However, this results in the numbering system of the ordered list to restart. To continue, you have to use [start=].

Example:

. Sentence 1
. Sentence 2

This is an inserted sentence.

[start=3]
. Sentence 3

Result:

1. Sentence 1
2. Sentence 2

This is an inserted sentence.

3. Sentence 3

Append text

As we have already talked about starting a new sentence in this section, we have not talked about writing in a new line. To do so, simply add a plus, +, symbol after then sentence like concatenation in programming.

Usage:

<Your heading> +
<Your content>

Example:

*Introduction:* +
This is an introduction.

Result:

Introduction:
This is an introduction.

Click here for documentation of the appending of text for more usage.

Literal block

To create a literal block which is like this grey box with text in it:

This block

Include an indentation before writing a sentence.

Highlight source code

There are cases where you would like to place your source code in a literal block but with certain keywords being highlighted just like in IDE, you can do that in .adoc following the example below.

Usage:

[source,]
----
<Source code>
----

Example:

[source,python]
----
import os

os.system("mkdir Test")
----

Result:

sourceHighlight

Figure 3e: Example of source code highlight

Click here for documentation of the highlight of the source code for more usage.

Jump to local file section/anchor

There are situations where you would like the user to click on certain words or sentences that will bring them to another location in the same file/webpage. Before you link to the location, jumping to that section can only occur via headings or a self-created anchor.

For the creation of anchor,

[#<name/id for your anchor>]

Example:

[#jumpSection]
Hello everyone!

Now, let’s show an example of linking a sentence to an anchor and another sentence to a heading.

Example:

== 1. Introduction
This is an introduction paragraph.

[#jumpSection]
Hello everyone!

Click <<1. Introduction,here>> to jump to introduction.
Click <<jumpSection,here>> to jump to welcome text.

Result:

1. Introduction
This is an introduction paragraph.

Hello everyone!

Click here to jump to introduction.
Click here to jump to welcome text.

Click here for documentation of the creation of anchor for more usage.

Hyperlink

A hyperlink allows users to click on certain words or sentences, bringing them to a website of your choice. Click on a link will not open a new tab, but on the same page if it is open in the browser. Therefore, users will have to right-click and select open in a new tab.

Usage:

Hello! Click [here].

Example:

Hello! Click https://lamecarrot.wordpress.com/tech-related/[here].

Result:

Hello! Click here.

Click here for documentation of hyperlink for more usage.

Table

The creation of a table is fairly simple. All you have to do is to include |== at the start and end of your table as shown below:
|===
<Your table's content>
|===

To create a new column, all you have to do is to separate each content with | and spacing between | and your content as shown below:

|===
| <Content 1> | <Content 2>
|===

To create a new row, simply start it in a new line. Remember your number of columns must be the same for all rows. That cell of the table is empty, leave it an extra spacing between |.

|===
| <Content 1> | <Content 2>
| <Content 1.1> | <Content 2.1>
|===

Example:

|===
| *Heading 1* | *Heading 2*
| Content 1 | Content 2
|   | Content 2.1
|===

Result:

adoc6

To position your content in the cell, use ^ to center the content, > to align it to the right. By default, all content will be aligned to the left. Include them right before the | column separator.

Example:

|===
^| *Heading 1* ^| *Heading 2*
| Content 1 >| Content 2
|   | Content 2.1
|===

Result:

adoc7

To change the size of the columns, you can specify the percentage of each column at the top of the table. Note that the total percentage must add up to 100%.

Example:

[cols="30%, 70%"]
|===
^| *Keywords* ^| *Description*
^| Command Prompt / Console / Shell | Command-line interface.
|===

Result:

adoc8

Click here for the documentation of the table for more usage.

Image

Before including an image, I prefer to create a new folder inside the folder where I created my Asciidoctor file to store all the images. As the number of images used for the document may increase, the number of photos will increase. Therefore, this may get messy. You can create more nested folders if you want to ensure tidiness as long as you specify the right directory to the image.

Usage:

image::<Location of image>[<Alt text>, align""]

Example:

image::Image/Capture.PNG[Alt text, align="center"]

Result:

Capture

Click here for the documentation of the image for more usage.

Center text in paragraph

To align a paragraph, simply include [.text-] on top of the paragraph. For the alignment, it can be left, center, or right. By default, all paragraphs will be aligned to the left.

Example:

[.text-center]
Hello

Result:

                                   Hello

Click here for the documentation of the alignment of paragraphs for more usage.

Source Code

Below contains the source code that is used for Figure 3a to 3c:

= Writeup on .adoc
:toc:

== 1. Text modification
This is a normal text.

*Bold text*

Bold in the **m**iddle

_Italic text_

Key `highlight` of the text.

. List item number one
. List item number two
    * Sub list
    * Another sub list

A random text or image here.

[start=3]
. Continue list

Continue text in new link +
without spacing.

=== 1.1. Section 1
Source code:

    This is a source code
        Indented source code

To specify specific programming language source code:
[source,python]
----
import os

os.system("mkdir HelloFolder")
----

=== 1.2. Section 2
Link to the <<imageAnchor,image>>.

Hyperlink to a https://lamecarrot.wordpress.com/tech-related/[website].

<<<

== 2. Table
[cols="30%, 70%"]
|===
^| *Keywords* ^| *Description*
^| Command Prompt / Console / Shell | Command-line interface.
|===

== 3. Image
[#imageAnchor]
image::Image/Capture.PNG[Alt text, align="center"]
[.text-center]
Figure 3a: A mini picture

I hope this basic guide will help you get started with Asciidoctor and enjoy using it. Do give any feedback you have on the comment section below. Thank you!

You may also send me some tips if you like my work and want to see more of such content. Funds will mostly be used for my boba milk tea addiction. The link is here. 🙂

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.