The chunk attribute

The chunk attribute can control the way output files are generated during the publishing process. Most chunk attribute values apply only to composite topics, which should be avoided. The to-content value is used to generate a single output topic from multiple DITA source topics.

The ditamap's topicref element includes a chunk attribute that can be used to aggregate source DITA topics during processing to a deliverable document.

Setting the chunk attribute effectively overrides the default processing of the publishing tool. As well as specifying that multiple DITA topics be generated as single output topics, the chunk attribute can also be used to specify that single DITA topics be split on output into multiple output topics.

The chunk attribute is also available on the map element; values set will apply to all the topics in the ditamap.

The chunk attribute is only ever applied to a parent node topicref element or a map element, and its value applies to the parent and its child topics.

The chunk attribute has up to three parts, or tokens, each separated by a space. For example, an attribute coded as chunk="select-topic to-content" has two tokens; select-topic and to-content.

There are three categories of tokens:

Selection tokens: Selection tokens are only used for identifying nested topics within a composite ditabase topic, so that the chunking policy can be applied to an individual nested topic (select-topic), a family of nested topics (select-branch), or the entire composite topic (select-document).
Policy tokens: Policy tokens specify whether the referenced topics should be split (by-topic) or merged (by-document).
Rendering tokens: Rendering tokens specify whether the referenced topics should be generated as a single topic (to-content), or whether they should be generated as separate topics but with just one entry in the table of contents (to-navigation).

As an example, a portion of a ditamap with a structure of:

<topicref href="c_safety.dita" chunk="to-content"> 
  <topicref href="c_electronic_brake_force_distribution.dita"  /> 
  <topicref href="t_child_restraint.dita" /> 
  <topicref href="c_other_restraint_systems.dita" />
</topicref>

will be output as one single HTML topic, with a file name of c_safety.html.

Note:

With the exception of the rendering tokens, most valid chunk attributes apply only to the processing of composite (ditabase) topics. Where possible, avoid using composite topics, and instead use ditamaps.