Dita Entity Reference

Entity reference transform skill

Replace unsupported HTML character entity references with their Unicode equivalents for DITA compatibility.

Overview

This skill uses the entity_reference.rb Ruby script to find and replace HTML character entity references (like  , —, ©) with their Unicode character equivalents. DITA only supports five XML entities: &, <, >, ', and ".

What it transforms

Common replacements

| Entity | Unicode | Description | |--------|---------|-------------| |   | | Non-breaking space | | – | – | En dash | | — | — | Em dash | | … | … | Horizontal ellipsis | | © | © | Copyright | | ® | ® | Registered trademark | | ™ | ™ | Trademark | | → | → | Right arrow | | ← | ← | Left arrow |

Supported entity categories

• Spaces and breaks
• Dashes and hyphens
• Quotation marks
• Punctuation
• Currency symbols
• Math and symbols
• Arrows
• Greek letters
• Accented characters

Usage

When the user asks to fix entity references:

1. Identify the target folder or file containing AsciiDoc content
2. Find all .adoc files in the target location
3. Run the Ruby script against each file:

``bash ruby ${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb ``

1. Report the number of replacements made and any unknown entities found

Dry run mode

To preview changes without modifying files:

ruby ${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb  --dry-run

Output to different file

ruby ${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb  -o 

Example invocations

• "Fix entity references in modules/getting_started/"
• "Replace HTML entities in the assemblies folder"
• "Run entity reference transformation on all AsciiDoc files"
• "Fix the entities in modules/deploying-with-podman.adoc"
• "Preview entity changes in modules/ --dry-run"

Behavior notes

• Preserves supported entities: &, <, >, ', and " are left unchanged
• Skips code blocks: Entities inside code blocks (---- or ....) are not replaced unless the block has subs="replacements" or subs="normal"
• Skips comments: Entities inside comment blocks (////) and single-line comments (//) are not replaced
• Reports unknowns: Unknown entities are reported but not modified

Output format

: Replaced N entity reference(s)
  Unknown entities (not replaced):
    Line X: &unknown;

Extension location

The Ruby script is located at: ${CLAUDE_SKILL_DIR}/scripts/entity_reference.rb

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhatt-rh
• Source: abhatt-rh/redhat-docs-agent-tools
• License: Apache-2.0
• Homepage: https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.