Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/publish-pypi.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'(<img[^>]*\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

Expand Down
31 changes: 27 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`. |
Expand Down Expand Up @@ -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` | `<input>_doc.pdf` | Output PDF path. |
| `-t, --title` | first `# heading` | Document title override. |
| `-s, --subtitle` | none | Subtitle shown under the title on the cover. |
Expand All @@ -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`. |
Expand All @@ -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.
Expand Down Expand Up @@ -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.

---
Expand Down Expand Up @@ -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.


---

Expand Down Expand Up @@ -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 |

Expand All @@ -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:

Expand Down Expand Up @@ -609,6 +630,7 @@ The converter module parses Markdown using [`mistune`](https://github.com/leptur
| `text[^1]` | `#footnote[...]` |
| `![alt](local.png)` | `#image("local.png")` |
| `<img src="local.png" width="300">` | Embedded image, using the same path as Markdown images |
| `<div align="center">` | `#align(center)[...]` around everything up to the closing tag |
| `> blockquote` | `#block(...)` |
| `---` | `#line(...)` |

Expand Down Expand Up @@ -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 `<img>` tags (inline or block), sized by `width` and `height` in pixels
- [x] `align` on a raw HTML block (`<div align="center">`, `<center>`)
- [x] Math blocks (LaTeX `$…$` and `$$…$$`)
- [x] Mermaid and SVG diagram blocks
- [x] GitHub alerts (`> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`)
Expand Down
2 changes: 1 addition & 1 deletion doc_engine/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
"""doc-engine-cli: Modern Markdown to Typst compiler."""

__version__ = "2.1.0"
__version__ = "2.2.0"
136 changes: 116 additions & 20 deletions doc_engine/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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."
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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."""
Expand All @@ -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)
Expand All @@ -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,
Expand All @@ -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:
Expand Down Expand Up @@ -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)
Expand All @@ -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)


Expand Down Expand Up @@ -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,
)
Expand All @@ -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]",
Expand Down
Loading
Loading