AsciiDoc Linter Rules

Heading Rules

HEAD001: Heading Hierarchy

Ensures proper heading level incrementation (no skipped levels).

Description

This rule checks that heading levels are not skipped. For example, you cannot go from a level 1 heading (=) directly to a level 3 heading (===) without having a level 2 heading (==) in between.

Examples
Valid Heading Hierarchy
== Document Title (Level 1)

=== Section (Level 2)

==== Subsection (Level 3)

=== Another Section (Level 2)
Invalid Heading Hierarchy
== Document Title (Level 1)

==== Subsection (Level 3)  // Error: Skipped Level 2

HEAD002: Heading Format

Ensures proper heading format (spacing and capitalization).

Description

This rule checks two aspects of heading format: 1. There must be a space after the = characters 2. The heading text should start with an uppercase letter

Examples
Valid Heading Format
== Document Title
=== Section Title
==== Subsection Title
Invalid Heading Format
=Document Title        // Error: No space after =
=== section title      // Warning: Starts with lowercase

HEAD003: Multiple Top Level Headings

Ensures document has only one top-level heading.

Description

This rule checks that there is only one level 1 heading (=) in the document. Multiple top-level headings can indicate structural problems or accidentally split documents.

Examples
Valid Single Top Level
== Main Document Title

=== Section One
=== Section Two
Invalid Multiple Top Level
== First Title

=== Section One

== Second Title  // Error: Multiple top-level headings

Block Rules

BLOCK001: Unterminated Blocks

Checks for blocks that are not properly terminated.

Description

This rule ensures that all block delimiters are properly paired. Each opening delimiter must have a matching closing delimiter.

Supported Block Types

  • Listing blocks (----)

  • Example blocks (====)

  • Sidebar blocks (****)

  • Literal blocks (…​.)

  • Quote blocks (_\_)

  • Table blocks (|===)

  • Comment blocks (////)

  • Passthrough blocks (+\+).

Examples
Valid Block Termination
[source,python]

def hello(): print("Hello, World!")

.Example Block
====
Some example content
====
Invalid Block Termination
[source,python]

def hello(): print("Hello, World!")

Example 1. Example Block

Some example content

==== BLOCK002: Block Spacing

Verifies proper spacing around blocks.

===== Description

This rule checks that blocks are properly separated from surrounding content with blank lines, improving readability.

===== Examples

.Valid Block Spacing
[source,asciidoc]

Some text before the block.

Block content

Some text after the block.

.Invalid Block Spacing
[source,asciidoc]

Some text before the block. ---- // Warning: No blank line before block Block content

Some text after the block.  // Warning: No blank line after block

=== Whitespace Rules

==== WS001: Whitespace Usage

Ensures proper whitespace usage throughout the document.

===== Checks Performed

  1. Consecutive Empty Lines: No more than one consecutive empty line

  2. List Marker Spacing: Proper space after list markers (*, -, .)

  3. Admonition Block Spacing: Blank line before admonition blocks

  4. Trailing Whitespace: No trailing spaces at end of lines

  5. Tab Usage: No tabs (use spaces instead)

  6. Section Title Spacing: Blank lines around section titles

===== Examples

Valid Whitespace Usage
== Document Title

=== Section Title

* List item 1
* List item 2

NOTE: This is a note.

Some text here.
Invalid Whitespace Usage
== Document Title
=== Section Title     // Missing blank line before
*Invalid list item   // Missing space after marker
NOTE: Invalid note   // Missing blank line before
Some text here  // Trailing spaces
	Tabbed line      // Tab instead of spaces


Extra blank line     // Too many blank lines

=== Image Rules

==== IMG001: Image Attributes

Verifies image attributes and file references.

===== Description

This rule checks: 1. All images have alt text 2. Referenced local images exist 3. Block images have titles 4. Image attributes are properly formatted

===== Examples

Valid Image Usage
// Inline image with alt text
image:icon.png[Icon]

// Block image with title and alt text
.Figure 1: System Architecture
image::diagram.png[Architecture Diagram]

// External image with alt text
image:https://example.com/img.png[Example Image]
Invalid Image Usage
// Missing alt text
image:icon.png[]

// Missing title for block image
image::diagram.png[Diagram]

// Non-existent local file
image::missing.png[Missing Image]

=== Format Rules

==== FMT004: Markdown Syntax Detection

Detects Markdown-style syntax in AsciiDoc files and suggests AsciiDoc alternatives.

===== Description

This rule is particularly useful for documents generated by LLMs that may accidentally use Markdown syntax instead of AsciiDoc. It detects common Markdown patterns and provides suggestions for the correct AsciiDoc equivalent.

===== Detected Patterns

Markdown Syntax AsciiDoc Equivalent Description

# Heading

= Heading

Markdown headings (# through )

[text](url)

text

Markdown links

![alt](path)

image::path[alt]

Markdown images

```language

[source,language] + ----

Markdown code fences

> quote

[quote] block or __

Markdown blockquotes

===== Examples

Markdown Syntax (will be flagged)
# This is a Markdown Heading

Check out [this link](https://example.com) for more info.

![Screenshot](images/screenshot.png)

> This is a quoted text

```python
print("Hello")
```
AsciiDoc Equivalent (correct)
== This is an AsciiDoc Heading

Check out link:https://example.com[this link] for more info.

image::images/screenshot.png[Screenshot]

[quote]
____
This is a quoted text
____

[source,python]

print("Hello")









=== Planned Rules






==== TABLE001: Table Formatting (Planned)






Will check table formatting consistency:
* Column alignment
* Header row presence
* Cell content formatting






==== LINK001: Link Verification (Planned)






Will verify:
* Internal cross-references
* External link validity
* Anchor definitions






==== FMT001: Explicit Numbered List Detection






Detects explicit numbered lists (1., 2., etc.) and suggests using AsciiDoc dot-syntax (.).






===== Description






This rule is particularly useful for documents generated by LLMs that may accidentally use explicit numbered lists instead of AsciiDoc’s auto-numbering syntax.






Explicit numbering is problematic because:






    

  • 

    It doesn’t auto-renumber when items are added/removed
    

    • 

  • 

    It’s not semantic AsciiDoc
    

    • 

  • 

    It creates maintenance burden
    

    • 







===== Examples






Explicit Numbered List (will be flagged)




1. First step
2. Second step
3. Third step








AsciiDoc Equivalent (correct)




. First step
. Second step
. Third step








===== Edge Cases






The rule correctly ignores:






    

  • 

    Decimal numbers like 1.5 kg or Version 2.0
    

    • 

  • 

    Numbers followed by dot without space: Chapter 1.Introduction
    

    • 

  • 

    Content inside code blocks (----), literal blocks (…​.), and passthrough blocks ()
    

    • 







==== FMT002: Non-Semantic Definition List Detection








Detects non-semantic definition list patterns and suggests using AsciiDoc `Term




Definition` syntax.










===== Description






This rule is particularly useful for documents generated by LLMs that may create "fake" definition lists using formatting hacks instead of proper AsciiDoc Definition List syntax.






Non-semantic patterns are problematic because:






    

  • 

    Definition Lists are semantic markup that render properly in all output formats
    

    • 

  • 

    They’re accessible (screen readers understand them)
    

    • 

  • 

    LLM-generated docs often use bold/italic hacks that lose semantics
    

    • 







===== Detected Patterns












Non-Semantic Pattern
Should Be







Term: definition


Term:: definition






Term: definition


Term:: definition






- Term: definition


Term:: definition






* Term: definition


Term:: definition









===== Examples






Non-Semantic Patterns (will be flagged)




*API*: Application Programming Interface
**REST**: Representational State Transfer
- *HTTP*: Hypertext Transfer Protocol








AsciiDoc Equivalent (correct)




API:: Application Programming Interface
REST:: Representational State Transfer
HTTP:: Hypertext Transfer Protocol








===== Edge Cases






The rule correctly ignores:






    

  • 

    Proper AsciiDoc definition lists (Term::)
    

    • 

  • 

    Inline bold text with colon in sentences
    

    • 

  • 

    AsciiDoc attributes (:icons: font)
    

    • 

  • 

    Content inside code blocks
    

    • 







==== FMT003: Counter Syntax in Title Detection






Detects 1 usage in section titles and suggests reviewing if counters are really needed.






===== Description






This rule is particularly useful for documents generated by LLMs that may use counter syntax in section titles unnecessarily.






Counter syntax in titles is often problematic because:






    

  • 

    Simple sequential sections don’t need explicit counters
    

    • 

  • 

    Counter state can be confusing across includes
    

    • 

  • 

    LLMs often mimic numbered headings from other formats unnecessarily
    

    • 







===== Examples






Counter in Titles (will be flagged)




=== Phase {counter:phase}
==== Step {counter:step}: Configuration
=== {counter:section} Overview








Alternatives (correct)




=== Phase 1: Discovery
=== Phase 2: Implementation

// Or use descriptive titles:
=== Discovery Phase
=== Implementation Phase








===== Edge Cases






The rule correctly ignores:






    

  • 

    Counter syntax in regular content (not in section titles)
    

    • 

  • 

    Counter with format specifiers (%02d)
    

    • 

  • 

     variant is also detected
    

    • 

  • 

    Content inside code blocks
    

    •