search

asciidoctor / asciidoctor-pdf

:page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.
https://docs.asciidoctor.org/pdf-converter/latest/
MIT License
1.14k stars 500 forks source link

asciidoctor-pdf stops rendering section headers at a certain level #2443

Closed houserockr closed 12 months ago

houserockr commented 12 months ago

I'm running asciidoctor-pdf on osx m2 (aarch64) with the following version installed via homebrew:

Asciidoctor PDF 2.3.7 using Asciidoctor 2.0.20 [https://asciidoctor.org] Runtime Environment (ruby 3.2.2 (2023-03-30 revision e51014f9c0) [arm64-darwin22]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

It seems that section headings at a certain level aren't rendered.

Screenshot 2023-08-28 at 13 46 33

Section 9.11.2.2.2 - which has 6 '='s in the *.adoc - is still rendered, but the next section one level down 9.11.2.2.2.1 - which has 7 '='s - isn't.

Is there a parameter that limits the maximum number of levels?

wmat commented 12 months ago

See https://docs.asciidoctor.org/asciidoc/latest/toc/levels/

By default, the TOC displays level 1 (==) and level 2 (===) section titles. You can assign a different level depth with the toclevels attribute. Accepted values are the integers 1 through 5.

houserockr commented 12 months ago

Correct me if I'm wrong, but to me, adding sections to the TOC and rendering section headers are two different things. The screenshot is not showing the TOC, it's showing the section header within the document. Are those affected by toclevels anyways?

houserockr commented 12 months ago

Screenshot 2023-08-28 at 17 58 19 Why does it just stop at level 5???

wmat commented 12 months ago

I don't know. You will get more answers in the community chat at https://asciidoctor.zulipchat.com

mojavelinux commented 12 months ago

Why does it just stop at level 5???

Section levels are limited to 0-5 because HTML only supports heading levels 1-6 (the heading level in HTML is always one more than the section level). This decision was made long ago and Asciidoctor complied with it. However, we are reconsidering this restriction in the AsciiDoc Language specification. However, no change will be implemented in Asciidoctor until at least the first draft of that specification is ready.

For further explanation, see https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax

houserockr commented 12 months ago

I mean I get that you need to be compatible with html, pdf, and all other output formats. And if one of those only supports a certain amount of levels for section headers, that is in fact a limitation. But imho, simply passing the asciidoc code through to the resulting document is a very bad idea.

Wouldn't it be nicer to at least render a section title having a level higher than the limit as a paragraph title (.Paragraph Title)?

mojavelinux commented 12 months ago

Your objection has been heard and, as I said, a change has already been proposed in the AsciiDoc Language specification (in part for the reasons you cited). No change is going to happen in Asciidoctor until that has cleared, so there's no use discussing it here further. You are welcome to join the specification effort if you want to contribute to the proposal.