Writing in AsciiDoc

AsciiDoc is just a text#

You can use AsciiDoc to quickly create professional-looking documents, whether you’re writing a blog post or a book, without needing to learn complex formatting languages.

With AsciiDoc, you can focus on writing your story or report and present it in a visually appealing format, like a stunning website or a well-designed book, without mastering a complicated program.

To start writing in AsciiDoc, simply use a text editor. AsciiDoc takes care of the formatting and layout, allowing you to concentrate entirely on your content.

AsciiDoc’s straightforward and intuitive syntax makes it easy to get started. You can use AsciiDoc to create documents in various formats, including HTML, PDF, and DocBook. Additionally, you can customize the output and include custom macros to suit your needs. Because AsciiDoc documents are plain text, you can easily collaborate with others.

Wrapped Text and Hard Line Breaks in Asciidoc#

You can use AsciiDoc’s wrapped text and hard line breaks features to precisely control your document’s layout. By default, you can rely on AsciiDoc to wrap text automatically, filling the available space and ensuring readability and adaptability across various formats.

This flexibility in text-wrapping is particularly beneficial for paragraphs, as it creates a smooth, natural flow of text. Moreover, you can dictate how text wraps and how lines break, fine-tuning your content to meet specific requirements.

You can use hard line breaks to create lists, write verses, and separate lines in other situations. While wrapped text helps maintain readability in the source file, you may need to enforce hard line breaks to control how the text appears in the final document.

AsciiDoc provides several ways to insert hard line breaks, allowing you to control the layout of your text precisely. You can insert a hard line break by ending a line with a space followed by a plus sign (+). This simple technique gives you control over your text layout and allows you to format your document precisely.

Fig 1. Ending a line with a space followed by a plus sign (+) to start a new line without wrapping the text.

Additionally, you can use the following methods to incorporate hard line breaks in Asciidoc.

• The hard breaks option, you can enable hard line breaks by adding [%hardbreaks] before your content. This directive allows you to take control of your text layout and insert hard line breaks where needed.
  By adding [%hardbreaks], you can precisely format your document and ensure that your text appears exactly as you intend.

• Add the “hard breaks” attribute to the document’s header to preserve line breaks throughout your whole document. You can achieve this by adding ‘’=’’ to the title of the document and ‘’:hardbreaks:" after that.

Admonitions#

Admonitions in AsciiDoc are an effective tool for improving your documentation. They are similar to special messages that highlight important information in a document.

Assume you are reading a guide or a book, and the author wants you to pay attention to certain details, such as a warning about something dangerous or a helpful tip.

Admonitions are used to make messages stand out, so you do not miss them.
AsciiDoc offers five admonition-style labels.

• Note : By adding the “note” label, you give readers the extra insight they need to fully grasp the topic, highlighting related points and showing connections between ideas to expand on key concepts.
  This additional information, while not essential, provides a richer understanding of the topic, making your documentation more informative and engaging.

• Tip: By implementing the “tip” label, you provide valuable insights and best practices, to help readers work more efficiently and achieve better results.
  This friendly piece of advice allows readers to easily navigate challenges, making their experience more productive and enjoyable.

• Important: The “important” label denotes a level of seriousness greater than that of a standard note, such as a reminder to back up your data before making significant changes.
  It signifies the importance of paying close attention to a particular matter, emphasizing that it should not be overlooked, similar to a substantial reminder that warrants careful consideration.

• Caution: The “caution” is a warning about something that could cause problems if not handled carefully. It is like a gentle reminder to proceed with caution

• Warning: The "warning" label actively warns readers of potential negative consequences, such as damage or loss, if they fail to follow instructions carefully, emphasizing the risks and urging them to take necessary precautions to avoid harm.

In AsciiDoc, caution and warning are both used to alert readers to potential risks, but they differ in their level of severity.

A caution is intended to make the reader aware of something that could go wrong if they’re not careful, but the consequences are generally moderate. It’s like a gentle reminder to proceed with care, as ignoring it could lead to minor problems or inconveniences.

On the other hand, a warning signals a more serious risk that could result in significant harm, such as system failure, data loss, or physical injury. It’s a stronger alert meant to stop the reader in their tracks, emphasizing that ignoring it could lead to major issues.
While both are important, a warning carries a higher level of urgency and is used for more critical situations.

Punctuation#

In AsciiDoc, punctuation is used much like it is in regular text. You need to use punctuation correctly so that your text looks good and is easy to read. If you do it right, your text will look great, and people will understand what you’re saying. In Asciidoc, punctuation is referred to as quoted text.

Quoted Text
In AsciiDoc, quoted text serves as a visual mechanism for highlighting dialogues or emphasizing particular content.
Comparable to traditional quotation marks in standard writing, AsciiDoc presents additional formatting options for ensuring the effective visual distinction of quoted content.

One of the instances of quoted text in AsciiDoc is the asterisk, which is used primarily for emphasis, similar to how you might use bold or italics in other word processors.

Here are the alternative forms of quoted text that AsciiDoc recognizes. You can apply bold, italic, and monospace formatting to the text using the following syntax:

When writing in AsciiDoc, you can make certain words or phrases look special by giving them a “role”. Think of it like labeling a word as “important” or “code.”.

To do this, you add a special label before the word, like [.userinput]#asciidoc#. This tells the computer to make the word “asciidoc” look different.

However, sometimes, you might not want the computer to change the way your text looks. That’s where “escaping” comes in. It’s like telling the computer, “Hey, don’t touch this text! Leave it exactly as I typed it. “When you “escape” text, you’re telling the computer not to add any special formatting or styles. It’s like a “do not touch” sign for your text.
In summary,

• Roles (like [.userinput]) help you make text look special
• Escaping helps you keep text exactly as you typed it, without any extra formatting

Preventing Substitution
In AsciiDoc, specific characters trigger automatic text formatting. For example, asterisks (*) enclose text in bold, underscores () make text italic, and double underscores ( _) create bold text.

This feature allows for quick text styling for emphasis or clarity.
However, this automatic formatting may not always align with your intentions. At times, you may need the text to remain exactly as typed, without special formatting. AsciiDoc provides tools like backslash escaping and passthrough macros to help you control text formatting.
Understanding how quoted text behaves in AsciiDoc is crucial for customizing the appearance of your documents.

Backslash Escaping
In AsciiDoc, you use backslash escaping to tell the program to ignore its usual formatting rules and print the text as is.
You place a backslash () before a character to shield it from formatting. This way, you can control how your text looks.
For example:

• You write * to print a literal asterisk (*) instead of making the text bold.
• You write _ to print a literal underscore (_) instead of making the text italic.

By using backslash escaping, you take charge of your text’s formatting and avoid unexpected changes. You decide how your text looks, and AsciiDoc follows your lead.

Inline pass macro and explicit substitution
You use an inline pass macro to wrap your text in a protective bubble, telling AsciiDoc to leave it alone.
By enclosing your text in ‘’pass:[text goes here]’’, you command AsciiDoc to pass it through to the output without making any changes. You’re in charge, and you’re telling AsciiDoc to:

• Leave your text as is
• Don’t touch your special characters or formatting commands
• Just pass it through to the output, unchanged

By using an inline pass macro, you take control of your text’s formatting and ensure it looks exactly how you want it to!

You enclose a phrase in the inline pass macro to exclude it from substitutions and disable escaping of special characters. This way, you can control how your text is formatted.

For example, you want to underline a word when converting your document to HTML, without applying any other formatting to it. You take action by wrapping the word in the inline pass macro, like this: ‘’pass:[underline me]’’.
By doing so, you:

• Prevent AsciiDoc from applying any other formatting to the word
• Ensure the word is underlined in the HTML output, without any additional changes

You’re in charge of your text’s formatting, and the inline pass macro helps you achieve your desired output!  

You enable ad-hoc quotes substitution by setting the macros value to subs, allowing you to control the replacement of specific characters or quotes.

Then, you use the inline pass macro to specify which quotes to replace and with what, taking charge of the substitution process. By doing so, you ensure that specific quotes are replaced with other characters in certain places, achieving your desired text formatting.  

You can also specify which types of substitutions AsciiDoc should ignore by using shorthand values. Here’s how each shorthand value works:

Shorthand Values

• c = special characters
• q = quotes
• a = attributes
• r = replacements
• m = macros
• p = post replacements

Triple plus passthrough
The triple-plus passthrough in AsciiDoc works similarly to the pass macro but uses a different syntax. To prevent AsciiDoc from applying any formatting or substitutions to your text, enclose it in triple pluses (+++). You often use this method to include custom HTML or XML code in your document.
How It Works:

• Triple-Plus Syntax:
  Place +++ before and after your text to tell AsciiDoc to ignore everything inside those markers. It won’t format, change, or substitute anything.  

You typically use the triple-plus passthrough when you need to add raw HTML or XML code to your document. By wrapping the code in triple pluses, you ensure that AsciiDoc leaves it exactly as you wrote it.

When you convert your AsciiDoc to HTML, the text inside the triple pluses appears exactly as written, creating a div with the specified class.

You use the triple-plus passthrough to embed code or content that AsciiDoc doesn’t natively handle, ensuring your custom HTML, XML, or other code stays intact in the final output.

In summary, the triple-plus passthrough lets you include unaltered text, code, or markup in your AsciiDoc documents, making it perfect for custom HTML or XML output.

Single plus enclosure
You protect a phrase from substitutions by wrapping it in plus signs (+) like this: +phrase+. By doing so, you tell the Asciidoc to leave the phrase alone and not make any changes to it. It’s like putting a “do not touch” sign on your text!

Replacements
In AsciiDoc, you can use simple text to represent symbols, arrows, and dashes, making your writing look cleaner and more professional without sacrificing readability.

You can easily create an arrow by typing -> or a dash by typing –, using formats that you’re likely already familiar with. These textual symbols unclutter your text and make it easier to follow. You likely recognize these standard ways of writing, which helps them feel natural to use and understand.

Textual symbol replacements

This simple punctuation does not reduce the readability of the text. In fact, it might actually make the text easier to read.
What is important is that these are standard practices you are probably already familiar with.

In AsciiDoc, you also use punctuation to create one of the most common elements in document lists!
Check out the second part of the writing in AsciiDoc guide to explore more about its syntax and advanced features.