Parse `#pagebreak()` in Typst

[RayBB]

Explain the problem.

pagebreak.typ:

First Page
#pagebreak()
Second Page

Running: pandoc pagebreak.typ -f typst -t pdf -s -o pagebreak.pdf

The output is missing the page break in PDF. docx also doesn't show it but pandoc to docx isn't supporting pagebreaks by default.

I would expect the content after the #pagebreak() to start on a new page.

Related typst docs: https://typst.app/docs/reference/layout/pagebreak/

Note: Typst supports two parameters:

pagebreak(
weak: bool, to: none | str,
) -> content 

However, for a first version it would probably be fine to ignore those options and give a warning if they're seen.

Pandoc version? MacOS and commit: 22ff5a8909dc8ce4f9d8a7dbdb97dcd657f9ebb0

[jgm]

The pandoc document model has no concept of page breaks.

Typst pagebreak is currently just ignored. We could have it parse as an empty Div with a pagebreak class, perhaps, or a HorizontalRule. (these would then allow you to use a filter to substitute something more appropriate for your output format.)

[RayBB]

Based on some quick searching it seems that LaTeX, PDF, DOCX, ODT, RTF, and Typst are the ones that support page breaks.

I think it would be worthwhile to support them, especially if it's not a big effort but also putting a warning if a page break is detected but won't be used would be nice. Also perhaps a note in the documentation about it.

Seems that others have tried to build something to fill the gap but it hasn't been updated in 6 years. https://github.com/pandocker/pandoc-docx-pagebreak-py

[tarleb]

I've updated the issue title to limit the scope to the Typst reader. See #1934 for the more general challenge of adding full support for pagebreaks to pandoc.

[RayBB]

Thanks @tarleb, given my new understanding. I went ahead and updated the description as well to reflect the issue better.

Do you think this would be a good first issue? Spelunking the codebase with AI a bit I don't see a ton of examples of how this works but it seems like it could be something like:

-- existing handlers...
  ,("pad", \_ _ fields ->  -- ignore paddingy
      getField "body" fields >>= pWithContents pBlocks)
  ,("pagebreak", \_ _ -> pure $ B.rawBlock "latex" "\\newpage")
  ]

[tarleb]

Yes, that's very close. Just the result should be updated, as this isn't raw LaTeX. There also should be three underscores, not two.

Using B.horizontalRule would make sense, possibly placed in a wrapper Div with a class to mark the rule as a pagebreak. See jgm's ideas above.

A PR would be most welcome!

[RayBB]

@tarleb I've never written haskell before. And still haven't written haskell (AI did) but I read a lot more haskell and think I have a working PR here: #11126

I skimmed the contributor guidelines and it's a lot so apologies if I missed a step.