From dita-tools
Fixes unsupported block titles in AsciiDoc files for DITA compatibility by remediating invalid contexts like source blocks, paragraphs, lists, and admonitions using a Ruby script. Use for BlockTitle warnings or DITA prep.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin dita-toolsThis skill is limited to using the following tools:
Fix unsupported block titles in AsciiDoc files for DITA compatibility.
Removes unsupported block titles like .Example and .Note from AsciiDoc procedure modules using Ruby script for DITA task compatibility. Useful when fixing titles or preparing files for DITA conversion.
Reviews AsciiDoc (.adoc) files for Red Hat modular documentation compliance: module types (concept, procedure, reference), assembly structure, anchor IDs with _{context}, context variables, and include directives.
Assesses CQA parameters P8-P11 for titles and short descriptions in Red Hat modular documentation, checking clarity, character limits, DITA conventions, and quality criteria.
Share bugs, ideas, or general feedback.
Fix unsupported block titles in AsciiDoc files for DITA compatibility.
This skill uses the block_title.rb Ruby script to identify and remediate block titles that are not supported in DITA. In DITA, block titles can only be assigned to examples, figures (images), and tables.
The Vale rule BlockTitle.yml detects block titles (lines starting with . or ..) that appear before unsupported content types.
Block titles are valid ONLY before:
image::)|===)[example] or ==== delimiters)Block titles before any other content type must be remediated:
[source,...] or ----)[NOTE], [WARNING], etc.)The following block titles in PROCEDURE modules are handled by the dita-tools:dita-task-title skill instead:
.Prerequisites.Procedure.Verification.Results.Troubleshooting.Next steps.Additional resourcesThe script applies context-appropriate remediation:
Convert to inline text with colon and add list continuation for proper rendering.
Before:
.Example manifest
[source,yaml]
----
apiVersion: v1
kind: Pod
----
After:
Example manifest:
+
[source,yaml]
----
apiVersion: v1
kind: Pod
----
Add double list continuation (++) when inside a numbered list.
Before:
. Create a manifest file:
+
.Example manifest
[source,yaml]
----
apiVersion: v1
----
After:
. Create a manifest file.
+
Example manifest:
++
[source,yaml]
----
apiVersion: v1
----
Convert to inline text with colon.
Before:
.Use cases
* Case 1
* Case 2
After:
Use cases:
* Case 1
* Case 2
Remove block titles that duplicate surrounding context.
Before:
You can create an instance type manifest by using the `virtctl` CLI utility. For example:
.Example `virtctl` command with required fields
[source,terminal]
----
$ virtctl create instancetype --cpu 2 --memory 256Mi
----
After:
You can create an instance type manifest by using the `virtctl` CLI utility. For example:
[source,terminal]
----
$ virtctl create instancetype --cpu 2 --memory 256Mi
----
Convert standalone descriptive titles to definition lists.
Before:
.VM snapshot controller and custom resources
The VM snapshot feature introduces three new API objects...
After:
VM snapshot controller and custom resources::
The VM snapshot feature introduces three new API objects...
When the user asks to fix block titles:
ruby scripts/block_title.rb <file>
To preview changes without modifying files:
ruby scripts/block_title.rb <file> --dry-run
ruby scripts/block_title.rb <file> -o <output.adoc>
find <folder> -name "*.adoc" -exec ruby scripts/block_title.rb {} \;
.Prerequisites and .Procedure are left for dita-task-title<file>: Fixed N block title(s)
Line 15: ".Example manifest" -> "Example manifest:" (before source block)
Line 42: ".Use cases" -> "Use cases:" (before list)
Line 78: ".Configuration" -> removed (redundant)
Or:
<file>: No unsupported block titles found
The Ruby script is located at: scripts/block_title.rb
This skill addresses the warning from: .vale/styles/AsciiDocDITA/BlockTitle.yml
Message: "Block titles can only be assigned to examples, figures, and tables in DITA."