TOC and numbering

[cavo789]

First of all, thank you for this very nice template. Much, much! better than the default pdf template of pandoc.

Since yesterday, I'm facing with a problem with the numbering of headings and didn't find any solution.

My .md file is an user documentation, I've only one # h1 line (this is my wish since when converting to HTML, SEO good practice is to have only one <h1>... </h1> in the page)

So, first question, is it possible to not mention that H1 in the table of contents? Make just like if it didn't exists at all (so don't number it too)

And, as you can see here below, my second question, I didn't understand how numbers are defined. My first h1 is number 0.1 and my first H2 is numbered 0.1.1; why this first 0 before?

Many thanks!

[Wandmalfarbe]

I've only one # h1 line (this is my wish since when converting to HTML, SEO good practice is to have only one <h1>... </h1> in the page)

I also believe this is the "correct" way to structure a document. By the way there is an interesting article about the topic.

So, first question, is it possible to not mention that H1 in the table of contents? Make just like if it didn't exists at all (so don't number it too)

You can remove section numbering for a heading in the text and the toc by using the class unnumbered in your markdown document like so ## A Simple Unnumbered Heading {.unnumbered}

There is no native way to remove the heading completely from the table of contents (see jgm/pandoc#1762). There is however a Python filter that should do exactly that: https://github.com/chdemko/pandoc-latex-unlisted.

And, as you can see here below, my second question, I didn't understand how numbers are defined. My first h1 is number 0.1 and my first H2 is numbered 0.1.1; why this first 0 before?

The numbering starts at 0 because you don't have an h1 at the start of your document. I can reproduce this with the following document and the parameters --number-sections and --toc:

---
title: "Markdown Headings"
author: "Author"
date: "2019-09-02"
...

## A Simple H2 Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

## Another Simple H2 Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

There is no built-in pandoc option to shift all the heading levels one level up (so an h2 would become an h1). One could write a simple Lua filter to do that.

The recommended way in pandoc to write your heading levels like in the following markdown. This would give you correct results when converting to LaTeX where you want to start every section with \section{...}.

---
title: "Markdown Headings"
author: "Author"
date: "2019-09-02"
...

# A Simple H1 Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

# Another Simple H1 Heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Unfortunately it produces a <h1> for every #-heading in your document text wich goes against the "use only one h1 at the top in the whole document" rule. There has been a lengthy discussion about the topic at

1. Issue of --numbered-sections used with --base-header-level=2: produces 0.x.y jgm/pandoc#5071 and
2. Using # for section titles with --base-header-level=2 instead of using ## ? rstudio/distill#63.

[cavo789]

Many thanks Pascal for this very long and complete answer.

I've continue my test and I've used this markdown (based on your own readme.md), I've call the file test.md:

---
title: "Eisvogel"
author: "Author"
date: "2019-09-02"
titlepage: true
---
...
# Eisvogel

A clean **pandoc LaTeX template** to convert your markdown files to PDF or LaTeX. It is designed for lecture notes and exercises with a focus on computer science. The template is compatible with pandoc 2.

## Preview

## Installation

## Usage

## Examples

### Numbered Sections

### Syntax Highlighting with Listings

### Syntax Highlighting Without Listings

### Standalone LaTeX Document

### Changing the Document Language

### Typesetting a Book

### Example Images

## Credits

## License

By running the following command

pandoc test.md -o test.pdf --from markdown --template %APPDATA%\pandoc\template\eisvogel.tex --number-sections --toc

I get the following table of contents:

Except the heading one has been numbered, numbering is well starting to 1.

One of my question was is it possible to skip the H1 in the toc since I've only one H1 in my document and that text will be used as title in my first page (thanks to your titlepage yaml variable). Adding the H1 in the TOC is not needed since every chapter will thus start with 1.x as we can see on the image here above.

---
title: "Eisvogel"
titlepage: true
---

In my previous test, I've already tried {.unnumbered} but without success, see below. Yes, the H1 doesn't have a number but ... everything is thus starting at 0 now. Instead of heaving "1. Preview", "2. Installation", ... (my wish), I've now "0.1. Preview", so not numbered means "don't give a number" but still means "Use that heading in the TOC as a parent of headings with lower number".

I've now tried without the eisvogel template and I've the same problem so it's not related to the template but to my use / understanding of Pandoc.

I'll now continue tests by reading the links you've given. Perhaps should I create my own filter (should learn how to do this).

Once more, thank you Pascal both for the template and your very long answer here above.

[deem0n]

If you still see section numbering starting with 0.

The problem is with the default document class or classoption, which is set to scrbook by default. If you run pandoc with -V classoption=book you should get correct numbering. See this SO question.

As I understand scrbook requires first level sections to be \addchap{bla1}, but pandoc generates \section{bla1}

[Wandmalfarbe]

As one can see in jgm/pandoc#1762, pandoc added support for hiding sections in the table of contents like this:

Some Heading {.unnumbered .unlisted}

To quote the pandoc manual:

If the unlisted class is present in addition to unnumbered, the heading will not be included in a table of contents. (Currently this feature is only implemented for certain formats: those based on LaTeX and HTML, PowerPoint, and RTF.)