quarto-dev / quarto-dev/quarto-cli

number-sections does not number headers with GFM output format

Open
#8,113 10 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug markdown
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

Bug description

When rendering to GFM, number-sections: true does not add numbers to headers, only to the ToC.
It works as expected when rendering to HTML. I could not find an existing issue or a discussion in the Q&A, but maybe I've missed it.
Since number-sections is listed in the GFM options, I would expect it to work just like with HTML. If not possible, maybe the help should be adjusted.

Steps to reproduce
---
title: "test"
format: 
  gfm: default
toc: true
number-sections: true
---

# header1

# header2

## subheader2-1

## subheader2-2

Expected behavior

Same as with HTML:

---
title: "test"
format: 
  html: default
toc: true
number-sections: true
---

# header1

# header2

## subheader2-1

## subheader2-2

Actual behavior

The ToC is numbered but not the headers when rendering to GFM. Both are numbered when rendering to HTML.

Your environment

VScodium Version: 1.85.1 (user setup)
Release: 23348
Commit: 08e6c15293922dd53a864bb041be381322fee401
Date: 2023-12-14T20:44:42.949Z
Electron: 25.9.7
ElectronBuildId: undefined
Chromium: 114.0.5735.289
Node.js: 18.15.0
V8: 11.4.183.29-electron.0
OS: Windows_NT x64 10.0.19045

Quarto check output

[>] Checking versions of quarto binary dependencies...
Pandoc version 3.1.1: OK
Dart Sass version 1.55.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
Version: 1.3.450
Path: C:\Program Files\Quarto\bin
CodePage: 1252

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....OK
Version: 3.8.5
Path: C:/Users/calandra.RGZM/AppData/Local/Programs/Python/Python38/python
.exe
Jupyter: (None)

  Jupyter is not available in this Python installation.
  Install with py -m pip install jupyter

[>] Checking R installation...........OK
Version: 4.3.2
Path: C:/PROGRA1/R/R-431.2
LibPaths:
- C:/Users/calandra.RGZM/AppData/Local/R/win-library/4.3
- C:/Program Files/R/R-4.3.2/library
knitr: 1.45
rmarkdown: 2.25

[>] Checking Knitr engine render......OK

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by rendering the supplied minimal document in both GFM and HTML, then compare the heading output with the numbered table of contents. Trace the GFM handling of number-sections and determine whether the expected fix is numbered headings or an update to the GFM options help. Done means the behavior is consistent with the documented expectation or the limitation is clearly documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.