Refactoring

Rename

An editor SHOULD provide a rename refactoring for the following AsciiDoc elements:

  • Anchor IDs: renaming an anchor ([[id]] or [id]) updates all xref:id[] and <<id>> cross-references pointing to it across all files in the workspace.

  • Document attributes: renaming an attribute declaration (:[name]:) updates all {name} references throughout the document and, where applicable, across other files.

  • File names: renaming an AsciiDoc file updates all include:: directives and xref: references that target it across the workspace.

Rename refactoring MUST be preview-able before being applied (showing which files and lines will change). Rename refactoring MUST be undoable as a single atomic action.

Extract Include

An editor SHOULD provide an "Extract Include" refactoring that:

  1. Takes a selected region of AsciiDoc content

  2. Creates a new file with that content

  3. Replaces the selected region with an include:: directive pointing to the new file

An editor implementing Extract Include SHOULD:

  • Prompt for the target file name and location

  • Compute the correct relative path for the include:: directive

  • Preserve block delimiters and attributes that belong to the extracted content

Inline Include

An editor SHOULD provide an "Inline Include" refactoring that replaces an include:: directive with the actual content of the referenced file.

An editor implementing Inline Include SHOULD:

  • Preserve the content verbatim

  • Remove only the include:: line

Markdown to AsciiDoc Conversion

An editor MAY provide a "Convert Markdown to AsciiDoc" action available on .md files that produces an equivalent .adoc file using Pandoc or a compatible converter. This conversion MUST be undoable.

An editor MAY suggest this conversion via an inspection when a Markdown file is opened.

Single-Line to Block Admonition

An editor MAY provide an intention action to convert a single-line admonition (e.g., NOTE: text) to its block equivalent:

[NOTE]
====
text
====