Quick Start

Prerequisites: Complete the basic DITA setup first. See Initial DITA Configuration for the complete setup workflow including Java installation, DITA root folder creation, DITA-OT installation, and publishing configuration.

To get DITA rendering working quickly, complete these essential steps:

1. Publish Rendering Stylesheet: Check in, mark for publish, and publish the dita-rendering.xsl stylesheet from stylesheets/_dita folder to the DSS (not required for DITA Preview).
2. Test Rendering: Upload or create DITA content in the designated DITA root folder, create aliases in Site Tree (optional), test in DITA Preview, then publish and test on DSS.

For detailed configuration steps and troubleshooting, see the Detailed Implementation Requirements section.

How Rendering Works

Ingeniux CMS renders DITA content through a three-stage process:

1. Normalization: The DITA-OT processes raw DITA files and resolves all references, keys, and content relationships to create normalized DITA XML.
2. Transformation: The CMS uses the dita-rendering.xsl stylesheet to transform normalized DITA into display-ready XML.
3. Display: ASP.NET views render the transformed XML for DITA Preview and DSS display.

The DITA Open Toolkit (DITA-OT) handles the normalization process, an XML-to-XML transformation. Normalization resolves DITA map references, keys, content references, and other elements to create fully expanded XML. This normalized DITA serves as the foundation for all rendering operations.

In typical Ingeniux CMS scenarios, the pipeline uses dita-rendering.xsl to transform normalized DITA content into display-ready XML for the desired output and presentation in DITA Preview on the DSS.

Developers can use standard MVC practices when rendering DITA content. ASP.NET views fit naturally within the Ingeniux CMS architecture and require no "retooling" by MVC developers because rendering XML content through views works the same as with any other XML document type in the CMS. The process of setting up a DSS server to display content remains consistent across content types.

DITA-OT Output Configuration

DITA rendering requires configuring the DITA-OT with a normalization plugin that processes DITA content and generates the normalized output used by Ingeniux CMS views and stylesheets. You can use the default normalization plugin provided with the DITA-OT or custom plugin that meets your requirements.

We recommend using the Ingeniux DITA 3.6.1 DITA-OT with its included DITA-OT normalization plugin. The Ingeniux DITA-OT includes beneficial fixes and enhancements.

Alternatively, you can install a custom DITA-OT or DITA normalization plugin, provided it meets development and rendering requirements.

DITA-OT Parameters

DITA-OT parameters contribute to controlling your DITA content display. Improper DITA content rendering may result from DITA-OT parameter settings.

For example, args.figurelink.style controls whether figure cross-references display titles, figure numbers, or both. args.rellinks determines which links display in output. Rendering issues may stem from DITA-OT parameter configurations rather than view or DITA rendering stylesheet code.

For details about configuration, see DITA-OT Parameters.

Rendering Schema

The rendering schema defines how normalized DITA content displays on the DSS and in DITA Preview. Ingeniux CMS includes a default DITA Detail schema that you can customize or replace.

You can develop and rename the default page schema to meet organizational needs, build upon the default page schema, or create a different custom page schema.

The DitaDetail.cshtml view serves as the core MVC view for rendering DITA content and comes included with the DSS project. This view specifically renders displays for the DITA Detail XML page type.

Like other MVC views for site pages, DitaDetail.cshtml requires modifications to render content properly.

By default, the Shared folder contains the view for the DITA Detail page type that renders DITA in the CMS. From this location, the view accesses your implementation's default controller. Any controller can access views in the Shared folder.

However, developers can place the view in a different location if the Shared folder is not preferable. If the view does not reside in the Shared folder, developers must move the default controller to a folder where the controller can access the view.

CMS 10.6.378+ Schema Localization

The DITA rendering schema defines the page type applied to published, normalized DITA output. This schema and its corresponding view render DITA content on the DSS and in DITA Preview, somewhat similar to site pages.

CMS 10.6.378 allows you to specify rendering schemas for localized DITA content in addition to the default rendering schema. This feature enables locale-based DITA rendering schema configuration, ensuring content wrappers align with the displayed DITA content's locale.

For each locale, create a copy of the default rendering schema, then modify the copy and associated view as needed. For example, navigation elements may require modification for locale-specific schemas. Alternatively, use completely different schemas. When creating these schemas, use distinct and recognizable names (e.g., DITA Detail fr-ca) to identify which schema applies to each locale.

For additional schema localization details, see Rendering Localized DITA Content.

Rendering Stylesheet

The CMS uses the dita-rendering.xsl stylesheet in the Assets Manager stylesheets/_dita folder to transform normalized DITA into display-ready XML that layers with an ASP.NET view to render DITA styles. You can preview the transformed output XML in the DITA asset's XML tab. This stylesheet is required for DSS Preview and the DSS. If you do not publish the dita-rendering.xsl to the DSS, errors will occur URLs for DITA. Content will not display on the DSS until you publish the stylesheet.

A stock dita-rendering.xsl is provided out of the box that you can check in, mark for publish, and publish. This stylesheet only provides basic functionality. However, you can check out and modify this stylesheet at any time to meet your DITA stylesheet requirements. Consider retaining a copy of the original stylesheet so you can refer back to it if customization changes cause errors.

For details about stylesheets, see Extensible Stylesheet Language Transform.

DITA Note Icon Assets

Stock icons are provided out the box for DITA <note> elements and are referenced in the stock dita-rendering.xsl. They are located in the CMS images_o/dita/icons asset folder. When published, these icons render for notes in the normalized DITA output.

Retain the stock icons, replace them, or modify dita-rendering.xsl to add your own <note> styling customizations.

Stock note icon assets include:

caution.png

Renders for <note type="caution" /> elements.

important.png

Renders for <note type="important" /> elements.

note.png

Renders for <note type="note" /> and <note /> elements.

tip.png

Renders for <note type="tip" /> elements.

warning.png

Renders for <note type="warning" /> elements.

ASP.NET Views

Create custom ASP.NET views to control how DITA content displays in DITA Preview and on the DSS. Views process the XML output from normalized DITA content and apply your preferred formatting and styles.

Follow standard ASP.NET MVC practices when developing views for DITA page types. The rendering process works identically to other XML content types in Ingeniux CMS.

For details, see Getting Started with ASP.NET MVC

Detailed Implementation Requirements

Prerequisites: Complete basic DITA setup first. See Initial DITA Configuration for DITA-OT installation, output format configuration, and publishing target setup.

For DITA rendering customization and implementation, follow these requirements:

1. Advanced Schema and Parameter Configuration
   1. Modify the default DITA rendering schema and create custom rendering schemas for locales as needed, using descriptive names (e.g., DITA Detail fr-ca) for the schemas.
      Note

      You can copy the default DITA rendering schema and make changes to the copies to address the needs of each locale if needed.
   2. Configure DITA-OT parameters such as args.figurelink.style for figure cross-reference display and args.rellinks for link output control in Administration > DITA > DITA-OT Parameters.
2. Stylesheet Management and Customization
   1. Locate and evaluate the stock dita-rendering.xsl stylesheet in stylesheets/_dita folder.
      Note

      Consider saving a backup copy of original stylesheet before making customizations.
   2. Implement stylesheet check-in, mark for publish, and publish workflow to ensure DSS availability and stylesheet accuracy.
   3. Customize the stylesheet as needed to meet organizational styling requirements while maintaining compatibility.
3. ASP.NET View Development and Deployment
   • Verify the views (e.g., DitaDetail.cshtml) corresponding with DITA rendering schemas exist and are properly configured in the DSS and DSS Preview projects.
   • Ensure view accessibility from Shared folder or configure controller placement for proper view access.
   • Develop custom view modifications to achieve desired content formatting and styling.
4. Testing and Validation
   • Create or upload a comprehensive test DITA content including maps, topics, and various element types to the designated DITA Root folder.
   • Optional: Generate aliases in Site Tree and verify proper content association
   • Validate rendering in the DITA Preview and XML tabs for immediate feedback.
   • Perform end-to-end testing by publishing DITA content and verifying DSS display.
   • Test parameter configurations to ensure proper content display and troubleshoot rendering issues.
   • Test view rendering with various DITA content types to ensure compatibility.
   • Document any rendering issues and resolution steps for future reference.