Heading VS ToC numbering in PDF with Dita/Markdown

[TamasB]

Hello!
My doc team is using a Dita/Markdown setup to publish HTML+PDF, and it was recently brought to our attention that the numbering of heading sections is different VS the ToC:


How it looks in the ditamap:

Code: Select all

    <topicref href="_install_ad_op/prerequisites_installing_nf.md" format="markdown" keys="prerequisites_deploying">
        <topicref href="solution-prereq/_install/installation.md" format="markdown" keys="solution_prereq_helm"/>

In which:
The H1 .md file "prerequisites_installing_nf.md" has 9 subsections as level "##" labeled as 4.1, [...], 4.9
While the H2 .md file "installation.md" is 4.10
But in the ToC, 4.10 becomes 4.1, as it doesn't take into consideration the ## subsections from H1, while interestingly, the PDF sidebar does.

Required solution:
For us, it's irrelevent whether it's the ToC that takes the numbering of the subsections from the H1 .md file, or the subsections in there don't get heading numbers at all, we would just like the ToC to reflect the numbering of the actual heading numbers.
Can you help us point out where (in the CSS?) we can either remove the ## (level 2) heading numbering from the .MD files, or make them appear in the ToC? Either of this would be OK for us.

Background info:
This was tested both on the client-side CI/CD using Oxygen Publishing Engine on version 24.1, and our ofline Oxygen Author 26.1 setup. We are using CSS-based PDF publishing.
In the PDF template properties we are using:

Code: Select all

#enable topic numbering
args.css.param.numbering = deep-chapter-scope-no-page-reset

Please let us know if you can help, or need more info.
edit: redacted client propriatary info from screenshot

[julien_lacour]

Hello,

You can remove the subtopics from the bookmarks by using the following rule in your CSS:

Code: Select all

*[class~="topic/topic"] *[class~="topic/topic"]:not([topicrefclass ~="map/topicref"]) > *[class~="topic/title"] {
  bookmark-level: 0;
}
*[class ~= "map/map"][numbering ^= 'deep'] *[class ~= "topic/topic"][is-chapter]:not([is-part]) *[class ~= "topic/topic"]:not([topicrefclass ~="map/topicref"]) {
  counter-increment: none;
}
*[class ~= "map/map"][numbering ^= 'deep'] *[class ~= "topic/topic"][is-chapter]:not([is-part]) *[class ~= "topic/topic"]:not([topicrefclass ~="map/topicref"]) > *[class ~= "topic/title"]:before {
  content: none;
}

Regards,
Julien

[TamasB]

Thanks Julien, this works! I consider this Solved, but curious if you know a solution to the other possibility too, i.e. to include the .MD subsections in the ToC too.

[julien_lacour]

Hello,

I also added an issue on our side to remove these subtopics by default in our CSS stylesheets.
We will also analyze if we can bring the subtopic inside the TOC. I will post on this thread if the status changes.

Regards,
Julien

[TamasB]

Many thanks Julien! We'll keep an eye out on your updates.

[julien_lacour]

Hello,

If you want the subtopics to be displayed in the TOC, you need to reference them in the ditamap directly:

Code: Select all

<topicref href="topics/topic.md" format="markdown">
    <topicref href="topics/topic.md#subtopicId" format="markdown"/>
</topicref>

Where "subtopicId" is the ID attribute value (either the topic title or the value in {#subtopicId}).
Check Markdown DITA syntax reference for more information.

Regards,
Julien

[TamasB]

Hi Julien! Extra thanks for getting back with both solutions! Now we can consider the options as well.

[julien_lacour]

Hello,

Oxygen 27.0 is now available, in this version you can include sub-topics in the TOC when publishing PDFs.
For more information you can check our user guide.

Regards,
Julien