Documentation Center

DITA Best Practices and Caveats

This topic provides some best practices, quirks and limitations in using DITA with Content Delivery.

Related links: linkpool vs. linklist
If you wish to hard-code a set of related links, use the linklist element to contain your links. Content Delivery preserves the contents of the linklist element, but clears and regenerates the contents of a linkpool element to populate it with links that fit the context. This is consistent with DITA spec section 3.1.1.4.3, linkpool.
Anchorref must have @toc="no"
When using the anchorref element to push map content, give the anchorref element the attribute @toc="no" because it is essentially a topicref element without an @href link. If you wish to display the child topicrefs in the map where the anchorref element is used, give the child elements the attribute @toc="yes".
Chaining Key References
In DITA, it is possible to chain key references; that is, to have a keyref to an element that has a keyref to another element, and maybe more levels, until the final href is defined. The DITA spec recommends support for at least three level of such references. At this time, Content Delivery supports only the first reference.