Metadata-Version: 2.4
Name: doc-engine-cli
Version: 2.1.0
Summary: Zero-config CLI that transforms Markdown into professional PDF documents using Typst.
Author-email: Leonardo Salas <leonardo.salas01@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/leonardosalasd/doc-engine-cli
Project-URL: Repository, https://github.com/leonardosalasd/doc-engine-cli
Project-URL: Issues, https://github.com/leonardosalasd/doc-engine-cli/issues
Keywords: documentation,markdown,pdf,typst,cli,zero-config
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: mistune>=3.3
Requires-Dist: typst>=0.11
Requires-Dist: mermaidx>=0.9.5
Requires-Dist: pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

<div align="center">

# doc-engine-cli

**Zero-config Markdown → PDF documentation engine**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/doc-engine-cli.svg?logo=pypi&logoColor=white&color=006DAD)](https://pypi.org/project/doc-engine-cli/)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/doc-engine-cli?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/doc-engine-cli)
[![Typst](https://img.shields.io/badge/Powered_by-Typst-239DAD.svg?logo=typst&logoColor=white)](https://typst.app/)
[![Tests](https://github.com/leonardosalasd/doc-engine-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/leonardosalasd/doc-engine-cli/actions/workflows/tests.yml)
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-EA4AAA.svg?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/leonardosalasd)

Transform any `README.md` into a premium, print-ready PDF report — no configuration, no templates, no LaTeX.

<br>
<img src="assets/main.gif" alt="doc-engine-cli turning a Markdown file into a PDF" width="820"/>
<br>

```
pipx install doc-engine-cli
```

<br>

<a href="https://github.com/sponsors/leonardosalasd">
  <img src="https://img.shields.io/badge/Sponsor%20this%20project-%E2%9D%A4-EA4AAA?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Sponsor doc-engine-cli on GitHub Sponsors" height="34"/>
</a>

<sub>Built and maintained by one person, in the open. Sponsorship keeps it that way.</sub>

---

</div>

## Overview

**doc-engine-cli** is a developer-first CLI tool that converts Markdown files into professionally styled PDF documents using [Typst](https://typst.app/) as its rendering backend. It is designed for teams and individual developers who need high-quality documentation artifacts without the complexity of LaTeX or manual typesetting.

The tool auto-detects your `README.md`, extracts metadata from Git, and produces an IEEE-inspired technical document — complete with cover page, table of contents, and premium typography — in a single command.

```bash
doc-engine build
```

That's it. Zero configuration required.

---

## Features

| Feature | Description |
|---|---|
| **Zero-Config** | Auto-detects `README.md`, Git author, and document title. No setup files needed. |
| **Seven Templates** | Academic, article, book, minimal, modern, report, and technical layouts, each with a configurable accent color. Point `--template` at your own `.typ` file to go further. |
| **Front Matter** | An optional `---` metadata block sets the title, subtitle, author, template, and accent right inside the file. |
| **Watch Mode** | `--watch` rebuilds the PDF every time you save the source. |
| **Diagrams** | ` ```mermaid ` and ` ```svg ` blocks are rendered as real diagrams, in pure Python — no Node, no headless browser. |
| **Alerts** | `> [!NOTE]` and friends render as coloured callouts, the way GitHub shows them. |
| **Math** | LaTeX math, inline with `$…$` and display with `$$…$$`, translated into native Typst math. |
| **Multi-File** | A `doc-engine.md` manifest builds one PDF from many files, diagrams, figures, and a bibliography. |
| **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. |
| **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`. |
| **Cross-Platform** | Works on Windows, macOS, and Linux with Python 3.10+. |

---

## Academic Writing

Cite with the usual `[@citation-key]` syntax and drop a `refs.bib`,
`references.bib`, or `bibliography.bib` next to your document. It is picked up
automatically and rendered as an IEEE-styled references section:

```markdown
As shown in [@smith2020], results vary.
```

Point `--bib` at a different file, or name one in front matter, to override the
search. Combine it with the `academic`, `article`, or `report` layout and LaTeX
math for a paper that needs no LaTeX toolchain.

---

## Quick Start

### Installation

```bash
pipx install doc-engine-cli
```
*(If you don't have `pipx`, you can install it via `pip install pipx`)*

> [!NOTE]
> Installing with a pipx older than 1.17 could crash with
> `InvalidVersion: Invalid version: ''`. That came from a dependency and was
> fixed upstream in mermaidx 0.9.5, so a fresh install is fine. If you are
> holding an older mermaidx, upgrade it, or use
> [uv](https://github.com/astral-sh/uv):
>
> ```bash
> uv tool install doc-engine-cli
> ```

### Generate Your First PDF

Navigate to any project directory containing a `README.md` and run:

```bash
doc-engine build
```

The tool will:

1. Auto-detect `README.md` in the current directory
2. Extract the document title from the first `# heading`
3. Read your Git `user.name` for the author field
4. Generate a `README_doc.pdf` with cover page, ToC, and formatted content

### Explicit Options

```bash
doc-engine build path/to/file.md -o output.pdf -t "Custom Title" -a "Author Name"
```

---

## Usage

<div align="center">
<img src="assets/config.gif" alt="doc-engine-cli configuration demo" width="800"/>
<br>
<em>Switching templates, recoloring the accent, and checking a file for errors.</em>
</div>

### Commands

```
doc-engine build [INPUT_FILE]   Convert a Markdown file into a PDF
doc-engine info                 Show version, repository, and what is supported
doc-engine info --json          The same, as JSON, for tools that drive the CLI
doc-engine --version            Print the version and exit
doc-engine --help               Show all commands and flags
```

### `build` flags

| Flag | Default | Description |
|---|---|---|
| `INPUT_FILE` | auto-detect `README.md` | Path to the Markdown file to convert. |
| `-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. |
| `-a, --author` | `git config user.name` | Author name override. |
| `--date` | today | Date shown on the cover. |
| `--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`. |
| `--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`. |
| `--tall-images` | `fit` | What to do with a picture taller than a page: `fit` scales it onto one page, `split` cuts it across several. |
| `--fetch-images` | off | Download images linked by URL instead of rendering their alt text. |
| `--no-branding` | off | Hide the `doc-engine` attribution from the PDF. |
| `--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. |
| `--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.

### Examples

**Basic — zero-config mode:**
```bash
cd my-project
doc-engine build
# → Generates README_doc.pdf
```

**Specify input and output:**
```bash
doc-engine build CONTRIBUTING.md -o contributing_guide.pdf
```

**Override metadata:**
```bash
doc-engine build -t "API Reference v2.0" -a "Engineering Team"
```

**Pick a template and accent color:**
```bash
doc-engine build --template modern --accent teal
doc-engine build --template technical --accent "#7c3aed"
```

**Check for errors before building:**
```bash
doc-engine build --dry-run
```

**Drop the engine attribution from the PDF:**
```bash
doc-engine build --no-branding
```

**Generate and open immediately:**
```bash
doc-engine build --open
```

**Rebuild on every save:**
```bash
doc-engine build --watch
```

**Use as Python module:**
```bash
python -m doc_engine build README.md
```

---

## Front Matter

Any Markdown file can open with a `---` block to carry its own settings, so the
document renders the same way for everyone — no flags to remember:

```markdown
---
title: Payments API
subtitle: Integration Guide
author: Platform Team
template: technical
accent: teal
---

# Payments API

...
```

Supported keys: `title`, `subtitle`, `author`, `date`, `template`, `accent`,
`paper`, and `bib`. A flag passed on the command line overrides the matching front-matter key,
which in turn overrides the auto-detected value.

---

## Watch Mode

Pass `--watch` to keep `doc-engine` running and rebuild the PDF whenever you save
the source. It's the fastest way to tweak a template or accent and see the result:

<div align="center">
<img src="assets/features-watch.gif" alt="doc-engine watch mode rebuilding on save" width="800"/>
<br>
<em>Every file the manifest names is watched, and a save rebuilds the whole document.</em>
</div>

```bash
doc-engine build --watch --template modern --accent teal
```

The output path is chosen once when watch starts, then rewritten in place on each
change. Press `Ctrl+C` to stop.

---

## Diagrams

Fenced blocks tagged `mermaid` or `svg` become pictures instead of code:

````markdown
```mermaid
flowchart LR
    Client --> API --> Ledger
```
````

Mermaid is rendered through an embedded JavaScript engine, so there is no Node
install and no headless browser — it stays a plain `pip install`. A `svg` block
is passed straight through, since Typst draws SVG natively.

If a diagram has a syntax error, the build stops and reports Mermaid's own
message rather than producing a broken document.

---

## Math

LaTeX math is translated into native Typst math, inline with `$…$` and as a
display block with `$$…$$`:

```markdown
The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$.

$$
P(A \mid B) = \frac{P(B \mid A)\,P(A)}{P(B)}
$$
```

Greek letters, relations, fractions, roots, sub- and superscripts, font
commands, matrices, and `cases` are covered. Anything unrecognized passes
through with its backslash removed, which lands on the right Typst symbol most
of the time.

A `$` that is not math stays untouched, so prices and shell variables survive:
`$10`, `$HOME`, and `export $PATH` all render as written.

---

## Alerts

A blockquote that opens with a marker becomes a coloured callout, matching what
GitHub shows on the page:

```markdown
> [!NOTE]
> Useful information worth knowing.

> [!WARNING]
> Something that needs attention.
```

`NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION` are all recognized. A
blockquote without a marker stays an ordinary quote.

---

## Code Themes

Code blocks are highlighted with Typst's own colours by default. `--code-theme`
swaps that for something else:

```bash
doc-engine build --code-theme github
doc-engine build --code-theme monochrome     # for printing in black and white
```

| Theme | Look |
|---|---|
| `github` | GitHub's light palette |
| `solarized` | Solarized light |
| `monochrome` | Greys only — keeps code legible on a black-and-white printer |

Any TextMate `.tmTheme` file works too, so a theme from your editor can be
pointed at directly:

```bash
doc-engine build --code-theme ~/themes/my-editor.tmTheme
```

---

## Cross-References

Inside a manifest build, a link from one included file to another becomes a jump
within the PDF rather than a link to a file the reader does not have:

```markdown
For the full picture see [the data model](model.md).
```

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.


---

## Multi-File Documents

A project that has outgrown a single file lists its parts in `doc-engine.md`,
using ordinary Markdown links so the manifest still reads as a table of
contents on GitHub:

```markdown
---
title: Payments Platform
subtitle: Engineering Handbook
template: report
---

- [Overview](doc/overview.md)
- [Architecture](diagrams/architecture.mmd)
- [Schema](img/schema.svg)
- [References](bib/references.bib)
```

Then just build:

```bash
doc-engine build
```

<div align="center">
<img src="assets/features-v2.gif" alt="doc-engine building a multi-file document" width="800"/>
<br>
<em>One manifest, one command: sections, a diagram, a figure, and a bibliography.</em>
</div>

Each entry is handled by what it is:

| Entry | What happens |
|---|---|
| `.md` | Appended as a section, headings intact |
| `.mmd`, `.mermaid` | Rendered as a diagram at that point |
| `.png`, `.svg`, `.jpg`, … | Placed as a captioned figure |
| `.bib` | Registered as the bibliography for the document |

Paths resolve against the manifest's folder, and every included file resolves
its own images relative to itself — so a file builds the same way alone as it
does inside the manifest. `--watch` follows every file the manifest names.

---

## Project Configuration

Team defaults belong in a `.doc-engine.toml` next to the project, not repeated
in every document:

```toml
[doc-engine]
template = "report"
accent = "teal"
paper = "us-letter"
```

A `[tool.doc-engine]` table in `pyproject.toml` works the same way. Precedence
runs command-line flag, then front matter, then this file.

Every key it understands:

| Key | Values |
|---|---|
| `template` | A built-in layout name, or a path to a `.typ` file |
| `paper` | `a3`–`a6`, `iso-b5`, `jis-b5`, `us-letter`, `us-legal`, `us-tabloid` |
| `accent` | A hex value or a colour name |
| `author` | Author name, used instead of the Git user |
| `bib` | Path to a `.bib` file |
| `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` |
| `tall_images` | `fit` or `split` |
| `fetch_images` | `true` downloads images linked by URL |

Anything else in the table is ignored, so a typo cannot quietly change how a
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
schema — scaling it onto one page can leave it unreadable, so it can be cut
across pages at full size instead:

```bash
doc-engine build --tall-images split
```

---

## Archival PDFs

For documents that have to stay readable for decades:

```bash
doc-engine build --pdf-standard a-2b
```

`a-3b` is also accepted, which additionally allows embedded attachments.

---

## Templates

`doc-engine` ships with seven layouts. Switch with `--template <name>`, and recolor any of them with `--accent`.

| Template | Look |
|---|---|
| `academic` | Serif IEEE-style report with cover page, table of contents, and running headers. The default. |
| `modern` | Clean sans-serif layout with generous spacing and a left-aligned cover. |
| `minimal` | No cover or table of contents — a compact title block, then straight into the content. |
| `technical` | Bold layout with a filled accent banner and section markers. Good for engineering docs. |
| `book` | Classic centered title page with chapter-style section breaks. |
| `article` | A LaTeX paper: New Computer Modern, numbered sections, title block on page one. |
| `report` | Roomy and easy on the eyes — 12pt on generous leading, wide margins, lots of air. |

```bash
doc-engine build --template book
doc-engine build --template modern --accent rose
```

Accent colors take a hex value (`#0ea5e9`) or one of these names: `blue`, `sky`, `indigo`, `violet`, `purple`, `red`, `rose`, `orange`, `amber`, `green`, `emerald`, `teal`, `slate`, `black`.

### Bring your own template

`--template` also accepts a path to a `.typ` file, so you can ship a house style
without forking the project:

```bash
doc-engine build --template ./corporate.typ
```

The quickest way to start is to copy one of the files in
[`doc_engine/templates/`](doc_engine/templates) and edit it. A template exposes a
single `setup_doc` entry point, and the compiler passes it the document metadata:

```typ
#let setup_doc(
  title: "",
  subtitle: "",
  author: "Anonymous",
  date: datetime.today().display(),
  bibliography_file: none,
  accent: none,
  branding: true,
  version: "",
  body,
) = { ... }
```

---

## Checking for Errors

Before compiling, `doc-engine` scans the Markdown for problems and reports them with the exact line and column, so you can jump straight to the fix:

```
README.md:42:8: error: link URL must not be empty
README.md:51:1: warning: image source is empty
```

Errors stop the build; warnings don't. Use `--dry-run` to run the check on its own without producing a PDF — handy in CI:

```bash
doc-engine build --dry-run
```

---

## Architecture

```
                    ┌─────────────┐
                    │  README.md  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │   CLI Layer  │  click + rich
                    │  (cli.py)    │  arg parsing, git detection
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │                         │
       ┌──────▼──────┐          ┌───────▼──────┐
       │  Converter   │          │   Compiler   │
       │(converter.py)│          │(compiler.py) │
       │              │          │              │
       │ Markdown AST │          │  Typst → PDF │
       │  → Typst     │          │  via typst-py│
       └──────┬──────┘          └───────┬──────┘
              │                         │
              │    ┌──────────────┐     │
              └────► templates/   ◄─────┘
                   │   *.typ      │
                   └──────┬──────┘
                          │
                   ┌──────▼──────┐
                   │  output.pdf  │
                   └─────────────┘
```

### Pipeline

| Stage | Module | Responsibility |
|---|---|---|
| **1. Input Resolution** | `cli.py` | Locate Markdown file, detect Git metadata |
| **2. Source Checking** | `linter.py` | Report empty links and unclosed fences with line/column |
| **3. Markdown Parsing** | `converter.py` | Parse Markdown AST via `mistune`, emit Typst markup |
| **4. Template Injection** | `compiler.py` | Merge converted content with the selected template |
| **5. PDF Compilation** | `compiler.py` | Compile via `typst` Python bindings |

---

## How It Works

### Markdown → Typst Conversion

The converter module parses Markdown using [`mistune`](https://github.com/lepture/mistune) and generates equivalent Typst markup:

| Markdown | Typst Output |
|---|---|
| `# Heading` | `= Heading` |
| `**bold**` | `*bold*` |
| `*italic*` | `_italic_` |
| `` `code` `` | `` `code` `` |
| `[text](url)` | `#link("url")[text]` |
| `- item` | `- item` |
| `1. item` | `+ item` |
| `- [x] task` | rendered checkbox |
| `text[^1]` | `#footnote[...]` |
| `![alt](local.png)` | `#image("local.png")` |
| `<img src="local.png" width="300">` | Embedded image, using the same path as Markdown images |
| `> blockquote` | `#block(...)` |
| `---` | `#line(...)` |

Special characters (`#`, `$`, `@`, `*`, `_`, etc.) are automatically escaped to prevent Typst interpretation.

A `width` or `height` on an HTML image is read as CSS pixels, a 96th of an inch each, and no picture is drawn wider than the text block however large the number is. Percentages are ignored, since fitting the text block is already the default.

### PDF Templates

Each template lives in `doc_engine/templates/` and exposes the same `setup_doc` entry point, so the compiler can swap between them with `--template`. The default `academic` template provides:

- **Cover page** with title, author, and date
- **Table of contents** with depth-3 navigation
- **Running headers** with document title and author
- **Page footer** with page numbers and engine attribution
- **Code blocks** with rounded corners and subtle borders
- **Heading hierarchy** with accent-colored H2 sections

The other templates (`modern`, `minimal`, `technical`, `book`) keep the same content but change the fonts, layout, and cover. The accent color is injected at compile time, so `--accent` recolors any of them.

---

## Project Structure

```
doc-engine-cli/
├── doc_engine/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # python -m doc_engine entrypoint
│   ├── cli.py               # Click-based CLI + Git detection
│   ├── help.py              # Rich help screens
│   ├── config.py            # .doc-engine.toml project settings
│   ├── settings.py          # flag / front matter / project precedence
│   ├── frontmatter.py       # Leading --- metadata block
│   ├── manifest.py          # doc-engine.md multi-file builds
│   ├── converter.py         # Markdown → Typst transpiler
│   ├── latex.py             # LaTeX math → Typst math
│   ├── diagrams.py          # Mermaid and SVG blocks
│   ├── images.py            # Cutting pictures taller than a page
│   ├── remote.py            # Downloading linked images
│   ├── compiler.py          # Typst → PDF compilation engine
│   ├── linter.py            # Source checks (line/column reporting)
│   └── templates/
│       ├── academic.typ     # Default IEEE-style report
│       ├── article.typ      # LaTeX paper, numbered sections
│       ├── report.typ       # Roomy and legible
│       ├── modern.typ       # Clean sans-serif layout
│       ├── minimal.typ      # Compact, no cover page
│       ├── technical.typ    # Accent banner + section markers
│       └── book.typ         # Centered title page, chapter breaks
│   └── themes/
│       ├── github.tmTheme    # Syntax highlighting themes
│       ├── solarized.tmTheme
│       └── monochrome.tmTheme
├── tests/                    # 181 tests across every module
├── pyproject.toml            # Package configuration + dependencies
├── LICENSE                   # MIT License
├── .gitignore
└── README.md
```

---

## Dependencies

| Package | Purpose | License |
|---|---|---|
| [`click`](https://click.palletsprojects.com/) | CLI framework | BSD-3 |
| [`rich`](https://github.com/Textualize/rich) | Terminal formatting and progress indicators | MIT |
| [`mistune`](https://github.com/lepture/mistune) | Markdown parser (pure Python) | BSD-3 |
| [`typst`](https://github.com/messense/typst-py) | Typst compiler bindings | Apache-2.0 |
| [`mermaidx`](https://github.com/MohammadRaziei/mermaidx) | Mermaid rendering without Node | MIT |
| [`pillow`](https://github.com/python-pillow/Pillow) | Cutting pictures taller than a page | MIT-CMU |

All dependencies are pure Python — no external binaries (Pandoc, LaTeX, etc.) are required.

---

## Development

### Setup

```bash
git clone https://github.com/leonardosalasd/doc-engine-cli.git
cd doc-engine-cli
pip install -e ".[dev]"
```

### Run Tests

```bash
python -m pytest tests/ -v
```

### Project Commands

```bash
# Generate PDF from this project's README
python -m doc_engine build

# Run with verbose error output
python -m doc_engine build README.md -o docs_output.pdf
```

---

## Docker

A container image is published to GitHub Container Registry on every release. Mount your project into `/workspace` and run `build` as usual:

```bash
docker run --rm -v "$PWD:/workspace" ghcr.io/leonardosalasd/doc-engine-cli build
```

The entrypoint is `doc-engine`, so you can pass any command or flag:

```bash
docker run --rm -v "$PWD:/workspace" ghcr.io/leonardosalasd/doc-engine-cli build --template modern --accent teal
```

---

## Supported Markdown Elements

- [x] Headings (H1–H6)
- [x] Bold, italic, strikethrough
- [x] Inline code and fenced code blocks (with language hints)
- [x] Links
- [x] Ordered and unordered lists
- [x] Nested lists
- [x] Blockquotes
- [x] Tables
- [x] Horizontal rules
- [x] Line breaks (`<br>`)
- [x] Task lists (`- [x]` / `- [ ]`)
- [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] Math blocks (LaTeX `$…$` and `$$…$$`)
- [x] Mermaid and SVG diagram blocks
- [x] GitHub alerts (`> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`)

---

## Roadmap

- [x] Template selection via `--template` flag
- [x] Configurable accent color via `--accent`
- [x] Source error checking with line/column and `--dry-run`
- [x] User-supplied template files (point `--template` at a path)
- [x] YAML front-matter support for metadata override
- [x] Local image embedding
- [x] Watch mode for continuous rebuilds
- [x] Math expressions (LaTeX-style `$...$`)
- [x] Multi-file documentation merge
- [x] Mermaid diagram rendering
- [x] Image downloading and embedding for remote URLs
- [x] PDF/A compliance for archival
- [x] Page size selection
- [x] Project-level configuration file
- [x] Syntax highlighting themes for code blocks
- [x] Cross-references between documents

---

## Sponsor

`doc-engine-cli` is written and maintained by one person, in the open, and it is
free under the MIT licence for everyone — no paid tier, no telemetry, no
upsell. If it saves you the afternoon you would have spent fighting LaTeX, you
can put something behind it:

<div align="center">
<a href="https://github.com/sponsors/leonardosalasd">
  <img src="https://img.shields.io/badge/Sponsor%20on%20GitHub-%E2%9D%A4-EA4AAA?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Sponsor on GitHub" height="38"/>
</a>
</div>

Sponsorship pays for the time that goes into the parts nobody sees: testing on
Windows, chasing a rendering bug across five Python versions, answering issues,
and keeping the release quality where it is.

It is entirely optional. Starring the repository, reporting a bug you hit, or
telling someone the tool exists all help too, and cost nothing.

---

## Contributing

Contributions are welcome — bug reports, documentation fixes, new templates, and
features. The [contributing guide](CONTRIBUTING.md) covers setup, testing across
Python versions, code style, and how to add a template.

| | |
|---|---|
| [Contributing guide](CONTRIBUTING.md) | Setup, tests, style, pull requests |
| [Code of conduct](CODE_OF_CONDUCT.md) | Expected behavior in community spaces |
| [Security policy](SECURITY.md) | Reporting a vulnerability privately |
| [Support](SUPPORT.md) | Where to ask questions and report problems |

Questions belong in [Discussions](https://github.com/leonardosalasd/doc-engine-cli/discussions/categories/q-a);
bugs belong in [Issues](https://github.com/leonardosalasd/doc-engine-cli/issues).

---

## License

This project is licensed under the [MIT License](LICENSE).

---

<div align="center">

**Built with [Typst](https://typst.app/) · Parsed with [mistune](https://github.com/lepture/mistune) · Styled with [Rich](https://github.com/Textualize/rich)**

</div>
