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[...]` |
| `` | `#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