Configure output generation settings id181AI0B0E30

AEM Guides comes with a lot of configuration options for you to customize the output generation process. This topic covers all configurations and customizations that would help you set up your output generation process.

Configure the Baseline tab on the DITA map dashboard id223MD0D0YRM

To hide the Baseline tab on the DITA map dashboard, perform the following steps:

Configure blended publishing within an existing AEM Site id1691I0V0MGR

If you have an AEM Site that contains DITA content, you can configure your AEM Site output to publish DITA content to a predefined location within your site. For example, in the following screenshot of an AEM Site page, the ditacontent node is reserved to store DITA content:

The remaining nodes in the page are authored directly from the AEM Site editor. Configuring the publish setting to publish DITA content to a predefined location ensures that none of your existing non-DITA content gets modified by the AEM Guides publishing process.

You need to perform the following configurations on your existing site to allow publishing of DITA content to a predefined node:

Perform the following steps to configure your existing site’s template properties:

Next time when you publish any DITA content using your site’s template configurations, the content gets published into the nodes specified in the topicContentNode and topicHeadNode properties.

Customize AEM Site output id166TG0B30WR

The AEM Guides supports creating outputs in following formats:

For the AEM Site output, you can assign different design templates with different output tasks. These design templates can render the DITA content in different layouts. For example, you could specify different design templates for internal and external audiences.

You can also use customized DITA Open Toolkit (DITA-OT) plug-ins with the AEM Guides. You can upload these custom DITA-OT plug-ins to generate PDF output in a specific way.

Customize design template for generating output customize_xml-add-on

The AEM Guides uses a set of predefined design templates to generate AEM Site output. You can customize the AEM Guides design templates to generate the output that conforms to your corporate branding. A design template is a collection of various styles (CSS), scripts (both server- and client-side), resources (images, logos, and other assets), and JCR nodes that tie all these resources together. A design template can be as simple as a single server-side script with just a couple of JCR nodes, or a complex combination of styles, resources, and JCR nodes. Design templates are used by AEM Guides publishing subsystem while generating AEM Site output and they control the structure, look and feel of the generated output.

There is no restriction as to where the design template resources should be located on the server, but they are usually logically organized as per their function. For example, the default template has all its JavaScript and CSS files stored under /etc/designs/fmdita/clientlibs/siteoutput/default folder. Wherever these files are located, they are linked together by a collection of JCR nodes. Together, these JCR nodes and the files constitute the whole design template.

The default design template shipped with the AEM Guides allows you to customize the landing, topic, and search page components. You can make a copy of the default design and the corresponding reference templates and specify different components to generate the desired output.

Perform the following steps to specify your own design template to use for AEM Site output generation:

For more information, see Creating your first Adobe Experience Manager website and The Basics of developing your own website on AEM.

Use document title for generating AEM site output

When generating AEM Site output, the way URLs are generated play an important role in the discoverability of your content. In case you are using UUID-based file names, generating URLs based on UUID of your files would not be search friendly. As an Administrator or Publisher, you have the control on how you want to generate the URLs for your AEM Site output. AEM Guides gives you a configuration through which you can choose to generate the URLs of AEM Site output using the file’s title rather than the UUID-based file names. By default, for UUID-based file systems, this option is turned ON. This implied that when you generate AEM Site output for UUID-based file systems, the file’s titles are used to generate the URLs and not the UUIDs of the files.

Use the instructions given in Configuration overrides to create the configuration file. In the configuration file, provide the following (property) details to configure the URLs generation in AEM Site output:

Configure the URL of the AEM Site output to use the document title

You can use the document titles in the URL of the AEM Site output. If the filename doesn’t exist or contains all special characters, you can configure the system to replace the special characters with a separator in the URL of the AEM Site output. You can also configure it to replace them with the first child topic’s name.

To configure the page names, perform the following steps:

For example, if the @navtitle in <topichead> has all special characters and you set the aemsite.pagetitle property to true, then by default, it uses a separator. If you set the nodename.systemDefinedPageName property to true, it shows the first child topic’s name.

Configure filename sanitization rules for creating topics and publishing AEM Site output id2164D0KD0XA

As an administrator, you can define a list of valid special characters allowed in filenames, which eventually form the URL of an AEM Site output. In earlier releases, users were allowed to define filenames containing special characters such as @, $, >, and more. These special characters resulted in encoded URL on generation of AEM Site pages.

Starting with 3.8 release, configurations have been added to define a list of special characters that are allowed in the filenames. By default, the valid filename configuration contains “a-z A-Z 0-9 - _”. This implies that while creating a file, you can have any special character in the file’s title, but internally it will get replaced with a hyphen (-) in the filename. For example, you can have the file’s title as Introduction 1 or Introduction@1, the corresponding filename generated for both these cases would be Introduction-1.

When you define a list of valid characters, remember that these characters “*/:[\]|#%{}?&<>"/+” and a space will always be replaced with a hyphen (-).

Use the instructions given in Configuration overrides to create the configuration file. In the configuration file, provide the following (property) details to configure the valid special characters in filenames and AEM Site output:

You can also configure the other properties such as use lower case in filenames, separator to handle invalid characters, and maximum number of characters allowed in the filenames. To configure these properties, add the following key value pairs in the configuration file:

Configure flattening of AEM Site node structure

When you generate AEM Site output, a node for every element in the topics is created internally. For a DITA map with thousands of topics, this node structure can become too deep. This type of deeply nested node structure can have performance issues for larger sites. The following snapshot displays deeply nested node structure for an AEM Site output:

In the above snapshot, notice that there is a node is created for every p element and its subsequent sub-elements and a similar structure is created for every other element used in the topic.

AEM Guides allows you to configure how AEM Site output’s node structure is created internally. You can flatten the node structure at specified elements, which means that you can define an element which will be considered as the main element and all sub-elements within it will be merged with the main element. For example, if you decide to flatten the p element, then any element appearing within the p element will get merged with the main p element. A separate note would not be created for any sub-element within the p element. The following snapshot displays the node structure flattened at p element:

To flatten AEM Site node structure, perform the following steps:

Now, when you generate the AEM Site output, the nodes within the p element are flattened and stored within the p element itself. You can find the new flattening properties for the p element in CRXDE.

Search a string within the content in AEM Site output

By default, you can search for a string in the titles only within the AEM Site output. You can configure the system to search for a string both in the titles and also the content or the body of the AEM Site output.

To enable the search, you should configure the flattening of AEM Site node structure.

CAUTION:

You can search up to 1MB of flattened content. For example, in the previous screenshot, you can search if the content under <p> tag is <= 1Mb.

Prevent flattening of AEM Site node structure

Similar to specifying the node to flatten in AEM Site output, you can also specify an element that you want to exclude from this configuration. For example, if you want to flatten nodes at body element, but you do not want any table element within body to flatten, then you can add the exclude property within the table element’s definition.

To exclude the table element from flattening, add the following property to the table element’s definition:

<preventancestorflattening>true|false</preventancestorflattening>

Configure the versioning for deleted pages in AEM Site output

When you generate AEM Site output with Delete and Create option selected for the Existing Output Pages setting, a version is created for the page(s) being deleted. You can configure the system to stop the creation of a version before deletion.

Perform the following steps to stop the creation of a version for the page(s) being deleted:

Setup custom rewriter with Experience Manager Guides custom-rewriter

Experience Manager Guides has a custom sling rewriter module for handling the links generated in case of cross-maps (links between the topics of two different maps). This rewriter configuration is installed at the following path:
/apps/fmdita/config/rewriter/fmdita-crossmap-link-patcher.

If you have another custom sling rewriter in your codebase, use an 'order' value greater than 50, as Experience Manager Guides sling rewriter uses 'order' 50. To override this, you need a value >50 . For more details, view Output Rewriting Pipelines.

Use metadata in publishing output through DITA-OT id191LF0U0TY4

AEM Guides provides a way to pass custom metadata while publishing output using DITA-OT. As an administrator and a Publisher you would need to perform the following tasks to configure and use custom metadata in the published output:

To add the required metadata in the system, perform the following steps:

The new parameter now shows up on the Properties page for all DITA maps.

Next, you need to make the custom metadata available in the DITA map console. Perform the following steps to make the custom metadata available on the DITA map dash board:

Now the custom metadata will show up in the DITA map console’s Properties drop-down list.

Lastly, as a Publisher, you need to include the custom metadata in the published output. To process the custom metadata while generating the output, perform the following steps:

The selected properties/metadata are passed on to the publishing process and are made available in the final output.

Validate metadata passing to the DITA-OT for processing

In order to validate the metadata values passed to the DITA-OT, local environment using a cloud ready jar can be used. Since we can’t access local file system on cloud, only way to validate metadata file is via cloud ready jar.

Customize DITA element mapping with AEM components id1679J600HEL

DITA elements in the AEM Guides are mapped to their corresponding AEM components. AEM Guides uses this mapping in workflows such as publishing and review to convert DITA element to a corresponding AEM component. The mapping is defined in the elementmapping.xml file, which can be accessed using the package manager.

You may use the predefined DITA element mappings, or you can map DITA elements to your custom AEM components. To use your custom AEM components, you need to understand the structure of the elementmapping.xml file.

elementmapping.xml structure

A high-level overview of the elementmapping.xml structure is explained below:

DITA element schema

Following is an example of the DITA element schema in elementmapping.xml file:

<ditaelement>
    <name>element_name</name>
    <class>element_class</class>
    <componentpath>fmdita/components/dita/component_name</componentpath>
    <type>COMPOSITE|STANDALONE</type>
    <attributeprop>propname_a</attributeprop>
    <textprop>propname_t</textprop>
    <xmlprop>propname_x</xmlprop>
    <xpath>xpath expression string</xpath>
    <target>head|para</target>
    <wrapelement>div</wrapelement>
    <wrapclass>class_name</wrapclass>
    <attributemap>
        <attribute from="attrname"         to="propname"         ispath="true|false"         rel="source|target" />
    </attributemap>
    <skip>true|false</skip>
</ditaelement>

The following table describes the elements in the DITA element schema:

Additional notes

Customize DITA map console id188HC08M0CZ

AEM Guides gives you the flexibility of extending the capabilities of the DITA map console. For example, if you have a set of reports that are different from what is available in the AEM Guides, you can add such reports to the map console. To customize the map console, you need to create an AEM Client Library (or ClientLib) that will contain the code to perform the functionality that you need.

AEM Guides provides the apps.fmdita.dashboard-extn category for customizing map console. Whenever the map console is loaded, the functionality created under the apps.fmdita.dashboard-extn category gets executed and loaded.

Handle image rendition during output generation id177BF0G0VY4

AEM comes with a set of default workflows and media handles to process assets. In AEM, there are pre-defined workflows to handle asset processing for the most common MIME types. Typically, for every image that you upload, AEM creates multiple renditions of the same in binary format. These renditions may be of different size, with a different resolution, with an added watermark, or some other changed characteristic. For more information about how AEM handles assets, see Processing Assets Using Media Handlers and Workflows in AEM documentation.

AEM Guides allows you to configure which image rendition to use at the time of generating output for your documents. For example, you can choose from one of the default image renditions or create one and use the same to publish your documents. Image rendition mapping for publishing your documents is stored in the /libs/fmdita/config/ **renditionmap.xml** file. A snippet of renditionmap.xml file is as follows:

<renditionmap>
   <mapelement>
      <mimetype>image/png</mimetype>
      <rendition output="AEMSITE">cq5dam.web.1280.1280.jpeg</rendition>
      <rendition output="PDF">original</rendition>
      <rendition output="HTML5">cq5dam.web.1280.1280.jpeg</rendition>
      <rendition output="EPUB">cq5dam.web.1280.1280.jpeg</rendition>
      <rendition output="CUSTOM">cq5dam.web.1280.1280.jpeg</rendition>
   </mapelement>
...
</renditionmap>

The mimetype element specifies the MIME type of the file format. The rendition output element specifies the type of output format and the name of rendition (for example, cq5dam.web.1280.1280.jpeg) that should be used for publishing the specified output. You can specify the image renditions to use for all supported output formats - AEMSITE, PDF, HTML5, EPUB, and CUSTOM.

If the specified rendition is not present, then AEM Guides publishing process first looks for the web rendition of the given image. If even the web rendition is not found, then the original rendition of the image is used.

Configure auto-purging period for output history id19AAI070V8Q

When you generate an output, the output gets created along with the output logs. For large DITA maps, these logs can take a large amount of space in your repository. By default, the logs are stored at the following location in the repository:

/var/dxml/metadata/outputHistory

Over a period of time, the collective size of all log files could run into GBs. AEM Guides allows you to configure a time period to keep these log files in the repository. After the specified time period, the logs along with output generation history are deleted from the repository.

Configuring the history purging feature impacts the output generation for all DITA maps in the repository. In the Outputs tab of a DITA map, the history is purged after the specified number of days and at the time specified in the setting.

Use the instructions given in Configuration overrides to create the configuration file. In the configuration file, provide the following (property) details to set a day and time to purge output history and logs:

Change the recently generated outputs list limit id1679JH0H0O2

You can change the maximum number of generated outputs that are displayed in the Outputs tab for a DITA map.

Use the instructions given in Configuration overrides to create the configuration file. In the configuration file, provide the following (property) details to change the number of outputs to display in the list: