dita-tools

v0.0.12

AsciiDoc cleanup, validation, and rewriting tools for DITA conversion preparation.

Tip

Always run Claude Code from a terminal in the root of the documentation repository you are working on. The dita-tools command operates on the current working directory, reading local files, checking git branches, and writing output relative to the repo root.

Warning

Always validate your reworked content with the AsciiDocDITA Vale style (vale --config=.vale.ini --glob='*.adoc') before submitting a PR/MR for merge. The /dita-rework command runs Vale checks during the workflow, but you must confirm that no new issues have been introduced and all reported issues are resolved before merging.

Prerequisites

Install the Red Hat Docs Agent Tools marketplace
Install software dependencies

Suggested workflow

The dita-rework command prepares AsciiDoc content for DITA conversion. It operates in three modes: a script-based cleanup pipeline (default), an LLM-guided rewrite mode, and a review mode.

Command syntax

/dita-tools:dita-rework <file.adoc|assembly.adoc> [--rewrite [--no-commit] [--dry-run] [--branch <name>]] [--review]

The <file> argument is required. It can be a single AsciiDoc module, an assembly file, or a folder of .adoc files. If an assembly is provided, all included modules are discovered and processed automatically.

Modes and switches

Switch	Mode	Description
(none)	Default (Phase D)	Script-based rework pipeline. Runs all DITA cleanup skills in sequence against the target file and its includes. Each skill is committed separately.
`--rewrite`	Rewrite (Phase W)	LLM-guided rewrite pipeline. Reads each file, reviews Vale AsciiDocDITA issues, and applies targeted fixes using AI.
`--review`	Review (Phase R)	Post-rework review. Compares reworked files against the upstream/main branch and produces a diff report.

Rewrite mode options

These switches are only valid when --rewrite is also specified:

Switch	Description
`--no-commit`	Skip git commit creation after each file is fixed.
`--dry-run`	Show what would be done without modifying any files.
`--branch <name>`	Use a custom branch name instead of the auto-generated one.

Running the default pipeline

The default mode runs the full suite of DITA cleanup skills in sequence:

/dita-tools:dita-rework guides/master.adoc

This creates a working branch, discovers all included files, runs a baseline Vale check, and then executes each cleanup skill in order:

dita-content-type — add or update :_mod-docs-content-type: attribute
dita-document-id — generate missing anchor IDs
dita-callouts — transform callouts to bullet lists
dita-entity-reference — replace HTML entities with Unicode
dita-line-break — remove hard line breaks
dita-related-links — normalize Additional resources sections
dita-add-shortdesc-abstract — add missing [role="_abstract"] attributes
dita-task-contents — add missing .Procedure block titles
dita-task-step — fix list continuations in procedure steps
dita-task-title — remove unsupported block titles from procedures
dita-block-title — fix unsupported block titles
dita-check-asciidoctor — validate AsciiDoc syntax

Each skill is committed individually. After all skills run, a final Vale check compares the results against the baseline and a summary is written to /tmp/dita-rework-pr-summary.md.

Running the rewrite pipeline

The rewrite mode uses the LLM to analyze and fix Vale AsciiDocDITA violations file by file:

/dita-tools:dita-rework guides/master.adoc --rewrite

To preview changes without modifying files:

/dita-tools:dita-rework guides/master.adoc --rewrite --dry-run

To run on a named branch without auto-committing:

/dita-tools:dita-rework guides/master.adoc --rewrite --no-commit --branch my-dita-fixes

Running the review

After reworking content, run the review mode to compare your changes against the upstream branch:

/dita-tools:dita-rework guides/master.adoc --review

This renders both versions to plain text, generates a diff, and writes a review report to /tmp/dita-rework-review-report.md.

Running with Ralph Loop

For large assemblies with many modules, you can use Ralph Loop to iterate the rewrite pipeline until all Vale issues are resolved. Ralph Loop re-runs the command automatically, checking progress after each iteration and stopping when the completion promise is met or the iteration limit is reached.

Tip

Open a terminal and install the Ralph Loop Claude plugin:

claude plugin install ralph-loop@claude-plugins-official

Then open Claude and start a DITA rework loop:

/ralph-loop:ralph-loop "Run /dita-tools:dita-rewrite on guides/master.adoc including all referenced modules. Fix all Vale AsciiDocDITA rule violations" --completion-promise "0 errors, 0 warnings" --max-iterations 20

This tells Ralph Loop to keep running the rewrite workflow until Vale reports zero errors and zero warnings, with a maximum of 20 iterations.

Typical end-to-end workflow

Rework — Run the default pipeline to apply script-based fixes:
```
/dita-tools:dita-rework guides/master.adoc
```
Rewrite — Run the rewrite pipeline to fix remaining issues with LLM-guided edits:
```
/dita-tools:dita-rework guides/master.adoc --rewrite
```
Validate — Confirm that all AsciiDocDITA Vale rules pass:
```
vale --config=.vale.ini --glob='*.adoc' guides/
```
Review — Compare your changes against the upstream branch:
```
/dita-tools:dita-rework guides/master.adoc --review
```
Submit — Push the branch and open a PR/MR for merge.

Install

/plugin install dita-tools@redhat-docs-agent-tools

Update

/plugin marketplace update redhat-docs-agent-tools

Commands

`dita-rework`

/dita-tools:dita-rework <file.adoc|assembly.adoc> [--rewrite [--no-commit] [--dry-run] [--branch <name>]] [--review]

Run the DITA rework workflow to prepare AsciiDoc files for DITA conversion

Skills

Skill	Description
`dita-add-shortdesc-abstract`	Add missing [role="_abstract"] attribute to AsciiDoc files for DITA short description support. Use this skill when asked to add abstract role attributes, mark short descriptions, or prepare files for DITA conversion.
`dita-asciidoc-rewrite`	Refactor AsciiDoc files for DITA conversion compatibility using LLM-guided analysis. Use this skill to fix Vale issues, prepare files for DITA conversion, or comprehensively rewrite AsciiDoc modules and assemblies following Red Hat modular documentation standards.
`dita-block-title`	Fix unsupported block titles for DITA compatibility. Block titles are only valid for examples, figures (images), and tables. Use this skill when asked to fix block titles, remediate BlockTitle warnings, or prepare files for DITA conversion.
`dita-callouts`	Transform callouts in AsciiDoc source blocks to prepare for DITA conversion. Use this skill when asked to transform, convert, or fix callouts in AsciiDoc files or folders.
`dita-check-asciidoctor`	Run asciidoctor to check AsciiDoc files for syntax errors. Outputs timestamped build log to /tmp. Reports warnings and errors, then reviews source to suggest fixes for common issues like unclosed conditionals, admonitions, and code blocks.
`dita-content-type`	Add or update :_mod-docs-content-type: attribute in AsciiDoc files. Detects content type (CONCEPT, PROCEDURE, ASSEMBLY, SNIPPET) from file structure and adds the attribute if missing. Use this skill when asked to add content types, fix module types, or prepare files for DITA conversion.
`dita-document-id`	Generate and insert missing document IDs for AsciiDoc titles. Use this skill when asked to add IDs, fix missing anchors, or prepare files for DITA conversion.
`dita-entity-reference`	Replace HTML character entity references with Unicode equivalents for DITA compatibility. Use this skill when asked to fix entity references, replace HTML entities, or prepare files for DITA conversion.
`dita-includes`	List all AsciiDoc files referenced via include directives, recursively traversing child includes. Use this skill when asked to find includes, list dependencies, or analyze AsciiDoc file structure.
`dita-line-break`	Remove hard line breaks from AsciiDoc files for DITA compatibility. Use this skill when asked to fix line breaks, remove forced breaks, or prepare files for DITA conversion.
`dita-reduce-asciidoc`	Reduce AsciiDoc files by expanding all include directives into a single flattened document using asciidoctor-reducer. Use this skill when asked to reduce, flatten, resolve, or normalize AsciiDoc assemblies.
`dita-related-links`	Fix Additional resources sections by removing or relocating non-link content for DITA compatibility. Use this skill when asked to fix additional resources, clean up related links, or prepare files for DITA conversion.
`dita-rework-assembly`	Extract inline content from AsciiDoc assembly files into separate modules. Use when refactoring assemblies to follow Red Hat modular documentation standards — moving introductory preambles, inline procedures, inline concepts, admonitions, or any other content into reusable modules.
`dita-rewrite-shortdesc`	Rewrite or improve short descriptions in AsciiDoc files for better clarity and DITA compliance. Use this skill when asked to fix short descriptions, improve abstracts, rewrite summaries, or make short descriptions more effective.
`dita-task-contents`	Add missing .Procedure block title to procedure modules for DITA compatibility. Use this skill when asked to fix procedure titles, add .Procedure markers, or prepare procedure files for DITA conversion.
`dita-task-step`	Fix list continuations in procedure steps for DITA compatibility. Use this skill when asked to fix task steps, add list continuations, or prepare procedure files for DITA conversion.
`dita-task-title`	Remove unsupported block titles from procedure modules for DITA compatibility. Use this skill when asked to fix task titles, remove unsupported titles, or prepare procedure files for DITA conversion.
`dita-validate-asciidoc`	Validate AsciiDoc files for DITA conversion readiness by running Vale linting with AsciiDocDITA rules. Reports warnings and errors in a markdown table format. Use this skill when asked to validate, check, or assess AsciiDoc files before DITA conversion.