[EXT]: Re: [dita-users] Topichead usage and best practice #bookmap


Using <topicref format=”dita” scope=”local” type=”concept”> with <navtitle>Organizational Title Text</navtitle> validates in processing, but produces no actual output topic in HTML, though the text in the navtitle appears in the TOC in the hierarchy.


In HTML output, the problem is:

  • No actual topic.html exists
  • TOC link has no topic to display in the reading pane
  • Title text doesn’t display in the breadcrumb navigation
  • Can’t select the TOC link and all its child topics and export to PDF or share in email


To get around those problems, you have to create an topic with a title (and preferably a useful short description).  From a minimalist perspective, this is not ideal.


In cloud publishing systems, where topic count equals investment, every topic should be meaningful and useful, and large numbers of title only topics create possible duplication and a hit on total topic count. Search results return many instances of what appears to be the same topic, so you have to apply metadata to the source to ensure the correct title only topic returns it’s associated publication. 


These might be some reasons why <topichead> or <topicref> without an href value shouldn’t be used for HTML publications.


Mona Ross | Sr. Information Architect | Ellucian® | M:+1.304.596.3712 |

CONFIDENTIALITY: This email (including any attachments) may contain confidential, proprietary and privileged information, and unauthorized disclosure or use is prohibited. If you received this email in error, please notify the sender and delete this email from your system. Thank you.


From: <> On Behalf Of Joe Pairman via
Sent: Wednesday, May 13, 2020 2:26 AM
Subject: [EXT]: Re: [dita-users] Topichead usage and best practice #bookmap


**External Email**

Thanks for sharing that! Tony provides a really good, succinct view there on why not to use topicheads as a general rule. 


The only time I used them in an IA was to drive a very specific output where the topic heads were non-selectable visual cues. Even so, I might be tempted to do it a different way if I had to do it again — something like a specialized outputclass attribute triggering custom stylesheet processing. 


On Mon, Apr 27, 2020 at 15:28 <ronny.flink@...> wrote:

I stopped using <topichead> after read the DITA style guide, by Tony Self. I also had problems with untranslated titles, when forgot to send <topichead> content to translation.

” There are two main reasons why topichead elements should be avoided. The first is that it conflicts with the notion of the separation of content and form, and the separation of data and metadata. All content (data) in a document should reside in the topics, not in the map. The ditamap should only contain metadata. If you use topichead as an alternative to a title-only topic, you are effectively placing non-reusable content, or data, in the ditamap. The second reason is more practical. If you are transforming a ditamap to a hypertext output format with a TOC, such as to Eclipse Help, the topichead elements will be transformed to unlinked parent nodes in the TOC. When the user clicks on such a node, the content pane will not display an associated topic, as it will for other nodes in the TOC. This inconsistency appears to the user to be an error. The unlinked node in the TOC will also cause inconsistencies or malfunctions in the way breadcrumbs function, and the way sequences (previous and next topic links) function.”

best regards

Larry Kollar

Good point. I knew there was some catch, but couldn't quite figure out what. I'll pass the info along.