Skip to content

fix: fence code blocks longer than the backticks they contain - #26

Merged
leonardosalasd merged 10 commits into
mainfrom
chore/v2.2.0
Nov 13, 2026
Merged

leonardosalasd merged 10 commits into
mainfrom
chore/v2.2.0

Conversation

@leonardosalasd

Copy link
Copy Markdown
Owner

No description provided.

A block holding its own fence, which is ordinary in a file that documents
Markdown, failed the whole build with `unclosed raw text`. The emitted Typst
always opened the block with three backticks, so the first run inside it closed
the block early and left the rest of the document as stray markup.

Typst ends raw text at a run matching the one that opened it, exactly as
Markdown does, so the fence now grows one backtick past the longest run in the
code. Blocks that contain none are written as before.
Two kinds of link reached the PDF as something a reader cannot follow, both
reported on macOS as "The application can't be opened. -50".

`[text](#a-heading)` was written out as a link to a path named `#a-heading`, so
the reader looked for a file beside the PDF. Headings now carry a label, named
the way GitHub names its anchors and made unique when a title repeats, and a
link whose target is one of them jumps inside the document. Typst refuses a link
to a label that is not there, so the labels are collected before rendering
rather than hoped for; an anchor matching no heading now drops the link and says
so, instead of producing one that errors when clicked.

`[text](example.com)` has no scheme, so it is a relative path to Markdown and
the reader treated it as one. A target that is plainly a host, and is not a file
this build can see, now gets `https://`. Paths, written schemes, and anything
ending in a file extension are untouched.
A reference whose definition is missing is not a compiler error. mistune leaves
it alone, so the literal `[^1]` reaches the page looking like a typo, and
--dry-run reported the file as clean.

The check runs over the whole source before judging, since a definition is
allowed to sit above its reference, and skips fenced code the way the other
checks do.
A portrait photograph scaled to the full text block cannot share a page with
anything, so the sentence announcing it stayed behind on the page before, above
a column of empty paper. A document of steps, each a line of text and a
screenshot, came out as alternating pages of text and picture.

Two halves to this. A picture is now allowed 88% of the text height rather than
all of it, which leaves room for a few lines beside it, and a paragraph
immediately followed by one is asked to travel with it. Sticky alone would not
have helped: Typst drops the request when the pair cannot fit together anywhere.

The same treatment goes to an alert's label, which a page break could strand at
the bottom of a page away from the text it labels.
A README that centres its banner with `<div align="center">` lost the
arrangement on the way to the PDF, because raw HTML blocks were read for images
and otherwise dropped.

The opening tag and the closing one usually arrive as separate blocks, with the
Markdown between them parsed on its own, so matching them up inside one piece
of HTML does not work. They are emitted where they are found instead, opening
and closing a Typst #align around whatever the document put between them, and
anything left open at the end of the file is closed before the Typst goes out.
Two things a folder of Markdown could not do.

A folder with notes in it but no README refused to build at all, which is a
strange answer when the file to convert is sitting right there. The search now
falls through to the first .md the folder lists, after the manifest and the
README it already looked for, and a path to a folder is accepted where a file
was.

And a folder of unrelated documents had no way to say "each of these". The
multi-file support it already has assembles pieces into one PDF, which is the
opposite of what three separate reports want. --all gives each file its own
PDF, and refuses --output and --watch, neither of which means anything when the
run produces more than one document.
…contents

Three things a document could not ask for without writing its own template.

--no-toc leaves out the generated table of contents, and the page break that
belongs to it, for a file that already carries an index of its own. --margin
takes a word for the usual amounts, tight, normal or wide, or a measurement
such as 2cm when the amount matters. --align decides how body text sits in the
measure, and reaches paragraphs only, so headings and the cover keep the
arrangement the template designed for them.

All three fall back to what the template does when nobody asks, which is what
keeps report wide and minimal ragged-right. They can be set in front matter and
in the project file like every other option, and only the bundled templates are
told about them: a template of someone else's keeps the contract it was written
against.
The project page renders the README outside the repository, where a relative
path resolves to nothing, so every screenshot on PyPI is a broken image.

Rewriting the paths in the repository would be the simpler fix and the wrong
one: relative paths are what let doc-engine embed its own screenshots when it
builds this file, which is the demo the README is making. The publish job now
rewrites them to raw GitHub in its checkout, so the copy that ships to PyPI
carries absolute URLs and the repository keeps working as it does.
Three behaviours shipped without a line explaining them: a link to a heading in
the same file, a web address written without its scheme, and the fact that a
tall picture now stops short of the full page so the text introducing it can
stay beside it. The error-checking row also still described a narrower check
than the one that runs.

@leonardosalasd leonardosalasd left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK

@leonardosalasd
leonardosalasd merged commit 7cd1c78 into main Nov 13, 2026
21 checks passed
@leonardosalasd
leonardosalasd deleted the chore/v2.2.0 branch November 13, 2026 00:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant