AsciiDoc

Overview

ASCII Doc is an open-source markup language to write technical content and has various features including converting content into PDF, HTML, EPUB, and also content reuse. ASCII Doc can be managed through the version control system making it suitable for Doc as Code environment.

Although, no denying the fact that, the paid authoring tool comes with its own advantages, Asciidoc does most of the work with zero budget and is applicable for small enterprises.

Before you begin:

1. You must have Ruby Gems installed on your machine.

2. You should have an IDE like Visual Studio, Intellij, or PyCharm.

How to write content in Markup?

AsciiDoc content is written in plain text. To format it, you add markup characters for headings, lists, and code blocks

These are common text formatting options available in ASCII Doc.

= Hello, AsciiDoc!  // This is a Heading

This is an interactive editor.  // This is normal style text.


== Section Title //This is a Heading 2

* A list item   //This is a Unordered list
* Another list item

*Bold text*  //This is how to write bold text

_Italic text_  //This is how to write in italics

[,ruby]    // This is a code block
----
puts 'Hello, World!'

How can we Reuse Content?

No more complicated use of XML tags like conref. Simply add the following line and the contents are added during export.

include::reuse.adoc    //reference to the content that is specified elsewhere in your directory.

I have created a root folder called ASCII and added the contents. The reusable contents are in a separate file and it is added in my file .adoc using include::reuse.adoc

How to create conditional content in PDF?

Conditional content allows you to include/exclude certain parts of your document based on conditions.

For example, if we want to create content for a product that has roles defined such as Admin, Manager, or Role Manager.

You can define attributes as:

ifdef::role-admin[]            //beginning of the condition
== Admin Section
Only shown in the Admin version of the PDF.
endif::role-admin[]            //end of the condition

To generate the PDF using the attributes, you run the following command:

asciidoctor-pdf -a role-admin file.adoc

• asciidoctor-pdf: CLI tool to convert the file to PDF format

• -a role-manager: This will convert the file to pdf but based on role-admin attribute.

How to export the contents in pdf format with custom theme?

In the following example, I will demonstrate on how to convert the Ascii content in the PDF format. The process will vary for HTML.

To convert the ASCII contents, you must:

• Create a .yaml file and add configurations.

The yaml file is responsible for customizing the output appearance of the PDF file. It controls various elements including font, headers, footers, and toc.

The yaml file might be overwhelming but trust me, it isn't that complicated. Even if you are stuck, you have LLMs that can do the work and explain how it works.

The following is the example of my .yaml file.

extends: default  # Inherits settings from the default theme

page:
  size: Letter  # Sets the page size to Letter format

header:
  height: 0.75in  # Defines the header height
  line-height: 1  # Sets the line height for header content
  recto:  # Settings for odd-numbered pages (recto)
    left:
      content: image:swagger.png[pdfwidth=10%]  # Displays the logo on the left
    center:
      content: '{document-title}'  # Centers the document title in the header
    right:
      content: '{page-number} of {page-count}'  # Shows the current page and total page count
  verso:  # Settings for even-numbered pages (verso)
    left:
      content: image:swagger.png[width=100]  # Displays the logo on the left for verso pages
    center:
      content: '{document-title}'  # Centers the document title in the header
    right:
      content: '{page-number} of {page-count}'  # Shows the current page and total page count

footer:
  height: 0.75in  # Defines the footer height
  line-height: 1  # Sets the line height for footer content
  recto:  # Footer settings for recto pages (odd-numbered)
    right:
      content: '{chapter-title} | {page-number}'  # Displays the chapter title and page number on the right
  verso:  # Footer settings for verso pages (even-numbered)
    left:
      content: '{page-number} | {chapter-title}'  # Displays the page number and chapter title on the left

# Table of Contents (TOC) settings
toc:
  levels: 3  # Includes up to 3 levels in the TOC
  title: "Table of Contents"  # Sets the TOC title
  font_size: 12  # Defines the font size for TOC entries
  font_color: #000000  # Sets the font color for TOC entries
  font_family: Times-Bold  # Uses Times-Bold for TOC text
  position: before  # Places the TOC before the main content
  page_numbers: true  # Enables page numbers in the TOC
  dot_leader: true  # Adds dot leaders between TOC entries and page numbers

Finally, the output of the file can be generated from your terminal using the following command:

• asciidocter-pdf runs the Asciidoctor pdf processor.

• -a pdf-theme=mytheme.yml specifies the custom pdf theme specified in mytheme.yaml file.

• file.adoc specifies the file to be converted into pdf.

asciidoctor-pdf -a pdf-theme=mytheme.yml file.adoc

"Now then, who’s ready to march into their manager’s office and say, ‘You know that fancy authoring tool we’ve been paying for? Yeah… turns out AsciiDoc does the same thing—for free.’ 😂 Who’s in?"