diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml index 36b9553..e765d87 100644 --- a/.github/workflows/publish-pypi.yml +++ b/.github/workflows/publish-pypi.yml @@ -22,6 +22,23 @@ jobs: - name: Install build tools run: python -m pip install --upgrade pip build twine + # PyPI renders the README on its own page, where a relative path resolves + # to nothing and every screenshot comes out broken. The repository keeps + # the relative paths, because that is what lets doc-engine embed its own + # images when it builds this file, and the copy that ships points at raw + # GitHub instead. + - name: Point README images at raw GitHub + run: | + python - <<'PY' + import pathlib, re + raw = "https://raw.githubusercontent.com/${{ github.repository }}/main/" + readme = pathlib.Path("README.md") + text = readme.read_text(encoding="utf-8") + text = re.sub(r'(]*\ssrc=")(?!https?://)(assets/)', rf'\1{raw}\2', text) + text = re.sub(r'(!\[[^\]]*\]\()(?!https?://)(assets/)', rf'\1{raw}\2', text) + readme.write_text(text, encoding="utf-8") + PY + - name: Build package (sdist & wheel) run: python -m build diff --git a/README.md b/README.md index 6e4cbab..561e2df 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ That's it. Zero configuration required. | **Page Sizes** | A4 by default, plus A3–A6, ISO/JIS B5, and US letter, legal, and tabloid. | | **Project Config** | A `.doc-engine.toml` keeps a team's defaults out of every document. | | **Rich Markdown** | Embeds local images, renders GitHub task lists as real checkboxes, and turns `[^1]` footnotes into native Typst footnotes. | -| **Error Checking** | Reports source problems with line and column before compiling. A `--dry-run` mode runs the check on its own. | +| **Error Checking** | Reports source problems — empty links, unclosed fences, footnotes with no definition — with line and column before compiling. A `--dry-run` mode runs the check on its own. | | **Non-Destructive** | Never overwrites an existing PDF — writes `report (1).pdf`, `report (2).pdf`, … unless you pass `--force`. | | **Premium Typography** | Font stacks that end in a font Typst ships, so a document looks the same in a bare container as on a laptop. | | **Pure Python** | No external binaries required (no Pandoc, no LaTeX). Ships as a single `pip install`. | @@ -152,7 +152,7 @@ doc-engine --help Show all commands and flags | Flag | Default | Description | |---|---|---| -| `INPUT_FILE` | auto-detect `README.md` | Path to the Markdown file to convert. | +| `INPUT_FILE` | auto-detect | Path to the Markdown file to convert, or a folder to look in. Left out, the build takes a `doc-engine.md` manifest, then a `README.md`, then the first `.md` in the folder alphabetically. | | `-o, --output` | `_doc.pdf` | Output PDF path. | | `-t, --title` | first `# heading` | Document title override. | | `-s, --subtitle` | none | Subtitle shown under the title on the cover. | @@ -161,6 +161,9 @@ doc-engine --help Show all commands and flags | `--template` | `academic` | A built-in layout (`academic`, `article`, `book`, `minimal`, `modern`, `report`, `technical`) or a path to your own `.typ` file. | | `--accent` | template default | Accent color as a hex value (`#2563eb`) or a name (`blue`, `teal`, `rose`, ...). | | `--paper` | `a4` | Page size: `a3`–`a6`, `iso-b5`, `jis-b5`, `us-letter`, `us-legal`, `us-tabloid`. | +| `--margin` | template default | Page margin: `tight`, `normal`, `wide`, or a measurement such as `2cm`, `0.8in`, `18mm`. | +| `--align` | template default | How body text sits in the measure: `justify`, `left`, `right`, `center`. | +| `--no-toc` | off | Leave out the generated table of contents, for a document that carries its own. | | `--bib` | auto-detect `refs.bib` | Path to a custom `.bib` file for the bibliography. | | `--pdf-standard` | off | Write an archival PDF/A file: `a-2b` or `a-3b`. | | `--code-theme` | Typst default | Syntax highlighting theme: `github`, `solarized`, `monochrome`, or a path to a `.tmTheme`. | @@ -170,6 +173,7 @@ doc-engine --help Show all commands and flags | `--dry-run` | off | Check the Markdown for errors and exit without writing a PDF. | | `-w, --watch` | off | Rebuild automatically whenever the source file changes. | | `-f, --force` | off | Overwrite the output file instead of writing a numbered copy. | +| `--all` | off | Build every Markdown file in the folder into its own PDF, rather than one document. | | `--open` | off | Open the PDF after it is generated. | Any flag can also be set in the front matter (see below); a flag on the command line always wins. @@ -246,7 +250,7 @@ accent: teal ``` Supported keys: `title`, `subtitle`, `author`, `date`, `template`, `accent`, -`paper`, and `bib`. A flag passed on the command line overrides the matching front-matter key, +`paper`, `margin`, `align`, `toc`, and `bib`. A flag passed on the command line overrides the matching front-matter key, which in turn overrides the auto-detected value. --- @@ -370,6 +374,18 @@ That resolves to the place where `model.md` was merged in. Links to anything outside the build — a URL, a file that is not part of the manifest — are left exactly as they are. +A link to a heading in the same file works the same way, using the anchor +GitHub would give it: + +```markdown +Back to [the overview](#overview). +``` + +A target that is plainly a web address but was written without a scheme, as in +`[my site](example.com)`, is given `https://`. Markdown reads such a target as +a relative path, which in a PDF means a file sitting beside it, and readers +report that as an error rather than opening anything. + --- @@ -446,6 +462,9 @@ Every key it understands: | `branding` | `false` hides the `doc-engine` attribution | | `code_theme` | `github`, `solarized`, `monochrome`, or a path to a `.tmTheme` | | `pdf_standard` | `a-2b` or `a-3b` | +| `margin` | `tight`, `normal`, `wide`, or a measurement such as `2cm` | +| `align` | `justify`, `left`, `right`, or `center` | +| `toc` | `false` leaves out the generated table of contents | | `tall_images` | `fit` or `split` | | `fetch_images` | `true` downloads images linked by URL | @@ -457,7 +476,9 @@ document is built. ## Large Images A picture that does not fit the text block is scaled down until it does, so -nothing is ever clipped. For a tall diagram — a top-down flowchart, a long +nothing is ever clipped. It stops a little short of the full height of the +page, which leaves room for the sentence that introduces it to stay on the same +page rather than being stranded above a column of white space. For a tall diagram — a top-down flowchart, a long schema — scaling it onto one page can leave it unreadable, so it can be cut across pages at full size instead: @@ -609,6 +630,7 @@ The converter module parses Markdown using [`mistune`](https://github.com/leptur | `text[^1]` | `#footnote[...]` | | `![alt](local.png)` | `#image("local.png")` | | `` | Embedded image, using the same path as Markdown images | +| `
` | `#align(center)[...]` around everything up to the closing tag | | `> blockquote` | `#block(...)` | | `---` | `#line(...)` | @@ -747,6 +769,7 @@ docker run --rm -v "$PWD:/workspace" ghcr.io/leonardosalasd/doc-engine-cli build - [x] Footnotes (`[^1]`) - [x] Local images, and remote ones with `--fetch-images` - [x] Raw HTML `` tags (inline or block), sized by `width` and `height` in pixels +- [x] `align` on a raw HTML block (`
`, `
`) - [x] Math blocks (LaTeX `$…$` and `$$…$$`) - [x] Mermaid and SVG diagram blocks - [x] GitHub alerts (`> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`) diff --git a/doc_engine/__init__.py b/doc_engine/__init__.py index 0d16dc6..2750a01 100644 --- a/doc_engine/__init__.py +++ b/doc_engine/__init__.py @@ -1,3 +1,3 @@ """doc-engine-cli: Modern Markdown to Typst compiler.""" -__version__ = "2.1.0" +__version__ = "2.2.0" diff --git a/doc_engine/cli.py b/doc_engine/cli.py index c497353..5362b04 100644 --- a/doc_engine/cli.py +++ b/doc_engine/cli.py @@ -90,6 +90,14 @@ def _find_file(directory: Path, candidates: tuple[str, ...]) -> Path | None: return None +def _markdown_files(directory: Path) -> list[Path]: + """Every Markdown file in a folder, in the order a file listing shows them.""" + return sorted( + (path for path in directory.glob("*.md") if path.is_file()), + key=lambda path: path.name.lower(), + ) + + def _accent_hex(value: str) -> str | None: key = value.strip().lower() if key in _NAMED_ACCENTS: @@ -208,6 +216,24 @@ def cli(ctx: click.Context) -> None: type=click.Choice(PAPER_SIZES, case_sensitive=False), help=f"Page size (default: {DEFAULT_PAPER}).", ) +@click.option( + "--margin", + default=None, + help="Page margin: tight, normal, wide, or a measurement such as 2cm.", +) +@click.option( + "--align", + "text_align", + default=None, + type=click.Choice(settings.ALIGNMENTS, case_sensitive=False), + help="How body text sits in the measure (default: whatever the template does).", +) +@click.option( + "--no-toc", + "no_toc", + is_flag=True, + help="Leave out the generated table of contents.", +) @click.option("--bib", default=None, help="Path to a custom .bib file.") @click.option( "--no-branding", "no_branding", is_flag=True, help="Hide the doc-engine attribution in the PDF." @@ -258,6 +284,12 @@ def cli(ctx: click.Context) -> None: is_flag=True, help="Overwrite the output file instead of writing a new one.", ) +@click.option( + "--all", + "build_all", + is_flag=True, + help="Build every Markdown file in the folder into its own PDF.", +) @click.option("--open", "open_pdf", is_flag=True, help="Open the PDF after generation.") def build( input_file: str | None, @@ -269,6 +301,9 @@ def build( template: str | None, accent: str | None, paper: str | None, + margin: str | None, + text_align: str | None, + no_toc: bool, bib: str | None, no_branding: bool, pdf_standard: str | None, @@ -278,6 +313,7 @@ def build( dry_run: bool, watch: bool, force: bool, + build_all: bool, open_pdf: bool, ) -> None: """Convert a Markdown file into a professional PDF document.""" @@ -299,27 +335,56 @@ def build( if project: console.print(f" [dim]Settings:[/dim] [cyan]{config.CONFIG_NAME}[/cyan]") - if input_file: - input_path = Path(input_file) + folder = Path(input_file) if input_file and Path(input_file).is_dir() else cwd + + if build_all: + if watch: + console.print("[bold red]Error:[/bold red] --all cannot be combined with --watch.") + raise SystemExit(1) + if output: + console.print( + "[bold red]Error:[/bold red] --all writes one PDF per file, so --output " + "has nothing to name." + ) + raise SystemExit(1) + targets = _markdown_files(folder) + if not targets: + console.print(f"[bold red]Error:[/bold red] No Markdown files in {folder}.") + raise SystemExit(1) + elif input_file and folder == cwd: + targets = [Path(input_file)] else: - input_path = manifest.find(cwd) or _find_file(cwd, _README_CANDIDATES) - if not input_path: + found = ( + manifest.find(folder) + or _find_file(folder, _README_CANDIDATES) + # A folder of notes rarely has a README, and refusing to build one + # is less useful than picking the file a listing would show first. + or next(iter(_markdown_files(folder)), None) + ) + if not found: console.print( "[bold red]Error:[/bold red] Nothing to build in this directory.\n" - "[dim]Add a README.md, write a doc-engine.md manifest, " + "[dim]Add a Markdown file, write a doc-engine.md manifest, " "or name a file to convert.[/dim]" ) raise SystemExit(1) - console.print(f" [dim]Auto-detected:[/dim] [cyan]{input_path.name}[/cyan]") + targets = [found] + console.print(f" [dim]Auto-detected:[/dim] [cyan]{found.name}[/cyan]") - if not input_path.exists(): - console.print(f"[bold red]Error:[/bold red] File not found — {input_path}") - raise SystemExit(1) + for target in targets: + if not target.exists(): + console.print(f"[bold red]Error:[/bold red] File not found — {target}") + raise SystemExit(1) + + input_path = targets[0] if dry_run: - issues = lint(input_path.read_text(encoding="utf-8")) + issues = [] + for target in targets: + found_here = lint(target.read_text(encoding="utf-8")) + _print_issues(found_here, str(target)) + issues.extend(found_here) if issues: - _print_issues(issues, str(input_path)) errors = sum(1 for i in issues if i.severity == "error") console.print(f"\n[dim]{errors} error(s), {len(issues) - errors} warning(s).[/dim]") raise SystemExit(1 if errors else 0) @@ -329,6 +394,9 @@ def build( flags = { "template": template, "paper": paper, + "margin": margin, + "text_align": text_align, + "no_toc": no_toc, "accent": accent, "author": author, "bib": bib, @@ -339,11 +407,11 @@ def build( "tall_images": tall_images, } - output_path = Path(output) if output else Path(f"{input_path.stem}_doc.pdf") - if not force: - output_path = _unique_path(output_path) + def destination(source: Path) -> Path: + path = Path(output) if output else Path(f"{source.stem}_doc.pdf") + return path if force else _unique_path(path) - def run() -> bool: + def run(input_path: Path, output_path: Path) -> bool: collected: manifest.Manifest | None = None if manifest.is_manifest(input_path): try: @@ -468,6 +536,9 @@ def run() -> bool: paper=chosen.paper, pdf_standard=chosen.pdf_standard, code_theme=chosen.code_theme, + toc=chosen.toc, + margin=chosen.margin, + text_align=chosen.text_align, ) except Exception as exc: message = getattr(exc, "message", None) or str(exc) @@ -487,14 +558,27 @@ def run() -> bool: ) return True - ok = run() + # Named once per file: a rebuild under --watch has to overwrite what it + # wrote a moment ago rather than number a new copy beside it. + outputs = {target: destination(target) for target in targets} + built: list[Path] = [] + failed = False + for target in targets: + if run(target, outputs[target]): + built.append(outputs[target]) + else: + failed = True - if open_pdf and ok: - _open_file(str(output_path)) + if len(targets) > 1: + console.print(f"\n[dim]{len(built)} of {len(targets)} file(s) built.[/dim]") + + if open_pdf: + for path in built: + _open_file(str(path)) if watch: - _watch(input_path, run) - elif not ok: + _watch(input_path, lambda: run(input_path, outputs[input_path])) + elif failed: raise SystemExit(1) @@ -575,6 +659,9 @@ def info(as_json: bool) -> None: "pdf_standards": list(PDF_STANDARDS), "accents": _NAMED_ACCENTS, "tall_image_modes": ["fit", "split"], + "margins": settings.MARGINS, + "alignments": list(settings.ALIGNMENTS), + "table_of_contents": ["on", "off"], }, indent=2, ) @@ -589,6 +676,15 @@ def info(as_json: bool) -> None: facts.add_row("Page sizes", f"{', '.join(PAPER_SIZES)} [dim](default {DEFAULT_PAPER})[/dim]") facts.add_row("Code themes", ", ".join(available_themes())) facts.add_row("Accents", f"{', '.join(sorted(_NAMED_ACCENTS))} [dim]or any hex[/dim]") + facts.add_row( + "Margins", + f"{', '.join(settings.MARGINS)} [dim]or a measurement such as 2cm[/dim]", + ) + facts.add_row( + "Text align", + f"{', '.join(settings.ALIGNMENTS)} [dim](default: the template's own)[/dim]", + ) + facts.add_row("Contents", "generated by default [dim]— leave it out with --no-toc[/dim]") body = Group( f"[bold white]doc-engine-cli[/bold white] [dim]v{__version__}[/dim]", diff --git a/doc_engine/compiler.py b/doc_engine/compiler.py index b21ed90..b29bceb 100644 --- a/doc_engine/compiler.py +++ b/doc_engine/compiler.py @@ -76,6 +76,9 @@ def compile_pdf( pdf_standard: str | None = None, code_theme: str | None = None, title_markup: str | None = None, + toc: bool = True, + margin: str | None = None, + text_align: str | None = None, ) -> None: source = template_path(template) if not source.exists(): @@ -113,6 +116,17 @@ def compile_pdf( accent_inject = f'rgb("{accent}")' if accent else "none" + # A template of someone else's keeps the contract it was written + # against: only the bundled ones are told about options added later. + extras: dict[str, str] = {} + if Path(template).suffix != ".typ": + if not toc: + extras["toc"] = "false" + if margin: + extras["margin"] = margin + if text_align: + extras["text_align"] = f'"{text_align}"' + main_file = tmp / "main.typ" main_file.write_text( _build_main( @@ -129,6 +143,7 @@ def compile_pdf( theme_inject, # Custom templates retain the existing string-only title contract. title_markup if Path(template).suffix != ".typ" else None, + extras, ), encoding="utf-8", ) @@ -144,6 +159,11 @@ def compile_pdf( # Forcing every image to full width blows up small diagrams, and constraining # only the width lets a tall one run past the bottom of the page, where Typst # clips whatever does not fit. +# +# The height they are allowed stops short of the whole text block. A portrait +# photograph scaled to the last millimetre leaves no room for the sentence that +# introduces it, so the sentence is stranded on the page before, and asking the +# two to travel together cannot help when together they do not fit anywhere. _FIT_IMAGE = """#let fit-image(path, width: none, height: none) = context layout(area => { let img = if width != none and height != none { image(path, width: width, height: height, fit: "contain") @@ -155,7 +175,8 @@ def compile_pdf( image(path) } let natural = measure(img) - let scale = calc.min(1.0, area.width / natural.width, area.height / natural.height) + let room = area.height * 0.88 + let scale = calc.min(1.0, area.width / natural.width, room / natural.height) if scale >= 1.0 { img } else { image(path, width: natural.width * scale) } }) """ @@ -174,8 +195,10 @@ def _build_main( paper: str = DEFAULT_PAPER, theme_inject: str = "none", title_markup: str | None = None, + extras: dict[str, str] | None = None, ) -> str: title_line = f" title_content: [{title_markup}],\n" if title_markup is not None else "" + extra_lines = "".join(f" {name}: {value},\n" for name, value in (extras or {}).items()) theme_line = f"#set raw(theme: {theme_inject})\n" if theme_inject != "none" else "" date_line = f' date: "{_escape(date)}",\n' if date else "" return ( @@ -193,6 +216,7 @@ def _build_main( f" branding: {'true' if branding else 'false'},\n" f' version: "{version}",\n' f' paper: "{paper}",\n' + f"{extra_lines}" ")\n\n" f"{body}" ) diff --git a/doc_engine/converter.py b/doc_engine/converter.py index 8480825..52aa111 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,7 +47,18 @@ _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. @@ -154,6 +178,26 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None self.images.append(dict(attrs)) +class _BlockParser(HTMLParser): + """Tags in the order they were written, which is what alignment needs. + + A `
` and its closing tag often arrive as two separate + blocks with the content between them parsed as Markdown, so the opening and + the closing have to be emitted where they were found rather than matched up + inside one piece of HTML. + """ + + def __init__(self) -> None: + super().__init__(convert_charrefs=True) + self.events: list[tuple[str, str, dict[str, str | None]]] = [] + + def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: + self.events.append(("start", tag, dict(attrs))) + + def handle_endtag(self, tag: str) -> None: + self.events.append(("end", tag, {})) + + class TypstRenderer(mistune.BaseRenderer): NAME = "typst" @@ -178,6 +222,13 @@ 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] = {} + # Elements holding the document open inside an #align, since the tag + # that opens one and the tag that closes it arrive separately. + self._alignment: list[str] = [] self._asset_names: dict[str, str] = {} self._cut_pieces: dict[str, list[str]] = {} self.assets: dict[str, str] = {} @@ -202,15 +253,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] @@ -285,19 +362,19 @@ def _html_images(self, token: dict, state: Any) -> str: parser = _ImageParser() parser.feed(token.get("raw", "")) parser.close() - return "\n".join( - self.image( - { - "attrs": { - "url": attrs.get("src") or "", - "width": attrs.get("width"), - "height": attrs.get("height"), - }, - "children": [{"type": "text", "raw": attrs.get("alt") or ""}], + return "\n".join(self._html_image(attrs, state) for attrs in parser.images) + + def _html_image(self, attrs: dict[str, str | None], state: Any) -> str: + return self.image( + { + "attrs": { + "url": attrs.get("src") or "", + "width": attrs.get("width"), + "height": attrs.get("height"), }, - state, - ) - for attrs in parser.images + "children": [{"type": "text", "raw": attrs.get("alt") or ""}], + }, + state, ) def inline_math(self, token: dict, state: Any) -> str: @@ -321,10 +398,53 @@ def paragraph(self, token: dict, state: Any) -> str: body = _render_children(self, token, state).strip() return f"{body}\n\n" if body else "" + def render_tokens(self, tokens: list[dict], state: Any) -> str: + """Render a run of blocks, keeping text with the picture it introduces. + + A picture that does not fit what is left of the page moves to the next + one on its own, and the sentence that announces it stays behind above a + column of empty paper. Asking the sentence to travel with the picture + puts them back together, which is how they were written. + """ + rendered = [self.render_token(token, state) for token in tokens] + for index, token in enumerate(tokens): + if token.get("type") != "paragraph" or _OPENS_WITH_IMAGE.match(rendered[index]): + continue + # Blank lines are tokens of their own, so the picture is not + # necessarily the very next thing rendered. + following = next( + (chunk for chunk in rendered[index + 1 :] if chunk.strip()), + "", + ) + if _OPENS_WITH_IMAGE.match(following): + rendered[index] = f"#block(sticky: true)[{rendered[index].strip()}]\n\n" + return "".join(rendered) + 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 "" @@ -332,7 +452,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) @@ -365,7 +488,9 @@ def _alert(self, kind: str, body: str) -> str: f' fill: rgb("{color}").lighten(92%),\n' " radius: (right: 3pt),\n" ")[\n" - f' #text(weight: 700, fill: rgb("{color}"))[{label}]\n' + # The label travels with the first line of the alert, so a page + # break cannot leave a lone "Warning" at the bottom of a page. + f' #block(sticky: true)[#text(weight: 700, fill: rgb("{color}"))[{label}]]\n' " #v(0.35em, weak: true)\n" f" {body}\n" "]\n\n" @@ -398,8 +523,33 @@ def thematic_break(self, token: dict, state: Any) -> str: return '\n#line(length: 100%, stroke: 0.5pt + rgb("#d0d0d0"))\n\n' def block_html(self, token: dict, state: Any) -> str: - body = self._html_images(token, state) - return f"{body}\n\n" if body else "" + parser = _BlockParser() + parser.feed(token.get("raw", "")) + parser.close() + + pieces: list[str] = [] + for kind, tag, attrs in parser.events: + if kind == "start" and tag == "img": + pieces.append(self._html_image(attrs, state)) + elif kind == "start": + alignment = _ALIGN_VALUES.get( + "center" if tag == "center" else (attrs.get("align") or "").strip().lower() + ) + if alignment: + self._alignment.append(tag) + pieces.append(f"#align({alignment})[\n") + elif self._alignment and self._alignment[-1] == tag: + self._alignment.pop() + pieces.append("\n]") + + body = "".join(pieces) + return f"{body}\n\n" if body.strip() else "" + + def close_alignment(self) -> str: + """Close anything the document opened and never closed.""" + closing = "\n]" * len(self._alignment) + self._alignment.clear() + return closing def footnotes(self, token: dict, state: Any) -> str: return "" @@ -509,8 +659,10 @@ 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)) + body = renderer.render_tokens(tokens, state) + renderer.close_alignment() + return _CITATION.sub(r"@\1", body) def convert_document( 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