AsciiDoc Editor Specification

Overview

This specification defines the features and behaviors that a conformant AsciiDoc editor or IDE plugin MUST, SHOULD, or MAY implement to deliver a productive authoring experience for AsciiDoc writers.

The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are interpreted as described in RFC 2119.

Feature Areas

  • Language Support — File recognition, syntax highlighting, language configuration

  • Editing — Auto-completion, snippets, text formatting shortcuts, smart pairing, image insertion

  • Text Folding — Folding of sections, blocks, and conditional directives

  • Navigation — Document outline, go-to-definition, breadcrumbs, cross-references

  • Diagnostics & Validation — Error reporting, inspections, spell and grammar checking

  • Preview — Live preview, scroll synchronization, security modes

  • Diagram Integration — PlantUML, Mermaid, Kroki and other diagram renderers

  • Export — HTML, PDF, DOCX document generation

  • Refactoring — Rename, extract include, inline include

  • Configuration — .asciidoctorconfig, custom Asciidoctor extensions

  • Antora Integration — Project detection, cross-reference resolution, attribute completion

Conformance Levels

Editors implementing this specification may conform at one of the following levels:

Basic

Implements all MUST requirements across Language Support, Editing, Preview, and Export.

Standard

Satisfies Basic, plus all SHOULD requirements across all feature areas.

Advanced

Satisfies Standard, plus all MAY requirements, including Antora integration, diagram rendering, refactoring, and CI/CD validation.