dita-tools

v0.0.1

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

Important: 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.

Prerequisites

Configure the Red Hat Docs Agent Tools marketplace

Install Ruby and required gems

# RHEL/Fedora
sudo dnf install ruby

gem install asciidoctor

Install Vale CLI

# Fedora/RHEL
sudo dnf copr enable mczernek/vale && sudo dnf install vale

# macOS
brew install vale

Install review mode dependencies (required for --review)

sudo dnf install python3
gem install asciidoctor-reducer
python3 -m pip install html2text

Install

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

Update

/plugin marketplace update redhat-docs-agent-tools

Commands

/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-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-intro`	Rework introductory content from AsciiDoc assembly files (master.adoc) into separate concept modules. Use when refactoring assemblies to follow Red Hat modular documentation standards, when asked to move intro content to modules, or when creating about-* modules from assembly preambles.
`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.