Is there a way to increase the generated pdf bookmark list's depth? I am referring to the left navigation bookmark panel when opening in readers such as Adobe reader. It appears that asciidoctor-pdf only generates to level 3 depth. or "===" depth in asciidoc.
= title
== section 1
=== sub section 1
==== sub section a
==== sub section b
=== sub section 2
== section 2
In the above example, sub section a and b would be missing from the bookmarks.
Figured it out.
Add the asciidoctor-pdf attribute...
:toclevels: 3
Related
I'm trying to have the following kind of layout in a Sphinx document :
Title
Article 1
Section 1
Article 2
I already saw that no matter what symbols I use to underline or overline the headers, the first appearance of a given heading will determine its hierarchical relation to the others. I.e, the following won't work :
==========
Title
==========
Article 1
---------
---------
Section 1
---------
Article 2
---------
Is there a way to circumvent this, for example by defining an invisible "Section 0" heading between Title and Article 1 with dashes as underline and overline, so that sphinx understands that Sections are greater than Articles, without actually displaying a "Section 0" between the title and the first article ?
I'm trying to do something like this Skipping heading levels in reStructuredText - although I don't really understand the code example they give...
The only ugly solution I found is the following :
=====
Title
=====
-----
\
-----
Article 1
---------
...
The two issues are that it creates a blank gap in the resulting document, and that it inserts a title-less heading in the toctree at the index page (even though it does not do that in the local summary).
I have the following document:
= Section
main text
== Subsection
some details text
Now I would like to continue my main text after the subsection. How can I "return" to the section part?
Differently speaking, how can I go up in the section hierarchy?
As far as I know, defining a new section, e.g., a == after a =, will bring me down one hierarchy. Is there also a way to go back up one hierarchy? I.e., to go back to the previous = level?
If I write = again, I start a new section, but I want to continue the old section, that already started before the current subsection.
I am imagining something like this:
= Section
main text
== Subsection
some details text
= (some keyword to return to the previous section)
continue main text
You can return to a "parent" section level by introducing a new parent heading, as described in the documentation.
Since there is no some keyword to return to the previous section, you cannot do:
== Section
Loreum ipsum...
=== Sub-section...
Ipso facto...
Parent section content here.
However, you could use one of the various blocks types to simulate that structure. Here's an example of using an open block with a discrete heading:
== Section
Lorem ipsum...
--
[discrete]
=== Sub-section
Ipso facto...
--
'''
Parent section content here.
The discrete heading is necessary to prevent the heading being counted as a sub-section title, which in turn would include the following parent section content within the sub-section. Note that using the discrete heading removes the heading from the table of contents too.
I included a horizontal rule with ''' so that there is a visual delineation between the sub-section content and the parent section's continuing content.
I am stuck on the depth of the toctree of my sidebar doc. Here's my doc : https://aff3ct.readthedocs.io/en/user_doc_dev/simulation/parameters/cdc/cdc_bch/cdc.html
As you can see, on the sidebar the toctree does not go deeper than the fourth level, but I have two other levels under. There is at the top of the page the Edit on GitHub link then you can see the source code.
I tried :maxdepth: -1 in any toctree directive but it changes only the display of the page's TOC and not of the sidebar's.
I tried on the first line of my first top file :tocdepth: 6, or with -1 or any big number, but it changes nothing.
I tried sphinxcontrib-fulltoc, but it never compiled; I did't find why.
Any idea ? Is it really possible to display deeper on the sidebar ? Is it a known bug ?
I've got my index file set up like so:
Doc Title
==============================
..toctree::
:maxdepth: 3
:numbered:
:caption: Contents
01_file1
01.3_file2
If the contents are thus...
01_file1.txt:
Level 1 section title
--------------------------------------------
Level 2 section title
............................................
Another Level 2 section title
............................................
and for 01.3_file2.txt:
A third Level 2 section title
............................................
I would expect this because Sphinx treats everything as a single document:
1. Level 1 section title
1.1 Level 2 section title
1.2 Another Level 2 section title
1.3 A third Level 2 section title
But instead I get this:
1. Level 1 section title
1.1 Level 2 section title
1.2 Another Level 2 section title
2. A third Level 2 section title
I'm guessing this is because Sphinx (or maybe reST/Markdown?) restarts implicit heading levels with each new text file. Is there a way to get what I actually want?
Quoting the reST documentation...
Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.
The parent file determines the heading level of its included children. To achieve the desired effect, remove 01.3_file2 from index, and place an .. include:: 01.3_file2 in 01_file1.txt at the point where you want to include it.
index:
Doc Title
==============================
..toctree::
:maxdepth: 3
:numbered:
:caption: Contents
01_file1
01_file1.txt:
Level 1 section title
--------------------------------------------
Level 2 section title
............................................
Another Level 2 section title
............................................
.. include:: 01.3_file2.txt
01.3_file2.txt:
A third Level 2 section title
............................................
Results in:
1. Level 1 section title
1.1 Level 2 section title
1.2 Another Level 2 section title
1.3 A third Level 2 section title
Is it possible in some way to skip heading levels in RestructuredText? For example, given
####
PART
####
*******
Chapter
*******
Section
=======
Subsection
----------
Subsubsection
^^^^^^^^^^^^
Paragraph
"""""""""
Another section
===============
Another Paragraph
"""""""""""""""""
The above heading seems to be rendered as a subsection-level heading...
The last paragraph gets rendered as a subsection instead of as a paragraph. (I am using Sphinx as a renderer.) So it seems section-level detecting is local, although the RestructuredText documentation says it should be consistent:
All section title styles need not be used, nor need any specific
section title style be used. However, a document must be consistent in
its use of section titles: once a hierarchy of title styles is
established, sections must use that hierarchy.
When running Sphinx 1.3 on the document in the question, a warning is emitted:
C:\path\to\test.rst:24: SEVERE: Title level inconsistent:
"Another Paragraph" is on line 24 and it gets rendered as a subsection heading because that is what Sphinx expects at that position.
So no, you cannot skip heading levels. That is also how I interpret the meaning of the passage about consistency quoted in the question.