Publishing DITA‑Based Technical Content to Adobe Experience Manager Sites
XML Documentation for Adobe Experience Manager is now Adobe Experience Manager Guides, a Cloud Native Component Content Management System. Learn more about AEM Guides here.
The XML Documentation for Adobe Experience Manager has several features and countless benefits to support a powerful component content management system within Adobe Experience Manager (AEM). This solution enables AEM to handle Darwin Information Typing Architecture-based (DITA-based) content creation and delivery seamlessly, providing a single CMS to manage marketing and technical content all under one platform.
Out of the multitude of features supported by this solution, the one-touch experience of publishing all of the technical content to multiple publishing channels is widely sought out by technical authors and publishers. The features encompassed with this best-in-class functionality of the XML Solution, referred to above as XML Documentation for Adobe Experience Manager, enable content-authors to deliver rich content experiences to end-users.
These publishing features are enabled by the widely-used open source publishing engine, the DITA Open Toolkit (DITA-OT). The XML Solution is shipped out-of-the-box (OOTB) with a default DITA-OT plug-in and can publish the DITA-based content in the most popular formats–AEM Sites, PDF, HTML5, and EPUB.
In this blog, we’ll briefly review publishing to one of the above formats (AEM Sites) and take you through some of the steps and configurations needed to customize the XML Solution to support this publishing.
Configuring DITA Profiles / DITA-OT Profiles
The XML Solution solution comes with a pre-configured DITA-OT profile that contains the configurations for the default DITA templates and the default DITA-OT package to use for editing and publishing content. DITA provides architectural capabilities to create modular, reusable content to allow for control, speed, and streamlined processes across teams.
However, most organizations use some sort of specialized form of DITA for creating and editing their documents. These organizations also use their own custom DITA-OT plug-in (possibly integrated with custom processors to render their specialized DITA elements properly). So, if your organization follows such practices, the first step in configuring the XML Solution for publishing AEM Sites is to configure the DITA-OT profile(s).
First, AEM needs to be able to access the custom DITA-OT plug-in and DITA specializations that your organization uses:
- The custom DITA-OT plug-in and any DITA specializations (i.e. specialized DTDs and XSDs) are uploaded into the AEM repository (or saved on the server).
- For DITA specializations, the DTD & XSD details must also be specified in the catalog.xml.
The Default Profile information is displayed on the Profiles page (Tools > XML Documentation > DITA Profiles). While the default profile cannot be deleted, it can be edited or duplicated to create a new profile:
- The default DITA profile is selected and “Edit Profile” is clicked.
- The “
AEM DITA-OT Zip Path” is modified to point to the custom DITA-OT package in the AEM repository (the path can also point to the Server path). - In the Schemas > Catalog section, the paths to the catalog.xml containing the DITA specialization details are added.
Now, the default DITA-OT profile is configured to use the custom plug-in. If your organization has a need to use different customizations for various types of documents, it’s better to organize such documents in a folder hierarchy. Then, multiple DITA-OT profiles (each configured differently) can be created and assigned (using “Assigned Path” config) to one or more DAM folder paths respectively.
Create DITA Element Mapping
The next step is to create an element mapping file to map the DITA elements to AEM content components. Again, XML Solution is shipped with a set of OOTB content components (located under: "/libs/fmdita/components/dita”) and a predefined element mapping file (located at: “/libs/fmdita/config/elementmapping.xml”).
If the DITA elements are to be mapped to custom AEM components, this mapping file can be overridden by a custom mapping file (preferably by creating an overlay in the apps folder). This custom mapping file doesn’t need to replicate the entire file. Instead, if only a few elements need to be mapped into custom AEM components, only these elements can be overridden in this custom mapping file.
Finally, this custom mapping file is specified in the “Override Element Mapping” setting in the “com.adobe.fmdita.config.ConfigManager” configuration for it to take effect.
Design Templates
Now that each of the DITA elements are mapped to a corresponding AEM content component, the next step is to define the high-level AEM templates, the page components referenced by these templates, their node structures, and a few custom property names to be used in the AEM Page Properties.
When a DITA-based document is desired to be published into an AEM Site, there are three types of AEM pages to be considered:
- Landing Page template (Index page containing a Table of Contents)
- Topic Page template (Topic Pages containing each topic of the document)
- Search Page template (Search Page to search for content inside a single document)
The XML Solution ships with a set of predefined AEM page templates (located under: “/libs/fmdita/templates/default/cqtemplates”). You can also use your custom AEM page templates for AEM Site generation.
Combining these AEM template paths, a set of JCR Node paths (node paths relative to the AEM page node generated for the document) and a few property names (property names in the page component node) will provide a single definition/configuration (referred to as a Design Template). Creating/updating the Design Template(s) is a prerequisite for proper AEM Sites output generation. Again, the XML Solution ships with a predefined Design Template (located at: “/libs/fmdita/config/templates/default”).
This Design Template node can be used as a base and if needed, multiple Design Templates can be created, each one representing a different type of document, example: Spec Sheet, User Guide, etc.
AEM Site Output Preset
The next step is to configure the output preset for an AEM Site. An output preset represents a customized output format in which the content is to be published and contains the configurations used in generating the DITA documents in said format. And, for AEM Site format, some of the configurations that are commonly used are:
| Setting Name | A title for the preset, say “User Guides,” “Reference Guides,” etc. |
| Design | The node path of the Design Template to be used |
| Destination Path | The parent content path where the pages will be created |
| Site Name | The site name i.e. the node name for the Landing Page created for the Document |
| Existing Output Pages | Overwrite Content: To not delete the pages but only overwrite content present under the content and head nodes of the page; Enables blended publishing (see below) Delete and Create: To force delete any existing pages |
| Delete Orphan Site Pages | To remove all orphan pages from the published AEM Site; This option has some caveats as it does not remove any content from the Published Child Map that has been removed since the document has been last published. |
| Run Post Generation Workflow | To select a workflow process to be executed after completion of the output generation workflow. |
Blended Publishing
The native DITA support in AEM enriches AEM sites to blend both technical content authored in DITA by technical authors (authored either in their familiar DITA-based authoring tool or using the powerful web-based editor of the XML Solution) and marketing content (authored natively inside AEM using AEM components).
This integration empowers the technical team to maintain their content and assets within AEM and even reuse the existing assets, templates, and styles of the marketing team, allowing them to deliver their technical content with the same look and feel as that of the marketing content.
This blended publishing feature can be enabled by defining the options “topicContentNode” and “topicHeadNode” in the Design Template and by selecting the “Overwrite Content” option in the output preset settings.
Folder Profiles
Folder Profiles can be created in the Folder Profiles page (Tools > XML Documentation > Folder Profiles). A single Folder Profile associates single or multiple folder paths to a set of authoring templates (i.e. DITA topic and DITA map templates), a set of output presets definitions (presets that are enabled for DITAMAPs for output generation) and a set of conditional attributes. The criteria that are defined in this Folder Profile will then be applied to any and all DITA files that are placed under the associated folder(s).
Usually, most organizations have different document type categories (User Guides, Reference Guides, Spec Sheets, etc.). Along with other content hierarchy recommendations put forth by the Adobe team in their Best Practices documentation, it is also recommended that a folder is created for each of these document categories and all the DITA files for the DITA-based documents belonging to a type (or at least the root DITAMAP file of these DITA-based documents) are placed inside the respective folder.
Organization of content in such a hierarchical nature will then enable the authors to associate a Folder Profile to each document type category folder, avoiding the need to create the same output preset settings multiple times.
A Better User Experience
With these settings, the XML Solution is now prime for the activity of publishing DITA-based documents into AEM Sites. A publishing specialist can also leverage the Map Collection dashboard of the XML Solution to assemble all different types of documents to a single unit as a collection and perform these publishing activities in batches in a much more efficient manner. The publishers can also view the output generation progress from the publishing dashboard.
This setup supports the technical team to dynamically publish large volumes of content into AEM Sites effortlessly and at a high velocity. The user experience between marketing and technical content is no longer disconnected and a blended content leads to a smoother end-user flow between the two. This further leads to better Analytics tracking to understand the customer journeys and personalize their experiences.
References:
Adobe. (2019). Adobe Enterprise-Class CCMS-Overview. Retrieved from
https://www.adobe.com/products/xml-documentation-for-experience-manager.html
Adobe. (2019). XML Documentation for Adobe Experience Manager 6.5, 6.4, and 6.3 User Guide. Retrieved from
https://helpx.adobe.com/content/dam/help/en/xml-documentation-solution/3-5/XML-Documentation-for-Adobe-Experience-Manager_6-5_6-4_6-3_User-Guide_EN.pdf
Adobe. (2019). XML Documentation for Adobe Experience Manager Installation and Configuration Guide. Retrieved from
https://helpx.adobe.com/content/dam/help/en/xml-documentation-solution/3-5/XML-Documentation-for-Adobe-Experience-Manager_Installation-Configuration-Guide_EN.pdf
Adobe. (2019). Best practices for working with XML Documentation for Adobe Experience Manager. Retrieved from
https://helpx.adobe.com/content/dam/help/en/xml-documentation-solution/3-5/XML-Documentation-for-Adobe-Experience-Manager_Best-Practices_EN.pdf
