From dita-tools
Fixes Additional resources sections for DITA by removing non-link content like paragraphs and notes, normalizing trailing text on links, and converting paragraph links to list items. Use when preparing docs for DITA conversion or cleaning related links.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin dita-toolsThis skill is limited to using the following tools:
Fix Additional resources sections by removing non-link content for DITA compatibility.
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.
Runs Vale with AsciiDocDITA rules on AsciiDoc files in Red Hat modular docs repos (repo-wide or assembly/topic scope via dita-validate-asciidoc) and fixes violations for 0 errors/warnings.
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.
Share bugs, ideas, or general feedback.
Fix Additional resources sections by removing non-link content for DITA compatibility.
This skill uses the related_links.rb Ruby script to find and fix Additional resources sections that contain content other than links. In DITA, the <related-links> element can only contain link elements, not arbitrary content.
The Vale rule RelatedLinks.yml detects content in Additional resources sections that is not:
link:url[text] or mailto:email[text]https://... or <https://...>xref:target[text]<<target>>{some-link-attribute}Links with additional descriptive text are preserved but normalized by removing the trailing text.
Before:
.Additional resources
* link:https://kueue.sigs.k8s.io/docs/concepts/resource_flavor/[Resource Flavor] in the Kueue documentation
* link:https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/[Cluster Queue] in the Kueue documentation
After:
.Additional resources
* link:https://kueue.sigs.k8s.io/docs/concepts/resource_flavor/[Resource Flavor]
* link:https://kueue.sigs.k8s.io/docs/concepts/cluster_queue/[Cluster Queue]
Links embedded in paragraph text (e.g., "See also link:...") are converted to proper list items.
Before:
.Additional resources
ifdef::cloud-service[]
See also link:https://docs.redhat.com/en/documentation/openshift_dedicated/index[OpenShift Dedicated cluster administration].
endif::[]
After:
.Additional resources
ifdef::cloud-service[]
* link:https://docs.redhat.com/en/documentation/openshift_dedicated/index[OpenShift Dedicated cluster administration]
endif::[]
Before:
.Additional resources
This section provides helpful links for further reading.
* link:https://example.com[Example site]
* xref:related-topic[Related topic]
After:
.Additional resources
* link:https://example.com[Example site]
* xref:related-topic[Related topic]
Before:
.Additional resources
[NOTE]
====
Remember to check these resources regularly.
====
* link:https://example.com[Example site]
After:
.Additional resources
* link:https://example.com[Example site]
Before:
.Additional resources
* This is just text, not a link
* link:https://example.com[Example site]
* Another plain text item
After:
.Additional resources
* link:https://example.com[Example site]
When the user asks to fix additional resources:
.adoc files in the target locationruby scripts/related_links.rb <file>
To preview changes without modifying files:
ruby scripts/related_links.rb <file> --dry-run
ruby scripts/related_links.rb <file> -o <output.adoc>
find <folder> -name "*.adoc" -exec ruby scripts/related_links.rb {} \;
<file>: normalized N link(s) in Additional resources
Or:
<file>: removed N non-link item(s), normalized M link(s) in Additional resources
Or:
<file>: No issues found in Additional resources
Or:
<file>: No Additional resources section found
The Ruby script is located at: scripts/related_links.rb
This skill addresses the warning from: .vale/styles/AsciiDocDITA/RelatedLinks.yml