Alias URLs

Aliases extend DITA's organizational capabilities by creating site-integrated representations of DITA content that can participate in broader website navigation while maintaining their connection to the underlying DITA structure.

Aliases represent DITA content in the Site Tree. Aliases can integrate with site content and be included in navigations and links when published to a DSS. Unlike standard site links, alias links display through the Site Tree structure and link to published, normalized DITA output files.

When administrators enable alias URL pathing for the publishing target, the DITA publishing pipeline creates user-friendly URLs for aliased DITA topics based on their Site Tree location. Each aliased DITA topic receives a URL, and topics referenced in multiple DITA maps receive multiple alias URLs.

Example alias structure in the CMS Site Tree:

/Content Store/Home/Knowledge Base/User Guide/Get Started/Dashboard

In this example, Knowledge Base is the parent page of the alias structure. User Guide is the aliased root DITA map and Get Started and Dashboard are aliased DITA topics part of the User Guide map structure. The Site Tree displays the DITA icon and a document information type tag (DITA map, topic, concept, task, etc.) next to each alias name.

The published URL for the Dashboard DITA topic displays similarly to:

https://mysite.com/KnowledgeBase/GetStarted/Dashboard

URL generation varies based on the publishing target's structured URL settings.

Key Points

Alias URL generation key characteristics:

• Creates user-friendly URLs based on alias location in the Site Tree.
• Uses alias names in paths, similar to standard site page URLs (the CMS may omit or replace special characters in the URL).
• Excludes .dita file extension from URLs.
• DITA asset types, elements, and attributes can affect alias generation and names, impacting the generated URL.

UrlMap.xml

The CMS constructs and tracks site page URLs using UrlMap.xml as part of the published content set in the replication target directory. Treating DITA alias URLs similarly to site page URLs, the CMS also uses UrlMap.xml to construct and track alias URLs.

UrlMap.xml contains all generated site URLs, including all alias URLs. System administrators can review UrlMap.xml in the replication target's settings folder. When publishing aliased DITA assets with alias URL pathing enabled, the CMS always generates alias URL entries in this file.

This information can help with troubleshooting, maintenance, and customization work involving alias URLs on the DSS server.

Example alias URL entry in UrlMap.xml:

<Page ID="da/31" ContentID="a/42" Path="KnowledgeBase/GetStarted/Dashboard" 
DITAFilePath="_DITA_Normalized\ditaRoot\user-guide\concepts\dashboard.dita" 
Schema="_alias_" />

Alias entry attributes include:

DITA Asset URLs

Asset-based URLs reflect the authoring organization of assets rather than Site Tree organization, providing direct mapping between source files and their published representations.

DITA asset URLs are based on DITA asset location in the CMS Assets Manager. The CMS automatically generates these URLs for all published normalized DITA content, regardless of aliasing.

When administrators disable the Enable alias URL pathing setting or when published DITA content lacks aliases, the DITA publishing pipeline uses DITA asset URLs instead of alias URLs. DITA asset URLs combine the administrator-specified partial match string with the file location under the DITA root folder in the Assets Manager. DITA post-publish processor settings defines the partial match string for the publishing target.

Example where the DITA asset dashboard.dita resides at this Asset Tree path:

/ditaRoot/user-guide-docs/topics/concepts/dashboard.dita

In this example, ditaRoot serves as the DITA Root Folder.

The CMS generates this DITA asset URL for dashboard.dita:

https://mysite.com/_dita_/user-guide-docs/topics/concepts/dashboard.dita

Key Points

DITA asset URL key characteristics:

• The partial match string (_dita_ in this example) displays directly after the site domain URL.

• The system appends the folder path from directly under the DITA root folder in the Assets Manager after the partial string. The DITA root folder itself does not display in the DITA asset URL. The DITA file name and .dita extension display in the URL path.

• You can navigate to normalized DITA content on the DSS using the DITA asset ID (/a/[id]) after publishing.

Advanced DITA Reuse URLs

DITA's reuse capabilities are fundamental to its architecture and include several mechanisms: content references (@conref), key references (@keyref), conditional processing (filtering), and various forms of linking and relationship management. These features enable content sharing, repurposing, and customization across publications while maintaining source integrity.

Content reuse in DITA creates complex relationships between source content and published output. Topics in DITA are designed to be context-independent, allowing multiple maps to reference the same topic. This reuse capability is advantageous to DITA's content strategy but creates challenges for DITA alias and asset URL generation because the same topic may require different URLs depending on its context within different maps or publication hierarchies.

These reuse relationships affect URL generation management and content variation creation.

Variant Files

DITA reuse features can generate multiple variations of the same source file in normalized output with different names and locations than the original file in the Assets Manager.

Variants are multiple iterations of the same source topic created through DITA reuse strategies that produce different filenames in the output directory. These DITA reuse mechanisms generate variant files:

• Conditional processing with <ditavalref>: When a topic is processed with different DITAVAL conditions via <ditavalref> elements, each condition set creates a variant. Also, topics that undergo branch-specific conditional processing create variants for each branch.
• Key scoping with @keyscope: When the same topic is referenced in different key scopes, each scope can create a variant with scope-specific key resolutions.
• Copy-to operations with @copy-to: The @copy-to attribute creates additional copies of topics with different file names.
• Chunk processing with @chunk: When chunk operations split or combine topics, they can create variant files with modified content or structure.

These DITA reuse strategies generate multiple variations of the same DITA source file in the normalized output with different names and locations than the original source file from the Assets Manager. The DITA-OT automatically appends a dash and number (-1, -2, etc.) to variant file names that do not already have a specified name. For example, overview.dita variations become overview-1.dita, overview-2.dita, etc.

Top-level Map Conditional Processing

Users can apply DITAVALs to maps through the Configure DITA Publishing dialog or <ditavalref> elements.

When users apply DITAVALs to the top-level (root) map that will be published, this creates conditionally processed files in different locations than standard normalized DITA content. These conditionally processed DITA assets use modified URLs instead of standard alias and asset URLs. Append ditaval and the DITAVAL file name (without the .ditaval extension) to the end of standard DITA alias or asset URLs.

Append this path format to Alias URLs or Asset URLs:

/_ditaval_/[name-of-DITAVAL-file]

For example, if applying beginner.ditaval to the map through the Configure DITA Publishing dialog, the DITA alias URL generated for the conditionally processed DITA content becomes:

https://mysite.com/KnowledgeBase/GetStarted/Dashboard/_ditaval_/beginner

The corresponding DITA asset URL becomes:

https://mysite.com/_dita_/base/cms/topics/concept/overview.dita/_ditaval_/beginner

See DITA-OT and Output Locations for details about the location of these conditionally processed normalized DITA files that are in a separate path from standard normalized DITA content.

Key Scoped Alias Names

When users apply @keyref (or @conref, @conkeyref) to the aliased DITA asset's <title> element, this can display in the alias URL path, depending on your CMS version.

Copy-to Files

The @copy-to attribute creates additional copies of topics with different file names. If the @copy-to attribute only specifies the file name without a path, the DITA-OT generates the @copy-to file in the folder of the DITA map, the map that specifies the @copy-to.

Chunked Files

DITA chunking either merges topic contents into one output file or splits them into separate files. When using @chunk="to-content", this attribute value merges content from the child topics into the parent topic or map.