Why do Level 2 headings become Level 1 in Typst?

[AlbertRapp]

Description

This Quarto file

---
format:
   typst:
      keep-typ: true
title: Bla bla
---

# Test 1

## test

produces the following Typst code:

#show: doc => article(
  title: [Bla bla],
  font: ("Inter Tight",),
  fontsize: 12pt,
  heading-family: ("Inter Tight",),
  heading-weight: 600,
  heading-color: rgb("#081c39"),
  heading-line-height: 0.85em,
  codefont: ("Sometype Mono",),
  toc_title: [Table of contents],
  toc_depth: 3,
  doc,
)

= Test 1
<test-1>
== test
<test>

But when I remove the Level 1 heading to get this Quarto file

---
format:
   typst:
      keep-typ: true
title: Bla bla
---

## test

I will have the ## line as Level 1 heading in Typst:

#show: doc => article(
  title: [Bla bla],
  font: ("Inter Tight",),
  fontsize: 12pt,
  heading-family: ("Inter Tight",),
  heading-weight: 600,
  heading-color: rgb("#081c39"),
  heading-line-height: 0.85em,
  codefont: ("Sometype Mono",),
  toc_title: [Table of contents],
  toc_depth: 3,
  doc,
)

= test
<test>

Why is this happening? This looks to be an intentional behavior. But I don't know why this is happening and I couldn't find a reference to that behavior in the docs.

[mcanouil]

This indeed seems intentional. Quarto does it, not Pandoc.

When a document has no level 1 heading, Quarto adds shift-heading-level-by: -1 by itself.
I first discovered this while working on https://github.com/mcanouil/quarto-offset-headings.

• For Typst it does always shift the heading.
• For PDF and LaTeX it does this only when number-sections is on and top-level-division is unset.
• For HTML it never does this.

The test is a Pandoc AST walk, not a regular expression. Quarto runs a small Lua filter over the markdown and asks one question: is there a Header with level == 1?

• quarto-cli/src/resources/filters/quarto-internals/leveloneanalysis.lua

  Lines 1 to 18 in d4cb49f

  	local found = false
  	function Header(el)
  	found = found or el.level == 1
  	return nil
  	end
  	function Pandoc(doc)
  	if found then
  	doc.blocks = pandoc.Blocks({
  	pandoc.Str("true")
  	})
  	else
  	doc.blocks = pandoc.Blocks({
  	pandoc.Str("false")
  	})
  	end
  	return doc
  	end

• quarto-cli/src/core/lib/markdown-analysis/level-one-headings.ts

  Lines 11 to 25 in d4cb49f

  	export async function hasLevelOneHeadings(markdown: string): Promise<boolean> {
  	// this is O(n * m) where n is the number of blocks and m is the number of matches
  	// we could do better but won't until we profile and show it's a problem
  	const path = pandocBinaryPath();
  	const filterPath = resourcePath(
  	join("filters", "quarto-internals", "leveloneanalysis.lua"),
  	);
  	const result = await execProcess({
  	cmd: path,
  	args: ["-f", "markdown", "-t", "markdown", "-L", filterPath],
  	stdout: "piped",
  	}, markdown);
  	return result.stdout?.trim() === "true";
  	}

The answer decides the shift. For Typst the only other condition is that you did not set shift-heading-level-by yourself, on the command line or in the format options.

• quarto-cli/src/format/typst/format-typst.ts

  Lines 96 to 105 in d4cb49f

  	// unless otherwise specified, pdfs with only level 2 or greater headings get their
  	// heading level shifted by -1.
  	const hasLevelOneHeadings = await hasL1Headings(markdown);
  	if (
  	!hasLevelOneHeadings &&
  	flags?.[kShiftHeadingLevelBy] === undefined &&
  	format.pandoc?.[kShiftHeadingLevelBy] === undefined
  	) {
  	pandoc[kShiftHeadingLevelBy] = -1;
  	}

This explains both of your files.
The first one has # Test 1, so the check returns true, no shift is added, and ## test stays == test.
The second one has only ## test, so the check returns false, the shift is added, and ## test becomes = test.

The equivalent code for PDF and LaTeX carries the extra conditions, which is why latex keeps your levels but typst does not.
Now, is this the actual issue? Should the behaviour be consistent? I can't really say as I don't really know all the rational behind this design choice.

• quarto-cli/src/format/pdf/format-pdf.ts

  Lines 298 to 315 in d4cb49f

  	// Don't shift the headings if we see any H1s (we can't shift up any longer)
  	const hasLevelOneHeadings = await hasL1Headings(markdown);
  	// pdfs with no other heading level oriented options get their heading level shifted by -1
  	if (
  	!hasLevelOneHeadings &&
  	autoShiftHeadings &&
  	(flags?.[kNumberSections] === true ||
  	format.pandoc[kNumberSections] === true) &&
  	flags?.[kTopLevelDivision] === undefined &&
  	format.pandoc?.[kTopLevelDivision] === undefined &&
  	flags?.[kShiftHeadingLevelBy] === undefined &&
  	format.pandoc?.[kShiftHeadingLevelBy] === undefined
  	) {
  	extras.pandoc = {
  	[kShiftHeadingLevelBy]: -1,
  	};
  	}

Two details are worth knowing.

The shift is a fixed -1, not a normalisation to level 1. A document whose shallowest heading is ### gives == deep in Typst, not = deep.

Pandoc applies shift-heading-level-by after every Lua filter. A filter can neither read the value nor cancel it, so a filter or extension that sets heading levels gets shifted again on top of its own output (that's where I got bitten for my Lua filter).

How to turn the heading shift off specificaly for Typst

Set shift-heading-level-by yourself to trigger the gate.
Quarto skips its own shift when the option is present, whatever the value:

format:
  typst:
    shift-heading-level-by: 0

quarto render doc.qmd --to typst --shift-heading-level-by 0 has the same effect.
Adding a level 1 heading also works, because the check then returns true.

[cderv]

Why is this happening? This looks to be an intentional behavior. But I don't know why this is happening and I couldn't find a reference to that behavior in the docs.

For the context of the design, I think we do this by design because this is better practice to have H1 header in all documents structure. This is valid of HTML but also for PDF

And this is even more ture with Accessibility validation. With verapdf on a PDF produce using typst with Pandoc

<errorMessage>Heading level 1 is skipped in a descending sequence of header levels</errorMessage>

---
title: Bla bla
---

## test

This is ISO 14289-1:2014 claude 7.4.2

For documents that are not strongly structured, as described in ISO 32000-1:2008, 14.8.4.3.5, heading tags shall be used as follows: () If any heading tags are used, H1 shall be the first. () A document may use more than one instance of any specific tag level. For example, a tag level may be repeated if document content requires it. () If document semantics require a descending sequence of headers, such a sequence shall proceed in strict numerical order and shall not skip an intervening heading level. () A document may increment its heading sequence without restarting at H1 if document semantics require it

So in Quarto we do enforce by default this H1 as results of structure even is ## is used - and AFAIR this is done because ## is often use as main headers by some users.

For the technical implementation and how to opt out this is shared ☝️

[mcanouil]

FYI, that's not a standardisation to level 1 that is done, see the behaviour with the example below:

---
title: Bla bla
---

### test

[cderv]

I know - thanks for clarifying though. We only do that for ## when no # because we found by experience this was common to have document with only ## as headers. It is way more common to have documents with only ###