Pandoc: Issue of --numbered-sections used with --base-header-level=2: produces 0.x.y

[larmarange]

When h1 is used for the title of a document and h2 for the sub-sections, --numbered-sections is producing 0.1, 0.2 etc.

It would be relevant to have an option to specify that numbering should start at level 2.

[mb21]

Can you post pandoc version, exact input/output please?

[larmarange]

I'm using Pandoc 2.2.1

A basic md file:

# Title of document

## Section 1

text text text

## Section 2

text text text

### Sub-section 2.1

text text text

Command: pandoc example.md -o example.html will produce

 

1 Title of document

1.1 Section 1

text text text

1.2 Section 2

text text text

1.2.1 Sub-section 2.1

text text text

The purpose would be to number only headers 2 and 3.  

[larmarange]

Regarding the introduction of "0.1" or "0.2", it occurs when you are using Rmarkdown document in RStudio (in such case, the title is defined in the YAML header and the levels 2 are defined in the markdown itself).

Regards

[mb21]

The purpose would be to number only headers 2 and 3.

Try:

# My header {.unnumbered}

See the http://pandoc.org/MANUAL.html for details.

it occurs when you are using Rmarkdown document in RStudio

Maybe RStudio is using an older version of pandoc? Or otherwise it's just a bug at their end...

[larmarange]

It's producing

Title of document

0.1 Section 1

 

text text text

 

0.2 Section 2

text text text

 

0.2.1 Sub-section 2.1

 

text text text

[larmarange]

Here the issue is to remove the 0. part of the level 2 and level 3 headers.

[larmarange]

Note: Pandoc 2.2.1 is the version embed with the current version of RStudio

[mb21]

Pandoc 2.2.1 is the version embed with the current version of RStudio

I've a vague memory of there being such a bug earlier..

The plain pandoc command works as expected, so I'm closing this issue. For questions, pandoc-discuss should be used. Or ask the RStudio folks...

[larmarange]

Sorry, but going back to my initial point.

It would be useful to have an additional option in pandoc (e.g. --start-numbering-level=2) allowing to produce something like

Title of document

1 Section 1

 

text text text

 

2 Section 2

text text text

 

2.1 Sub-section 2.1

 

text text text

[mb21]

You can do this using CSS counters.

If you're targeting other output formats, pandoc-crossref might help.

[tarleb]

@larmarange it sounds like you might be looking for --number-offset.

[larmarange]

Thank you @tarleb, as I understood it, --number-offset allows to specify the start of the counters, but not to hide level 1 in level numbers, i.e. to number level 2 headings 1, 2, 3 etc. instead of 1.1, 1.2, 1.3, and to number level 3 headings as 1.1, 1.2 instead of 1.1.1, 1.2.1 etc.

Thank you @mb21 , I will look at pandoc-crossref.

[jgm]

I suspect you're doing this:

# Title of document

## Section 1

etc.

Normally in pandoc you'd lay this out this way instead:

title: Title of document
...

# Section 1

 text text text

# Section 2

text text text

## Sub-section 2.1

text

If you do it this way, pandoc --number-sections will give you just what you're looking for. Try it.

If you really want the layout where level-2 headers are your section headers, then you can put the unnumbered class on the level-1 header and use --number-offset.

[larmarange]

The issue in HTML is that there is no standard regarding the main title of the page and many templates are using <h1> for that purpose and therefore <h2> as the section titles.

Therefore, your md file looks like:

title: Title of document
---

## Section 1

 text text text

## Section 2

text text text

### Sub-section 2.1

text

But you get sections numbers as 0.1 0.2.

--number-offset allow you to transform them into 1.1 1.2 but not into 1 2

[larmarange]

Maybe a better approach would be to write in your md file titles like:

title: Title of document
---

# Section 1

 text text text

# Section 2

text text text

## Sub-section 2.1

text

and to use --base-header-level=2. However, even in that case, the result remains the same as # section is transformed into an h2 before the computation of section numbers.

[jgm]

Joseph [e-mail] writes:

The issue in HTML is that there is no standard regarding the main title of the page and many templates are using <h1> for that purpose and therefore <h2> as the section titles.

Pandoc's templates use <h1> for both, distinguishing
the title with a special class.

This allows us to retain a consistent meaning for
level-one headers across formats.

[larmarange]

That's right.

However, there are many cases when there is a need to produce <h2> elements and the option --base-header-level=2 is perfect in such context (allowing to control the HTML markup without changing the semantics of the markdown).

The only problem is when combining --base-header-level=2 with --number-sections as --number-sections is applied after.

For such situation, an additional option (e.g. --base-numbering-level==2 or another name) would be relevant to control the way headers are numbered.

[jgm]

One possibility would be to change the number
generation algorithm so that it rewrites 0.x.y -> x.y.
It's hard to think of cases where this would give bad
results; I suppose it would do so if you started a
document with level 2 headers, then went to level 1,
but who does that?

[larmarange]

Such approach would work perfectly

[tarleb]

Reopening so this won't get lost.

[larmarange]

thanks

[cavo789]

Just read the full issue and want to say I've exactly the same need of @larmarange

I'm also producing HTML page so I don't want to have more than one H1 in my document (for SEO purposes) and my wish is to be able to ignore that H1 in my TOC; don't mention it and don't number it. The first item "1. xxx" start with H2 level. Just like Jospeh is asking for as far I understand.

[mb21]

this may be related: https://github.com/jgm/pandoc/issues/5615 ...or maybe not. I guess jgm's proposed fix from above is good enough:

One possibility would be to change the number
generation algorithm so that it rewrites 0.x.y -> x.y.

The test input would be:

pandoc -s -o foo.html --number-sections --base-header-level=2 --toc
^D
---
title: doc title
---

# first heading