Home CMS Documentation Home CMS 10 DITA Processing Pipeline Initial DITA Configuration DITA Administration DITA Map Manager DITA Aliases Alias References DITA Alias Attributes

DITA Alias Attributes

DITA attributes control how the CMS generates aliases for your content structure. Understanding these attributes helps you plan effective alias strategies and anticipate how your content will display in the Site Tree and URL paths.

See OASIS DITA Version 1.3 Specification for details about DITA attributes.

Important

To use alias URL pathing, select the Enable alias URL pathing checkbox on the publishing target.
DITA asset types and elements in your DITA assets may affect alias generation.

Linking Attributes

Linking attributes determine which DITA assets receive aliases and how they connect within your content structure.

@href

The CMS generates aliases only for DITA assets referenced by @href attributes in map elements. The CMS requires DITA assets to be referenced through @href to receive aliases.

@scope

The @scope attribute determines whether referenced DITA assets receive aliases based on their relationship to the map.

@scope="local" (default): The CMS generates aliases.
@scope="external": The CMS does not generate aliases.
@scope="peer": The CMS does not generate aliases.

Map Attributes

Map attributes control how the CMS names aliases and processes content during publishing.

@navtitle

The @navtitle attribute provides alternative titles for navigation and alias naming.

Version Notes: CMS 10.6.492 vs. CMS 10.6.308–10.6.378

CMS 10.6.492: The alias name uses the <title> value instead of the @navtitle or <navtitle> values.

For <topichead>elements, the CMS uses @navtitle for alias names. <topichead> alias generation requires both @navtitle and @id values.

CMS 10.6.308–10.6.378: If the map element referencing the DITA asset contains @locktitle="yes" and a @navtitle value, the CMS uses the @navtitle value for the alias name. Otherwise, the CMS uses the topic's <title> value.

For <topichead> and <topicset>, the CMS uses @navtitle for alias names.

@locktitle

This attribute controls whether navigation titles override asset titles in alias naming.

Version Notes: CMS 10.6.308–10.6.378

If the map element referencing the DITA asset contains @locktitle="yes" and a @navtitle value, the CMS uses the @navtitle value for the alias name. Otherwise, the CMS uses the topic's <title> value.

@chunk

This attribute controls content chunking behavior and alias generation for chunked content. DITA chunking determines whether the publishing process merges reusable topics into one output file or preserves them as individual files. Chunking values such as to-content and select-topic direct how the DITA publishing pipeline assembles the final output.

Version Notes: CMS 10.6.492

If the map element referencing the DITA asset contains @chunk="to-content" and @copy-to, the CMS generates an alias only for the chunked element, not its child elements. The DITA publishing pipeline processing merges the child element content into the chunked output file.

Requirements for chunking aliased content:

The CMS requires the element to have both @chunk="to-content" and @copy-to.
The @copy-to value is used to create a URL entry for the chunked output file. After the DITA pipeline publish, the default URL uses the @copy-to value in the aliased DITA asset's URL Management properties.
You can only chunk maps via <mapref> elements (not <map> or <bookmap> elements).

@copy-to

This attribute creates a duplicate output file with a different filename for copied or chunked content and URL generation control.

You can use @copy-to to display a topic in multiple navigation locations. The output topics will have different labels and metadata without linking to the same physical output file.

The DITA-OT generates the duplicate file in the output directory relative to the map location containing the topic reference with @copy-to. Use @copy-to to specify the filename, extension, and path for the duplicate file in the output directory.

For example, if your DITA map resides in the root folder and the map contains <topicref href="topics/install.dita" copy-to="windows/install-windows.dita"> and <topicref href="topics/install.dita" copy-to="macOS/install-macOS.dita">, the DITA-OT generates the specified subfolders in the root folder of the output directory and creates the duplicate files in those subfolders.

Version Notes: CMS 10.6.492

Important:

For links and images to resolve within the rendered normalized DITA topic, the CMS and DSS require the generated @copy-to output file to reside in the same folder as its original DITA source file.
When chunking content with the CMS DITA publishing pipeline, the pipeline requires both @chunk="to-content" and @copy-to for alias generation.
The DITA publishing pipeline uses @copy-to to generate a DSS asset map entry for the output file copy. After publishing, if only one @copy-to is applied to the topic reference, the value displays as the default URL in the aliased asset's URL Management properties.
If @copy-to values are applied to multiple <topicref> elements that reference the same topic, DSS customization will required. The Default URL in Properties > URL Management reflects only the last processed @copy-to path value.
See Normalized DITA URLs for details.

@processing-role

This attribute controls whether elements and their children are included in alias generation and navigation.

@processing-role="normal" (default): The CMS generates aliases.
@processing-role="resource-only": The CMS does not generate aliases for the element or its children.

Apply @processing-role="resource-only" to content you want processed during DITA pipeline processing but not included in alias generation.

Complex Attributes

Complex attributes affect alias naming when DITA content contains references to keys or other reused content.

@keyref

The CMS generates aliases for DITA assets referenced by @href attributes in map elements, not @keyref attributes.

Version Notes: CMS 10.6.492

When an asset's <title> contains nested elements with @keyref attributes:

The CMS displays a placeholder with the key name and icon in the alias name. For example: [🔑 product-a]
After publishing and replication, the @keyref resolves and the actual content renders in the alias name and URL on the DSS.

@conref

This attribute affects alias naming when DITA titles contain content references.

Version Notes: CMS 10.6.492

When an asset's <title> contains nested elements with @conref attributes:

The alias name displays a placeholder with square brackets, the name of the element referencing the content, and the receipt icon. For example: [🧾 ph]
After publishing and replication, the @conref resolves and the referenced content appears in the alias name on the DSS.

@conkeyref

This attribute affects alias naming when DITA titles contain content key references.

Version Notes: CMS 10.6.492

When an asset's <title> contains nested elements with @conkeyref attributes:

The CMS displays a placeholder with the key name and icon in the alias name. For example: [🔑 product-a]/permissions
After publishing and replication, the @conkeyref resolves and the referenced content appears in the alias name on the DSS.