{{< pagebreak >}} prevents heading creation unless an empty line separate it from #

[p-vllnva]

Bug description

Possibly related to #12361.
In 1.7.23 and 1.7.24, shortcode immediately preceding a section ({{< pagebreak >}} in the example below) prevents heading creation.

If intentional, I think it should be communicated very clearly as it may break a lot of previously fine documents.

Steps to reproduce

---
title: "pagebreak did not behave like this in 1.6"
number-sections: true
---

# No problem here

{{< lipsum 2 >}}

{{< pagebreak >}}

# Still no problem here

{{< lipsum 2 >}}

{{ <pagebreak> }}
# This will not be recognized as a section

{{< lipsum 2 >}}

Actual behavior

Unless an entire empty line separates {{< pagebreak >}} from the next heading, it appears as raw text in the output.

Expected behavior

In 1.6, the headings were printed just fine in the output.

Your environment

• Positron: 2025.04.0 build 250
• Ubuntu 22.04

Quarto check output

Quarto 1.7.24
[✓] Checking environment information...
Quarto cache location: /home/peio/.cache/quarto
[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.6.3: OK
Dart Sass version 1.85.1: OK
Deno version 1.46.3: OK
Typst version 0.13.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 1.7.24
Path: /opt/quarto/bin

[✓] Checking tools....................OK
TinyTeX: (external install)
Chromium: 869685

[✓] Checking LaTeX....................OK
Using: TinyTex
Path: /home/peio/.TinyTeX/bin/x86_64-linux
Version: 2025

[✓] Checking Chrome Headless....................OK
Chrome: (not detected)

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

[✓] Checking Python 3 installation....OK
Version: 3.10.12
Path: /usr/bin/python3
Jupyter: (None)

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

[✓] Checking R installation...........OK
Version: 4.4.3
Path: /usr/lib/R
LibPaths:
- /home/peio/R/x86_64-pc-linux-gnu-library/4.4
- /usr/local/lib/R/site-library
- /usr/lib/R/site-library
- /usr/lib/R/library
knitr: 1.50
rmarkdown: 2.29

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

[mcanouil]

@p-vllnva your example is not reproducible as it lacks format.
Also, your example is using invalid shortcode such as the second pagebreak which is clearly wrong.
Please do use your example and ensure it is correct before opening bug reports.

Note that it's a pretty standard markdown guideline to have empty lines surrounding headings, code blocks/cells, and lists.
As not adding the empty lines means it's one single paragraph.

[cscheid]

As @mcanouil said, this isn't a bug. If you don't add a line break, then the contents are a single paragraph, and the pagebreak shortcode needs to operate as a standalone statement in a block. We should add a linting rule for this, but the behavior isn't a bug.

[p-vllnva]

Thank you for the answer.

@mcanouil Sorry, did this late last night. But consider the following example, the "problem" remains.

---
title: "Untitled"
number-sections: true
format: typst
---

# No problem here

{{< lipsum 2 >}}

{{< pagebreak >}}

# Still no problem here

{{< lipsum 2 >}}

{{< pagebreak >}}
# This will not be recognized as a section

{{< lipsum 2 >}}

@mcanouil @cscheid Ok I understand now that it is poor syntax but it is still the case that it used to produce a header in 1.6 and having read through the release notes, I could not find a reference to this change in behavior. It is breaking for documents with poor syntax that were saved by the older, more permissive versions (this is precisely how I came across this).

[cderv]

@p-vllnva the 1.6 behavior was possibly the bug.

A bisect shows the change in behavior happened for

• Don't add stray spaces in breakQuartoMd #11442 to solve Too many line breaks around shortcodes #11441

See this example

---
format: html
hello: world
---

1
{{< meta hello >}}
3

There should be newlines after the shortcode as the newlines are not in markdown.

In v1.7, the Markdown syntax from source is correctly respected.

The changelog entry is there:

quarto-cli/news/changelog-1.7.md

Line 179 in 31e496f

- ([#11441](https://github.com/quarto-dev/quarto-cli/issues/11441)): Don't add newlines around shortcodes during processing.

Hope it helps understand.

@cscheid maybe we could add a highlight item, or a breaking change entry (we don't have those yet) to warn users about this expected change.

[p-vllnva]

@cderv Very clear thank you very much for the time and attention.

[cscheid]

@p-vllnva the 1.6 behavior was possibly the bug.

Yes, that's correct.

@cscheid maybe we could add a highlight item, or a breaking change entry (we don't have those yet) to warn users about this expected change.

It's not a breaking change. It's a bug fix (truly), that happens to interact in an unfortunately-positive way with incorrect user code. We should have a changelog entry, and an explanation in the issue. Since GitHub adds a link to these comments in #11441, we don't need any additional changes.

[cderv]

It's not a breaking change. It's a bug fix (truly), that happens to interact in an unfortunately-positive way with incorrect user code. We should have a changelog entry, and an explanation in the issue. Since GitHub adds a link to these comments in #11441, we don't need any additional changes.

Thanks, I see how you consider this then.

I was talking about breaking change because a "working" document will now silently "break". The "working" part was not supposed to work in the first place, but it worked for the users. The fix is expected (I know it is truly a bug fix), but it still has impact for users.

From a developer's point of view, I agree this is not a breaking change, but from a user's point of view, this will be a breaking change.

So, I was thinking that even for this type of expected change, it is good to communicate and explain that this will happen and that anyone should check their document when using shortcodes.

Anyhow, I understand now that your consider the links in the changelog and issue descriptions to be sufficient documentation. I get that ! All good.

I may communicate on social channels about some of the changes that I consider impactful for users, like this one.

[cscheid]

I was talking about breaking change because a "working" document will now silently "break".

Notice the quotes you yourself put on that sentence!

From a developer's point of view, I agree this is not a breaking change, but from a user's point of view, this will be a breaking change.

I understand what you're saying, I really do: https://xkcd.com/1172/

But this situation has always been true for a number of Quarto documents and features, especially when it comes to handling Markdown, where there are no error messages. We should be careful about these kinds of communications in this particular situation, because we don't actually have a formal model of what should happen.

Do you think we should be documenting the impact of every Markdown commit we make on the highlights? I definitely do not think that. It will make our documentation worse. More documentation isn't always better! It's always a trade-off.

So, I was thinking that even for this type of expected change, it is good to communicate and explain that this will happen and that anyone should check their document when using shortcodes.

But we have communicated that. It's in the changelog, we even use the words "shortcode" and "newline". Adding a longer discussion about this in our docs would make it inconsistent with all the other changes we made that would also "break" some "working" documents from users.

This discussion is a good summary of why we need more error messages, and we need linting.

[mcanouil]

I think one of the reason there are issues with Markdown is because some Markdown parser/writer tried to be "smart" which lead users to not understand Markdown.

edit: A lot of users seem to believe the examples should behave the same way, but they should not in terms of paragraph (in addition to be hard to read when no empty lines are added).

---
format: html
---

# 1 => expected: text `My sentence starts ## here but ends here.`

My sentence starts
## here
but ends here.

# 2 => expected: text `My sentence starts`, a level 2 header `here`, text `but ends here.`

My sentence starts

## here

but ends here.

# 3 => expected: text `My sentence starts ## here` and text `but ends here.`

My sentence starts
## here

but ends here.

# 4 => expected: text `My sentence starts` and level 2 header `here but ends here.` (but Pandoc "adds" a softbreak)

My sentence starts

## here
but ends here.

Note that the last one should not really work or should be equivalent to ## here but ends here. but Pandoc treats it differently.

There are no markdown linters that do not have the "empty lines" rule (at least, I never find anywhere something saying "it's fine to not have empty lines")