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.
List of files to download:
- pycharm IDE
- 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).
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.
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).
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).
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).
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.
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).
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:
Figure 3a: Example of PDF document created from .adoc (part 1)
Figure 3b: Example of PDF document created from .adoc (part 2)
Figure 3c: Example of PDF document created from .adoc (part 3)
List of examples:
- Table of content
- Plain text + new paragraph
- Bold text
- Italic text
- Emphasis text
- Ordered list
- Unordered list
- Continue ordered list numbering
- Append text
- Literal block
- Highlight source code
- Jump to local file section/anchor
- Center text in paragraph
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.
= <Your title>
= 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.
= Writeup on .adoc :toc:
Click here for documentation of the table of content for more usage.
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.
== <Sentence/title of heading one> === <Sentence/title of heading two>
== 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.
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).
To bold a word/sentence, including asterisks, *, on both ends of the word/sentence.
*Text* *Bold text.*
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.
Bold in the **m**iddle
Bold in the middle
Click here for documentation of the bold text for more usage.
To create italic text, including underscore, _, on both ends of the word/sentence.
_Text_ _Italic text._
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.
Italic letter in the __m__iddle
Italic letter in the middle
Click here for documentation of the italic text for more usage.
To emphasis, a word/sentence, include grave accent, `, on both ends of the word/sentence.
`Text` `Bold text.`
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.
Bold in the ``m``iddle
Bold in the middle
Click here for documentation of the emphasis text for more usage.
To create an ordered list, you have to include a dot, ., followed by one space before you write your sentence.
. <Your sentence>
. Sentence 1 . Sentence 2 . Sentence 3
1. Sentence 1 2. Sentence 2 3. Sentence 3
Click here for documentation of the creation of an ordered list for more usage.
To create an unordered list, you have to include an asterisk, *, followed by one space before you write your sentence.
* <Your sentence>
* Sentence 1 * Sentence 2 * Sentence 3
• 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.
. <Your sentence> * <Your sub-sentence>
. Sentence 1 * Sub-sentence
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=].
. Sentence 1 . Sentence 2 This is an inserted sentence. [start=3] . Sentence 3
1. Sentence 1 2. Sentence 2 This is an inserted sentence. 3. Sentence 3
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.
<Your heading> + <Your content>
*Introduction:* + This is an introduction.
Introduction: This is an introduction.
Click here for documentation of the appending of text for more usage.
To create a literal block which is like this grey box with text in it:
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.
[source,] ---- <Source code> ----
[source,python] ---- import os os.system("mkdir Test") ----
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>]
[#jumpSection] Hello everyone!
Now, let’s show an example of linking a sentence to an anchor and another sentence to a heading.
== 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.
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.
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.
Hello! Click [here].
Hello! Click https://lamecarrot.wordpress.com/tech-related/[here].
Hello! Click here.
Click here for documentation of hyperlink for more usage.
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> |===
|=== | *Heading 1* | *Heading 2* | Content 1 | Content 2 | | Content 2.1 |===
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.
|=== ^| *Heading 1* ^| *Heading 2* | Content 1 >| Content 2 | | Content 2.1 |===
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%.
[cols="30%, 70%"] |=== ^| *Keywords* ^| *Description* ^| Command Prompt / Console / Shell | Command-line interface. |===
Click here for the documentation of the table for more usage.
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.
image::<Location of image>[<Alt text>, align""]
image::Image/Capture.PNG[Alt text, align="center"]
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.
Click here for the documentation of the alignment of paragraphs for more usage.
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. 🙂