Heading VS ToC numbering in PDF with Dita/Markdown

Post here questions and problems related to editing and publishing DITA content.
TamasB
Posts: 5
Joined: Tue Oct 01, 2019 2:32 pm

Heading VS ToC numbering in PDF with Dita/Markdown

Post by 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:
Image

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
Posts: 528
Joined: Wed Oct 16, 2019 3:47 pm

Re: Heading VS ToC numbering in PDF with Dita/Markdown

Post by 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
Posts: 5
Joined: Tue Oct 01, 2019 2:32 pm

Re: Heading VS ToC numbering in PDF with Dita/Markdown

Post by 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
Posts: 528
Joined: Wed Oct 16, 2019 3:47 pm

Re: Heading VS ToC numbering in PDF with Dita/Markdown

Post by 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
Posts: 5
Joined: Tue Oct 01, 2019 2:32 pm

Re: Heading VS ToC numbering in PDF with Dita/Markdown

Post by TamasB »

Many thanks Julien! We'll keep an eye out on your updates.
julien_lacour
Posts: 528
Joined: Wed Oct 16, 2019 3:47 pm

Re: Heading VS ToC numbering in PDF with Dita/Markdown

Post by 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
Posts: 5
Joined: Tue Oct 01, 2019 2:32 pm

Re: Heading VS ToC numbering in PDF with Dita/Markdown

Post by TamasB »

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