10 Tips for Headings in AsciiDoc

1. Use a Logical Structure

Let's begin with the basics. Organize your document with a clear hierarchy. Start with = for the main title, then == for major sections, === for subsections, and so forth. Most markup languages order headings by hierarchy - AsciiDoc is no different. This hierarchy helps readers understand the document’s structure at a glance.

Outline your document structure before writing any content. This way, you can counter the infamous writer's block as you already have a plan in mind on what topic you want to address in which section.

2. Be Concise and Descriptive

Headings and subheadings should be brief yet descriptive enough to convey the essence of the section. Avoid vague titles; readers should know what to expect in each section. Write in active voice instead of passive voice. In active voice, the subject performs an action. It comes in front of the verb. In comparison: the passive voice focuses on the actions of the object.

3. Use Parallel Structure

For headings at the same level, maintain a consistent grammatical structure. This uniformity helps in maintaining a smooth flow and enhances readability. For example, start every heading with the same word structure such as a gerund (verb + ing: e.g. "exploring", "finding", "using", ...).

The keyword is "parallelism". Write headings in a consistent sentence structure. Each heading in this article starts with a verb in the imperative and addresses you directly. This places the focus directly on actions and recommendations.

4. Incorporate Keywords

Use relevant keywords in your headings and subheadings for better searchability and to emphasize the document's main points. However, avoid keyword stuffing. For example, it doesn't add any value to integrate your product name into all headings.

Keep your reader in mind: What keywords are they most likely to search for? This should be an integral part of your audience analysis. Ask yourself what your reader is looking for when scanning your document. Are they having issues with your product/service? Are they reading out of curiosity since they want to unleash the product's full potential?

5. Limit the Number of Levels

Too many levels can make your document look complicated. Try to limit your document structure to three or four levels of headings to keep it accessible.

An outline is balanced if the number of sections and subsections in each chapter does not vary too much. It does not make much sense if a chapter contains only one subsection or section.

Technical Writing on Mac, iPad & iPhone

Start Free Trial

6. Separate Sections Clearly

AsciiDoc automatically handles spacing, but ensure that your headings stand out from the text and from each other, making the document easier to scan. If you are customizing the stylesheet used for layout and design of the document, make sure to leave enough white space above the heading.

7. Use Anchors for Linking

In most cases, technical documents are not read from beginning to end like novels, but are searched for specific topics. Fast navigation is essential for this. Digital documents have an advantage over printed documents here: they can link texts to each other. Here is a tip on how you can use this linking effectively so that your readers can find the desired text passage as quickly as possible:

You can assign so-called "anchors" to the headings. This is an element - invisible in the output - that creates a reference point for links. Define the anchor in the line above your heading/subheading with [#anchor-name]. You can now refer to it in other parts of your document. For the reference, write <#anchor-name>. If you want to add a custom title to the reference, you can add it to the syntax with a comma: <#anchor-name, title>.

Although you can also refer directly to the heading, we recommend that you always use an anchor. This means that you do not have to adjust the reference when making changes to the heading. The link works as long as you do not change the anchor. As it does not appear in the output, you have no problem leaving the anchor name unchanged.

8. Avoid Orphan Headings

Orphaned headings are detached from the text. For example, they are on a different page and are separated from their content by a page break. Avoid this happening.

9. Keep Them Aligned

Ensure all headings and subheadings are aligned the same way. This most often means to left-align them in order to maintain a clean, professional appearance and ease of reading.

However, center alignment can also work in some cases. You can change the alignment from left to center by writing [.text-center] in the line directly above the heading.

10. Review for Consistency

Ensure consistent use of capitalization, punctuation, and format throughout your document. Consistency helps in maintaining professionalism and aids readability.

Remember, well-crafted headings and subheadings not only organize your content but also guide your readers through your document, making complex information easier to navigate and understand.