From 1c453a6daa8a42c74a70e80a885a51e1ea4b4b83 Mon Sep 17 00:00:00 2001 From: Leonardo Salas Date: Thu, 12 Nov 2026 15:11:03 -0600 Subject: [PATCH 01/10] fix: fence code blocks longer than the backticks they contain 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. --- doc_engine/converter.py | 6 +++++- tests/test_converter.py | 10 ++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/doc_engine/converter.py b/doc_engine/converter.py index 8480825..4b620f4 100644 --- a/doc_engine/converter.py +++ b/doc_engine/converter.py @@ -47,6 +47,7 @@ _REMOTE = re.compile(r"^(?:[a-z][a-z0-9+.-]*:)?//", re.IGNORECASE) _UNSAFE = re.compile(r"[^A-Za-z0-9._-]") _FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})") +_BACKTICKS = re.compile(r"`+") _SETEXT_H1 = re.compile(r"^ {0,3}=+[ \t]*$") # Pandoc-style [@key] survives escaping as \[\@key\]; restore it as a Typst @key. @@ -332,7 +333,10 @@ def block_code(self, token: dict, state: Any) -> str: code = token["raw"] if lang and diagrams.is_diagram(lang): return self._render_diagram(lang, code) - return f"\n```{lang}\n{code}```\n\n" + # Typst closes raw text at the first run of backticks that matches the + # one it opened with, so code holding its own fence needs a longer one. + fence = "`" * max(3, len(max(_BACKTICKS.findall(code), key=len, default="")) + 1) + return f"\n{fence}{lang}\n{code}{fence}\n\n" def _render_diagram(self, language: str, source: str) -> str: svg = diagrams.render(language, source) diff --git a/tests/test_converter.py b/tests/test_converter.py index 0470e1a..327b6e8 100644 --- a/tests/test_converter.py +++ b/tests/test_converter.py @@ -109,6 +109,16 @@ def test_code_block(self) -> None: result = convert(md) assert "```python" in result + def test_code_block_holding_its_own_fence(self) -> None: + md = '````python\nif line.startswith("```"):\n pass\n````' + result = convert(md) + assert result.startswith("\n````python\n") + assert result.endswith("````\n\n") + + def test_fence_grows_past_the_longest_run(self) -> None: + md = "`````\na ```` b\n`````" + assert convert(md).startswith("\n`````\n") + def test_link(self) -> None: result = convert("[click here](https://example.com)") assert '#link("https://example.com")' in result From 9e768c2add988be601c7ca779dba8b89422059bf Mon Sep 17 00:00:00 2001 From: Leonardo Salas Date: Thu, 12 Nov 2026 15:14:56 -0600 Subject: [PATCH 02/10] fix: make links to headings and bare hosts open 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. --- doc_engine/converter.py | 85 ++++++++++++++++++++++++++++++++++++++--- tests/test_converter.py | 42 +++++++++++++++++++- 2 files changed, 120 insertions(+), 7 deletions(-) diff --git a/doc_engine/converter.py b/doc_engine/converter.py index 4b620f4..c81e78a 100644 --- a/doc_engine/converter.py +++ b/doc_engine/converter.py @@ -15,6 +15,7 @@ from html.parser import HTMLParser from pathlib import Path from typing import Any +from urllib.parse import unquote import mistune @@ -46,6 +47,14 @@ _INLINE_MATH = r"\$(?!\s)(?P(?:[^$\\\n]|\\.)+?)(? int: md.inline.register("inline_math", _INLINE_MATH, parse_inline, before="link") +def _plain_text(tokens: list[dict]) -> str: + return "".join( + _plain_text(token["children"]) if "children" in token else token.get("raw", "") + for token in tokens + ) + + +def _slug(text: str) -> str: + """The anchor a heading answers to, named the way GitHub names it.""" + return _SLUG_STRIP.sub("", text.strip().lower()).replace(" ", "-").strip("-") + + def _css_length(value: str | None) -> str | None: """A Typst length for an HTML width or height written in pixels. @@ -179,6 +200,10 @@ def __init__( self._anchors = {Path(k).resolve(): v for k, v in (anchors or {}).items()} self.warnings: list[str] = [] self._footnotes: dict[str, str] = {} + # Labels for this document's own headings, in the order they appear, and + # the slugs that reach them, so `[text](#a-heading)` lands somewhere. + self._heading_labels: list[str] = [] + self._heading_targets: dict[str, str] = {} self._asset_names: dict[str, str] = {} self._cut_pieces: dict[str, list[str]] = {} self.assets: dict[str, str] = {} @@ -203,15 +228,41 @@ def link(self, token: dict, state: Any) -> str: anchor = self._anchor_for(url) if anchor: return f"#link(<{anchor}>)[{children}]" - return f'#link("{url}")[{children}]' + if url.startswith("#"): + # Linking it anyway produces a link to a file that is not there, and + # readers report that as an error rather than as a dead link. + self.warnings.append(f"no heading matches {url}") + return children + return f'#link("{self._web_url(url)}")[{children}]' + + def _web_url(self, url: str) -> str: + """Give a bare host the scheme a PDF reader needs in order to open it. + + `[text](example.com)` is a relative path as far as Markdown is + concerned, so the reader looks for a file sitting beside the PDF and + reports that it cannot open it. A target that is plainly a host, and not + a file this build can see, is a web address the author wrote in short. + """ + if _SCHEME.match(url) or url.startswith(("/", "#", "./", "../")): + return url + host = _HOST.match(url) + if not host or _FILE_SUFFIX.search(host.group(0)): + return url + if self._base_dir is not None and (self._base_dir / url).exists(): + return url + return f"https://{url}" def _anchor_for(self, url: str) -> str | None: - """An anchor when this link points at another file in the same build. + """An anchor when this link points somewhere inside the same build. - Linking to a sibling document is normal in a folder of Markdown, but the - reader of the PDF has no such file, so the link jumps within the document - instead. + Linking to a heading, or to a sibling document in a folder of Markdown, + is normal to write and meaningless to a reader holding only the PDF, so + both jump within the document instead. """ + if url.startswith("#"): + # The parser percent-encodes what it reads, so an accented heading + # arrives here unrecognizable unless it is decoded first. + return self._heading_targets.get(_slug(unquote(url[1:]))) if not self._anchors or self._base_dir is None or _REMOTE.match(url): return None target = url.split("#", 1)[0] @@ -325,7 +376,28 @@ def paragraph(self, token: dict, state: Any) -> str: def heading(self, token: dict, state: Any) -> str: level = token["attrs"]["level"] body = _render_children(self, token, state) - return f"\n{'=' * level} {body}\n\n" + label = self._heading_labels.pop(0) if self._heading_labels else "" + return f"\n{'=' * level} {body}{f' <{label}>' if label else ''}\n\n" + + def load_headings(self, tokens: list[dict]) -> None: + """Name every heading before rendering, so links can be resolved. + + Typst refuses a link to a label that does not exist, so a target has to + be known to be there before one is written. + """ + taken: dict[str, int] = {} + for token in tokens: + if token.get("type") != "heading": + continue + slug = _slug(_plain_text(token.get("children", []))) + if not slug: + slug = f"heading-{len(self._heading_labels) + 1}" + seen = taken.get(slug, 0) + taken[slug] = seen + 1 + unique = slug if not seen else f"{slug}-{seen}" + label = f"{self._namespace}h-{unique}" + self._heading_labels.append(label) + self._heading_targets.setdefault(unique, label) def block_code(self, token: dict, state: Any) -> str: info = token.get("attrs", {}).get("info", "") or "" @@ -513,6 +585,7 @@ def _parse_markdown(markdown: str) -> tuple[list[dict], Any]: def _render_markdown_tokens(renderer: TypstRenderer, tokens: list[dict], state: Any) -> str: + renderer.load_headings(tokens) renderer.load_footnotes(tokens, state) return _CITATION.sub(r"@\1", renderer.render_tokens(tokens, state)) diff --git a/tests/test_converter.py b/tests/test_converter.py index 327b6e8..aa598bf 100644 --- a/tests/test_converter.py +++ b/tests/test_converter.py @@ -145,6 +145,43 @@ def test_empty_input(self) -> None: assert convert("") == "" +class TestLinkTargets: + def test_bare_host_gets_a_scheme(self) -> None: + assert '#link("https://leonardosalas.dev")' in convert("[me](leonardosalas.dev)") + assert '#link("https://example.com/a/b")' in convert("[a](example.com/a/b)") + + def test_files_and_paths_are_left_alone(self) -> None: + for target in ("README.md", "docs/guide.md", "./notes.txt", "/abs/path"): + assert f'#link("{target}")' in convert(f"[x]({target})") + + def test_written_schemes_are_left_alone(self) -> None: + assert '#link("mailto:a@b.com")' in convert("[m](mailto:a@b.com)") + assert '#link("https://x.dev")' in convert("[s](https://x.dev)") + + def test_a_local_file_is_not_mistaken_for_a_host(self, tmp_path) -> None: + (tmp_path / "data.sqlite").write_text("x") + result = convert("[db](data.sqlite)", base_dir=tmp_path) + assert '#link("data.sqlite")' in result + + def test_headings_are_labelled_and_reachable(self) -> None: + result = convert("## Mi Sección\n\n[ir](#mi-sección)") + assert "== Mi Sección " in result + assert "#link()[ir]" in result + + def test_repeated_headings_get_their_own_anchors(self) -> None: + result = convert("## Setup\n\n## Setup\n\n[a](#setup)\n\n[b](#setup-1)") + assert "" in result + assert "" in result + assert "#link()[a]" in result + assert "#link()[b]" in result + + def test_an_anchor_with_no_heading_warns_instead_of_linking(self) -> None: + result = convert_document("[nope](#missing)") + assert "#link" not in result.body + assert "nope" in result.body + assert result.warnings == ["no heading matches #missing"] + + class TestTaskLists: def test_checked_and_unchecked_render_boxes(self) -> None: result = convert("- [x] done\n- [ ] todo\n") @@ -353,7 +390,10 @@ def test_body_keeps_its_formatting(self) -> None: class TestFormattedTitle: def test_title_uses_body_plugins_and_citations(self) -> None: for inline in ("~~struck~~ title", "The $x^2$ theorem", "Result [@smith2020]"): - assert extract_title_markup(f"# {inline}") == convert(f"# {inline}").strip()[2:] + # A body heading carries the anchor links reach it by; a title, + # which nothing links to, does not. + heading = convert(f"# {inline}").strip()[2:].rsplit(" <", 1)[0] + assert extract_title_markup(f"# {inline}") == heading def test_plugin_metadata_is_plain(self) -> None: assert extract_title("# ~~Old~~ $x^2$ result") == "Old x^2 result" From e6728350f58cdd0ff7e6959078ddd722de324975 Mon Sep 17 00:00:00 2001 From: Leonardo Salas Date: Thu, 12 Nov 2026 15:40:33 -0600 Subject: [PATCH 03/10] fix: warn about footnote references with no definition 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. --- doc_engine/linter.py | 31 ++++++++++++++++++++++++++++++- tests/test_linter.py | 30 ++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/doc_engine/linter.py b/doc_engine/linter.py index 0654fe5..310bb1b 100644 --- a/doc_engine/linter.py +++ b/doc_engine/linter.py @@ -10,6 +10,18 @@ _LINK = re.compile(r"(!?)\[(?P[^\]]*)\]\((?P[^)]*)\)") _FENCE = re.compile(r"^\s*(```|~~~)") +_FOOTNOTE_DEF = re.compile(r"^ {0,3}\[\^(?P