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

larmarange · 2018-11-12T13:12:13Z

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.

The text was updated successfully, but these errors were encountered:

mb21 · 2018-11-12T13:14:24Z

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

larmarange · 2018-11-12T13:30:25Z

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 · 2018-11-12T13:31:37Z

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 · 2018-11-12T13:47:41Z

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 · 2018-11-12T13:58:17Z

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 · 2018-11-12T14:00:40Z

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

larmarange · 2018-11-12T14:01:35Z

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

mb21 · 2018-11-12T14:03:20Z

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 · 2018-11-12T15:46:28Z

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 · 2018-11-12T15:54:35Z

You can do this using CSS counters.

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

tarleb · 2018-11-12T16:23:33Z

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

larmarange · 2018-11-13T13:17:17Z

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 · 2018-11-13T17:26:40Z

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 · 2018-11-13T17:40:43Z

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 · 2018-11-13T17:42:41Z

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 · 2018-11-13T20:22:19Z

Joseph <notifications@github.com> 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 · 2018-11-14T14:54:47Z

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 · 2018-11-14T16:21:23Z

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 · 2018-11-14T17:03:16Z

Such approach would work perfectly

tarleb · 2018-11-14T17:34:13Z

Reopening so this won't get lost.

larmarange · 2018-11-20T18:25:37Z

thanks

cavo789 · 2019-09-05T06:16:08Z

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 · 2019-09-05T07:01:31Z

this may be related: #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

andrewstarks · 2021-06-08T16:32:17Z

I've been struggling with this myself. I made a stupidly simple Lua filter, which seems to work for me.

-- For LaTeX documents, shift all headings down by one.
-- Make Level 1 unnumbered, or remove it if it contains the "hidden" class. (`# Title {.hidden}`)
function Header(el)
    -- do this for only latex output.
    if FORMAT:match "latex" then
        if el.level == 1 then
            --check for hidden class. (Why didn't pandoc make this a set? `{class_name = true}`)
            for i, v in ipairs(el.classes) do
                if v == "hidden" then
                    --The empty list means remove the element
                    return {}
                end
            end
            -- this may mean that there are two unnumbered classes, but that doesn't matter.
            el.classes[#el.classes + 1] = "unnumbered"
        else
            -- all headings > 1 are shifted down so that you don't end up with 0.x.y headings.
            el.level = el.level - 1
        end
    end
    return el
end

# My TItle
...or...
# My Title {.unnumbered}
...will not be included in the numbering.

# My Title {.hidden}

...will not show up in the PDF document, at all

phiresky · 2021-07-22T16:43:44Z

The docs for shift-heading-level-by mention this:

--shift-heading-level-by=1 may be a good choice for converting Markdown documents that use level-1 headings for sections to HTML, since pandoc uses a level-1 heading to render the document title.

Which lead me to believe that shift-heading-level=x behaves in the way that people are discussing in this issue - but when you add --number-sections it becomes "wrong" by adding 0. in front of the numbers.

Maybe another flag should be added like --number-depth-offset=1 similar to --number-offset but shifting the numbers to the left?

Since the content of this issue is kinda spread out, here's an exact example:

---
title: Title of document
---

# Section 1

text text text

# Section 2

text text text

## Sub-section 2.1

text

pandoc a.md --standalone --base-header-level=2 --number-sections´

actual output:

...
<header id="title-block-header">
<h1 class="title">Title of document</h1>
</header>
<h2 data-number="0.1" id="section-1"><span class="header-section-number">0.1</span> Section 1</h2>
<p>text text text</p>
<h2 data-number="0.2" id="section-2"><span class="header-section-number">0.2</span> Section 2</h2>
<p>text text text</p>
<h3 data-number="0.2.1" id="sub-section-2.1"><span class="header-section-number">0.2.1</span> Sub-section 2.1</h3>
<p>text</p>
...

expected output:

<header id="title-block-header">
<h1 class="title">Title of document</h1>
</header>
<h2 data-number="1" id="section-1"><span class="header-section-number">1</span> Section 1</h2>
<p>text text text</p>
<h2 data-number="2" id="section-2"><span class="header-section-number">2</span> Section 2</h2>
<p>text text text</p>
<h3 data-number="2.1" id="sub-section-2.1"><span class="header-section-number">2.1</span> Sub-section 2.1</h3>
<p>text</p>

jgm · 2021-07-23T05:22:30Z

I guess there are two cases to consider:

Document starts with a level-2 header but later has a level-1.
Document starts with a level-2 header and never has a level-1.

(1) would seem to be a pretty rare kind of case, while (2) is common for the reason you give. Unfortunately pandoc is producing the output appropriate to (1).

One possibility would be to have the HTML writer start numbering with whatever the lowest-numbered header that occurs in the document. So in case 1, we'd number 0.1, 0.2, 1.1, etc., while in case 2 we'd number 1, 2, etc. I prefer not to add options if we can do the right thing automatically.

Another question is whether such a change would lead to a divergence in HTML and LaTeX/PDF output, and if so how to fix it. (There may be similar questions about docx and other formats.)

chapterjason · 2022-02-09T11:57:28Z

I currently use this:

[
  "--standalone",
  "--number-sections",
  "--shift-heading-level-by=1",
  "--number-offset=1",
  "--no-highlight",
  "--toc",
  "--toc-depth=3",
  "--top-level-division=chapter",
  "--listings",
  "--include-after-body",
  "'[REDACTED]\\resources\\templates\\_watch.html'",
  "--metadata=title-meta:Test",
  "--metadata=title:Test",
  "'--metadata=date-meta:2022-02-09T11:53:29.849Z'",
  "'--metadata=author-meta:Foo bar'",
  "'--metadata=subtitle:This is a sample example to show all features.'",
  "'--metadata=description-meta:Example here, example there. -- There'",
  "--metadata=lang:en",
  "'--metadata=keywords:test,demo,example,kitchen-sink'",
  "--template",
  "'[REDACTED]\\resources\\templates\\default.html'",
  "--css",
  "'./assets/default.css'",
  "--strip-comments",
  "--from",
  "markdown",
  "--to",
  "html5"
]

Input:

# a

## b

### c

# d

## h

### l

# i

Output:

What I try to achieve:

PeterWang-dev · 2023-03-14T07:50:13Z

Reply to keep this issue alive.

asiz · 2023-03-14T12:14:08Z

I ran into the same issue, and believe it would be convenient to have a solution matching the html and pdf outputs. Thanks for this great tool!

tarleb · 2023-03-30T08:41:41Z

Related question on StackOverflow: https://stackoverflow.com/q/73417580

Including the relevant Lua filter here to save you a click. Use the filter by saving the below to a file shift-headings.lua and pass that file to pandoc via --lua-filter=shift-headings.lua.

function Pandoc (doc)
  -- Create and number sections. Setting the first parameter to
  -- `true` ensures that headings are numbered.
  doc.blocks = pandoc.utils.make_sections(true, nil, doc.blocks)

  -- Shift the heading levels by 1
  doc.blocks = doc.blocks:walk {
    Header = function (h)
      h.level = h.level + 1
      return h
    end
  }

  -- Return the modified document
  return doc
end

PrinceKay145 · 2023-09-23T10:32:04Z

I have the same issue while trying to convert a markdown file to pdf.

Thanks to everyone who contributed.
I have not been able to solve it yet, but i learnt more about markdown from this thread)

kosson · 2024-01-24T13:32:15Z

I ran into this myself via via Obsidian plugin: https://github.com/mokeyish/obsidian-enhancing-export.
The supplementary arguments I used are: --csl https://raw.githubusercontent.com/citation-style-language/styles/master/harvard-limerick.csl --bibliography="/home/nicolaie/Documents/Library-Zotero-all.bib" --pdf-engine=/usr/bin/pdflatex --filter pandoc-crossref --toc=true --toc-depth=3 --standalone -V toc-title:"Cuprins" --number-sections --number-offset=1 --citeproc. This lead to the following PDF rendering.

Context:
pandoc 3.1.11
Features: +server +lua
Scripting engine: Lua 5.4

pdfTeX 3.141592653-2.6-1.40.25 (TeX Live 2023/Debian)
kpathsea version 6.3.5

jgm · 2024-02-03T18:24:13Z

To reproduce:

$ printf "# one\n\n# Two\n" | pandoc --number-sections --shift-heading-level-by=1 -t html
^D
<h2 data-number="0.1" id="one"><span
class="header-section-number">0.1</span> one</h2>
<h2 data-number="0.2" id="two"><span
class="header-section-number">0.2</span> Two</h2>

…() so use PCRE instead

This is like `makeSections` but has an additional parameter specifying number offsets, for use with the `--number-offset` option. Use `makeSectionsWithOffsets` in HTML writer instead of ad hoc and inefficient number-adjusting code. Clarify MANUAL.txt: the `--number-offset` option should only directly affect numbering of the first section heading in a document; subsequent headings will increment normally. Fix test output for #5071 to reflect this.

palapapa · 2024-12-24T00:06:41Z

Even though this has been closed, doing what the OP said in the issue still produces numbers like "0.1", "0.2" etc. if you use numbered sections but start with h2 (##) while using the metadata block for the title and author. Using the filter written by @andrewstarks is the only thing that worked for me. It would be nice to have an option that can do this without using filters.

--number-offset doesn't work for LaTeX outputs so I can't use that.

mb21 closed this as completed Nov 12, 2018

larmarange changed the title ~~Selecting root level for number_sections~~ Issue of --numbered-sections used with --base-header-level=2: could an additional pandoc option be relevant? Nov 14, 2018

tarleb reopened this Nov 14, 2018

This was referenced Nov 20, 2018

Using # for section titles with --base-header-level=2 instead of using ## ? rstudio/distill#63

Open

add number_section function in yaml options? rstudio/distill#56

Open

Wandmalfarbe mentioned this issue Sep 2, 2019

TOC and numbering Wandmalfarbe/pandoc-latex-template#114

Closed

mb21 changed the title ~~Issue of --numbered-sections used with --base-header-level=2: could an additional pandoc option be relevant?~~ Issue of --numbered-sections used with --base-header-level=2: produces 0.x.y Sep 7, 2019

dhimmel mentioned this issue Oct 21, 2019

default CSS theme: only center the title header manubot/rootstock#273

Closed

phiresky mentioned this issue Oct 20, 2021

Allow use of --number-sections manubot/rootstock#442

Open

multimeric mentioned this issue Oct 21, 2021

Heading numbering manubot/rootstock#441

Open

obgnail mentioned this issue Nov 17, 2023

自动编号的标题导出到Word中没有编号 obgnail/typora_plugin#302

Closed

jgm closed this as completed in 03bb426 Feb 4, 2024

cderv referenced this issue in rstudio/bookdown Feb 21, 2024

fix #1454: the default TRE could destroy the characters in strip_html…

9a23818

…() so use PCRE instead

cderv mentioned this issue Feb 21, 2024

Check and adapt to new --number-sections in Pandoc 3.1.12 rstudio/bookdown#1455

Closed

TeaDrinkingProgrammer mentioned this issue Mar 13, 2024

Update default number-sections settings according to new behaviour pandoc. Zettlr/Zettlr#5029

Closed

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

larmarange commented Nov 12, 2018

mb21 commented Nov 12, 2018

larmarange commented Nov 12, 2018

larmarange commented Nov 12, 2018

mb21 commented Nov 12, 2018

larmarange commented Nov 12, 2018

larmarange commented Nov 12, 2018

larmarange commented Nov 12, 2018

mb21 commented Nov 12, 2018

larmarange commented Nov 12, 2018

mb21 commented Nov 12, 2018

tarleb commented Nov 12, 2018 •

edited

Loading

larmarange commented Nov 13, 2018

jgm commented Nov 13, 2018 •

edited

Loading

larmarange commented Nov 13, 2018

larmarange commented Nov 13, 2018

jgm commented Nov 13, 2018 via email

larmarange commented Nov 14, 2018 •

edited

Loading

jgm commented Nov 14, 2018 via email

larmarange commented Nov 14, 2018

tarleb commented Nov 14, 2018

larmarange commented Nov 20, 2018

cavo789 commented Sep 5, 2019

mb21 commented Sep 5, 2019 •

edited

Loading

andrewstarks commented Jun 8, 2021 •

edited

Loading

phiresky commented Jul 22, 2021 •

edited

Loading

jgm commented Jul 23, 2021

chapterjason commented Feb 9, 2022

PeterWang-dev commented Mar 14, 2023

asiz commented Mar 14, 2023

tarleb commented Mar 30, 2023

PrinceKay145 commented Sep 23, 2023

kosson commented Jan 24, 2024

jgm commented Feb 3, 2024

palapapa commented Dec 24, 2024 •

edited

Loading

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

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

Comments

larmarange commented Nov 12, 2018

mb21 commented Nov 12, 2018

larmarange commented Nov 12, 2018

1 Title of document

1.1 Section 1

1.2 Section 2

1.2.1 Sub-section 2.1

larmarange commented Nov 12, 2018

mb21 commented Nov 12, 2018

larmarange commented Nov 12, 2018

Title of document

0.1 Section 1

0.2 Section 2

0.2.1 Sub-section 2.1

larmarange commented Nov 12, 2018

larmarange commented Nov 12, 2018

mb21 commented Nov 12, 2018

larmarange commented Nov 12, 2018

Title of document

1 Section 1

2 Section 2

2.1 Sub-section 2.1

mb21 commented Nov 12, 2018

tarleb commented Nov 12, 2018 • edited Loading

larmarange commented Nov 13, 2018

jgm commented Nov 13, 2018 • edited Loading

larmarange commented Nov 13, 2018

larmarange commented Nov 13, 2018

jgm commented Nov 13, 2018 via email

larmarange commented Nov 14, 2018 • edited Loading

jgm commented Nov 14, 2018 via email

larmarange commented Nov 14, 2018

tarleb commented Nov 14, 2018

larmarange commented Nov 20, 2018

cavo789 commented Sep 5, 2019

mb21 commented Sep 5, 2019 • edited Loading

andrewstarks commented Jun 8, 2021 • edited Loading

phiresky commented Jul 22, 2021 • edited Loading

jgm commented Jul 23, 2021

chapterjason commented Feb 9, 2022

PeterWang-dev commented Mar 14, 2023

asiz commented Mar 14, 2023

tarleb commented Mar 30, 2023

PrinceKay145 commented Sep 23, 2023

kosson commented Jan 24, 2024

jgm commented Feb 3, 2024

palapapa commented Dec 24, 2024 • edited Loading

tarleb commented Nov 12, 2018 •

edited

Loading

jgm commented Nov 13, 2018 •

edited

Loading

larmarange commented Nov 14, 2018 •

edited

Loading

mb21 commented Sep 5, 2019 •

edited

Loading

andrewstarks commented Jun 8, 2021 •

edited

Loading

phiresky commented Jul 22, 2021 •

edited

Loading

palapapa commented Dec 24, 2024 •

edited

Loading