agent-markdown-pdf 0.2.1__tar.gz → 0.3.0__tar.gz

{agent_markdown_pdf-0.2.1 → agent_markdown_pdf-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.2.1
+Version: 0.3.0
 Summary: Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics
 Author: rainp
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/ABClize/mdtopdf
 Project-URL: Repository, https://github.com/ABClize/mdtopdf
 Project-URL: Issues, https://github.com/ABClize/mdtopdf/issues
-Keywords: markdown,pdf,markdown-to-pdf,weasyprint,obsidian,cli,agent,automation,json
+Keywords: markdown,pdf,markdown-to-pdf,chromium,obsidian,cli,agent,automation,json
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -29,20 +29,23 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: markdown-it-py>=3.0.0
 Requires-Dist: mdit-py-plugins>=0.4.0
 Requires-Dist: pygments>=2.0.0
-Requires-Dist: latex2mathml>=3.81.0
-Requires-Dist: matplotlib>=3.10.0
-Requires-Dist: mini-racer>=0.14.1
-Requires-Dist: weasyprint>=69.0
+Requires-Dist: playwright<2,>=1.51
+Requires-Dist: tinycss2>=1.4.0
+Requires-Dist: fonttools[woff]>=4.59.2
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: build>=1.2.0; extra == "dev"
 Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: pypdfium2>=4.30.0; extra == "dev"
+Requires-Dist: pillow>=10.0.0; extra == "dev"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
 Dynamic: license-file
 
 <h1 align="center">mdtopdf: Agent-friendly Markdown-to-PDF CLI</h1>
 
 <p align="center">
-  <a href="https://github.com/ABClize/mdtopdf/blob/main/README_CN.md">中文文档</a>
+  <a href="https://github.com/ABClize/mdtopdf/blob/main/README_CN.md">中文文档</a> |
+  <a href="https://github.com/ABClize/mdtopdf/blob/main/README.es-ES.md">Español</a>
 </p>
 
 <p align="center">
@@ -56,7 +59,7 @@ Dynamic: license-file
 <p align="center">
   <img src="https://img.shields.io/pypi/pyversions/agent_markdown_pdf.svg" alt="Python versions">
   <img src="https://img.shields.io/badge/output-JSON_%2B_Human-blueviolet" alt="JSON and human output">
-  <img src="https://img.shields.io/badge/backend-WeasyPrint-2f855a" alt="WeasyPrint backend">
+  <img src="https://img.shields.io/badge/backend-Chromium-2f855a" alt="Chromium backend">
   <img src="https://img.shields.io/badge/status-alpha-f59e0b" alt="Alpha status">
 </p>
 
@@ -76,15 +79,15 @@ command-line interface where the style can be defined up front.
 
 - **Agent-friendly** - `mdtopdf --help` is an interface description an agent can read.
 - **JSON when it matters** - conversion, HTML preview, environment checks, and theme listing can return machine-readable output.
-- **Local files in, local files out** - no browser dependency, no upload step, no remote rendering service.
+- **Local files in, local files out** - an isolated headless browser, no upload step, no remote rendering service.
 - **More than plain Markdown** - Obsidian links, highlights, frontmatter, comments, and callouts are rendered.
 
 ## Quick start
 
-Install from PyPI:
+Install from PyPI in your Python environment:
 
 ```shell
-python -m pip install agent-markdown-pdf
+python -m pip install "agent-markdown-pdf>=0.3.0"
 ```
 
 The PyPI distribution is `agent-markdown-pdf`; it installs the `mdtopdf` command.
@@ -97,12 +100,17 @@ intentionally different from the command name.
 | Run the CLI | `mdtopdf` |
 | Import in Python | `mdtopdf` |
 
-Check the machine:
+Check the machine before the first conversion:
 
 ```shell
-mdtopdf doctor --json
+mdtopdf doctor --render-check --json
 ```
 
+The package installs the Python dependencies, including Playwright. You also need
+a compatible Chromium browser and the fonts your documents use. An installed
+Chrome, Edge, or Chromium is discovered automatically; if none is found, follow
+[Browser setup](#browser-setup). This check actually renders PDF, math, and diagrams.
+
 Convert a file:
 
 ```shell
@@ -114,7 +122,8 @@ Try the bundled visual test document:
 ```shell
 git clone https://github.com/ABClize/mdtopdf.git
 cd mdtopdf
-python -m pip install -e .[dev]
+python -m pip install -e ".[dev]"
+python -m playwright install chromium --no-shell
 mdtopdf html examples/visual-test-en.md -o visual-test-en.html --overwrite
 mdtopdf convert examples/visual-test-en.md -o visual-test-en.pdf --overwrite --json
 ```
@@ -122,6 +131,27 @@ mdtopdf convert examples/visual-test-en.md -o visual-test-en.pdf --overwrite --j
 The same visual test is also available in Chinese at
 `examples/visual-test-cn.md`.
 
+## Updating
+
+There is no `mdtopdf update` command. For a pip-installed release, activate the
+same virtual environment (or select the same Python interpreter) used to install it:
+
+```shell
+python -m pip install --upgrade agent-markdown-pdf
+python -m mdtopdf --version
+```
+
+This updates from the package index, not from the development branch.
+For pipx or uv tool installations, use that tool's upgrade workflow instead.
+For editable/source installs, update the intended checkout and reinstall from it;
+do not replace a development install with a PyPI release by accident.
+
+Pin a tested version in your deployment requirements rather than upgrading on
+every job. After upgrading to 0.3.0 or later, run `mdtopdf doctor --render-check --json`
+and review a representative PDF. If Playwright now needs a different managed
+browser, follow [Browser setup](#browser-setup). Conversion does not check for
+updates or upgrade the package/browser automatically.
+
 ## Agent workflow
 
 The bundled agent skill lives at
@@ -133,6 +163,26 @@ mdtopdf doctor --json
 mdtopdf convert report.md -o report.pdf --overwrite --json
 ```
 
+Agents can also send UTF-8 Markdown directly to `convert -`, without saving an
+input file. An explicit output file is required; PDF bytes are not written to stdout.
+
+```shell
+printf '# Report\n\nGenerated by an agent.\n' | mdtopdf convert - -o report.pdf --json
+```
+
+PowerShell (set the pipe encoding for non-ASCII text, especially in Windows PowerShell 5.1):
+
+```powershell
+$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+'# Report' | mdtopdf convert - -o report.pdf --json
+```
+
+Relative resources resolve from the working directory unless `--base-url` is set.
+Use `--resource-dir` for bare attachment names and `--title` for the document title
+and default header (otherwise `stdin`). JSON reports `input: "-"` and `source: "stdin"`.
+Empty or non-UTF-8 input fails; `--overwrite` and `--strict` behave as with files.
+The `html` command still takes a file path.
+
 Use HTML preview when layout needs a quick look:
 
 ```shell
@@ -145,6 +195,24 @@ check summary, warnings, and render method. If conversion fails in JSON mode,
 the error is structured enough for an agent to show the command, explain the
 likely cause, and retry after a fix.
 
+A successful conversion can still have warnings: a missing image, an unavailable
+font, or an unsupported formula shown as source. Read `warnings` before handing over the PDF.
+For jobs that must not accept these fallbacks:
+
+```shell
+mdtopdf convert report.md -o report.pdf --overwrite --strict --json
+mdtopdf doctor --render-check --json
+```
+
+`--strict` leaves an existing output untouched when a diagnostic is raised.
+It is also available for file-based HTML previews. Math and Mermaid are rendered
+to static HTML/SVG in Chromium; plain HTML export does not start a browser and
+does not check image loading. `doctor --render-check` tests PDF, KaTeX, and Mermaid
+together. It checks runtime health, not visual parity across machines.
+Exit codes are `0` for success, `1` for runtime or strict-check failures, and
+`2` for invalid arguments. Missing fonts are advisory; a missing browser or
+bundled renderer makes the basic doctor check fail.
+
 ## Visual output
 
 The gallery below is rendered from the final PDF produced by
@@ -163,19 +231,29 @@ pagination.
 ## How it works
 
 ```text
-Markdown -> markdown-it-py HTML -> theme/custom CSS -> WeasyPrint PDF
+Markdown -> markdown-it-py HTML -> theme/custom CSS -> Chromium PDF
 ```
 
-Mermaid rendering is optional. If a local `mmdc` command exists, Mermaid blocks
-render to SVG. If it is missing, conversion still succeeds and Mermaid blocks
-remain visible as highlighted code.
+One Chromium session renders bundled KaTeX and Mermaid, waits for fonts and
+images, and prints the PDF. No separate Mermaid CLI, Node.js installation,
+WeasyPrint, or MSYS2 setup is needed. Browser installation is an explicit setup
+step; conversion never downloads a browser.
+
+### Upgrading from 0.2.x
+
+The command name and Python API stay the same, but the PDF engine changes from
+WeasyPrint to Chromium. There is no WeasyPrint fallback. Install/check the browser,
+then render a representative document before upgrading an automated workflow.
+Page breaks, headers/footers, fonts, and custom paged-media CSS may differ.
+JSON consumers should accept the new render-method value rather than hard-code
+the old backend. See the [release notes](https://github.com/ABClize/mdtopdf/blob/main/CHANGELOG.md).
 
 ## Features
 
 | Feature | Notes |
 | --- | --- |
 | JSON output | `--json` is available for conversion, HTML preview, doctor, and theme listing. |
-| Environment checks | `doctor --json` checks Python imports, native WeasyPrint libraries, Windows DLL paths, Mermaid availability, and recommended fonts. |
+| Environment checks | `doctor --json` checks Python imports, the browser executable, bundled KaTeX/Mermaid assets, and recommended fonts. |
 | Local rendering | Markdown, CSS, math, Mermaid SVG generation, and PDF export stay on the machine. |
 | HTML preview | Generate standalone HTML before PDF export for fast visual inspection. |
 | Obsidian compatibility | Wikilinks, aliases, frontmatter hiding, comments, highlights, and typed callouts. |
@@ -246,6 +324,11 @@ mdtopdf convert report.md -o report.pdf --css print.css --base-url .
 During export, `mdtopdf` checks the final CSS font stacks. Missing fonts do not
 stop PDF generation, but they are reported in CLI warnings and in the JSON
 `warnings` field.
+Custom CSS also warns when its first named font is missing, even if a fallback
+is available. Local `@font-face` files are checked for readability and CJK
+coverage; declaring a family is not enough. Remote font sources are not fetched
+by this static check and are reported as unverified. These checks do not replace
+reviewing the rendered PDF. Pass `--strict` to reject warnings.
 
 Return JSON:
 
@@ -261,6 +344,10 @@ Allow raw HTML only for trusted local Markdown:
 mdtopdf convert trusted.md -o trusted.pdf --unsafe-html
 ```
 
+HTML filtering is not a filesystem or network sandbox. Images and CSS can still
+reference local files or remote URLs. Run untrusted documents in an environment
+with restricted filesystem access and networking.
+
 ## Python API
 
 ```python
@@ -297,111 +384,94 @@ markdown_file_to_pdf("report.md", output_path="report.pdf", overwrite=True)
 - Obsidian-style callouts such as `> [!note] Title`
 - Safe inline HTML tags such as `<br>`, `<kbd>`, `<mark>`, `<sup>`, and `<sub>`
 - TeX math through `$inline$`, `$$block$$`, and common `amsmath` environments
-- Mermaid diagrams through local `mmdc`, when installed
+- Mermaid diagrams through bundled Mermaid in Chromium
 
 Raw HTML is disabled by default except for the safe subset above. For trusted
 local Markdown, pass `--unsafe-html`.
 
-## Mermaid diagrams
-
-Install a persistent local renderer:
+## Browser setup
 
-```shell
-npm install -g @mermaid-js/mermaid-cli
-```
-
-`mdtopdf` does not call Mermaid.ink and does not download Mermaid CLI through
-`npx` during conversion. Run `mdtopdf doctor --json` to check whether Mermaid
-rendering is available.
-
-## Platform notes
-
-`mdtopdf` requires Python 3.10+ and installs its Python dependencies from PyPI:
-`click`, `markdown-it-py`, `mdit-py-plugins`, `pygments`, `latex2mathml`,
-`matplotlib`, `mini-racer`, and `weasyprint`.
-
-WeasyPrint also needs native libraries such as Pango, GLib, and Cairo. Linux
-and macOS package managers usually provide them through system packages.
+PDF export requires Chromium. HTML export also uses it when the document has
+math or Mermaid. Browser selection is deterministic: `MDTOPDF_BROWSER_EXECUTABLE`,
+then legacy `PUPPETEER_EXECUTABLE_PATH`, then installed Playwright Chromium,
+then Chrome/Edge/Chromium on PATH or in common Windows/macOS installation folders.
+Linux also checks standard installation paths. An invalid explicit path is an error,
+not a reason to silently switch browsers. Discovery never downloads or installs anything.
 
-The default theme uses a PDFium-safe Latin-first font stack. Latin fonts are
-listed before CJK fonts so ASCII digits, dates, versions, and page numbers are
-not embedded into CJK font subsets that some Chrome/PDFium renderers handle
-poorly. Chinese text still falls back to the CJK side of the stack, where
-`Microsoft YaHei` is the first preferred CJK font. If it is missing, the theme
-falls back to `PingFang SC`, `Noto Sans SC`, `Noto Sans CJK SC`,
-`Source Han Sans SC`, and other available CJK fonts.
-
-For Linux containers or agent sandboxes, install fontconfig plus the fonts you
-expect the default theme to use. A practical open-font baseline is:
+If no browser is available, install the managed browser once:
 
 ```shell
-sudo apt-get install -y --no-install-recommends \
-  fontconfig \
-  fonts-noto-cjk \
-  fonts-liberation \
-  fonts-dejavu-core
-fc-cache -f
+python -m playwright install chromium --no-shell
+mdtopdf doctor --render-check --json
 ```
 
-This baseline is a fallback. If you want Linux Chinese typography to match the
-default Windows output more closely, provide `Microsoft YaHei` in the runtime
-under your own font license. `mdtopdf` names that font in CSS but does not
-bundle or download Microsoft font files. Providing Microsoft YaHei improves the
-Chinese fallback; the Latin-first order is still kept for PDFium-safe digits.
-
-Code blocks prefer `Cascadia Mono` / `Cascadia Code`, then `Consolas`,
-`Noto Sans Mono CJK SC`, `Liberation Mono`, and `DejaVu Sans Mono`. On Debian,
-`fonts-cascadia-code` provides Cascadia fonts; on other Linux images, provide
-Cascadia Code yourself or let the theme fall back to the installed monospace
-fonts.
-
-Emoji are rendered through the system emoji font. The default theme prefers
-`Segoe UI Emoji` for emoji spans on every platform, including Linux. Windows
-usually provides it; Linux containers only get the same glyphs if the runtime
-provides that font. If Segoe UI Emoji is not available, the theme falls back to
-`Apple Color Emoji`, `Noto Emoji`, `Noto Color Emoji`, and other installed emoji
-fonts. Whether the final PDF keeps color emoji still depends on WeasyPrint,
-Pango/Cairo, and the PDF viewer.
-
-Optional fallback fonts:
-
-```shell
-sudo apt-get install -y --no-install-recommends fonts-noto-color-emoji fonts-stix
-fc-cache -f
-```
-
-On Windows, install the native libraries separately. A common MSYS2 setup is:
+`doctor --json` shows the selected path and its `tools.browser.source`.
+Use `--render-check` to verify it actually launches and renders. A browser found
+on disk can still lack required system libraries or sandbox support.
+An existing recent Chrome or Edge can be selected explicitly:
 
 ```powershell
-winget install MSYS2.MSYS2
+$env:MDTOPDF_BROWSER_EXECUTABLE = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
+mdtopdf doctor --render-check --json
 ```
 
-Then install Pango from an MSYS2 MINGW64 shell:
-
 ```shell
-pacman -S mingw-w64-x86_64-pango
+export MDTOPDF_BROWSER_EXECUTABLE="$(command -v google-chrome)"
+mdtopdf doctor --render-check --json
 ```
 
-Finally, point WeasyPrint at the DLL directory from PowerShell. Adjust the path
-if MSYS2 is installed somewhere else:
+The legacy `PUPPETEER_EXECUTABLE_PATH` is accepted if the new variable is unset.
+A fresh headless session is used; your personal browser profile is never opened.
+Browser errors include an `error_code`, original message, and repair `hint`.
 
-```powershell
-setx WEASYPRINT_DLL_DIRECTORIES "C:\msys64\mingw64\bin"
-```
+## Platform notes
+
+Use Python 3.10+ and a recent Chromium browser. The Python Playwright package
+includes its driver; a separate Node.js or npm installation is not required.
+Windows and macOS no longer need an MSYS2 or Homebrew Pango setup.
 
-Run this after installation. The JSON output also reports whether recommended
-Latin, CJK, emoji, monospace, and math fallback fonts are present:
+On a supported Debian/Ubuntu environment, install Chromium's system libraries
+during setup, then provide the fonts your documents use:
 
 ```shell
-mdtopdf doctor --json
+python -m playwright install-deps chromium
+sudo apt-get update
+sudo apt-get install -y --no-install-recommends \
+  fontconfig fonts-liberation fonts-dejavu-core fonts-noto-cjk fonts-stix
+fc-cache -f
 ```
 
+Run conversions as a **non-root** user with working browser sandbox support.
+If Ubuntu/AppArmor blocks a downloaded browser, use an explicitly configured
+system Chrome permitted by the host policy. Do not fix this by disabling the
+sandbox. See [Playwright browser setup](https://playwright.dev/python/docs/browsers).
+
+The theme keeps Latin fonts before CJK fonts. Linux uses Liberation Sans /
+DejaVu Sans for English and digits, Noto Sans CJK SC for Chinese, and Cascadia
+Mono / Cascadia Code for code where installed (otherwise system monospace).
+Debian provides Cascadia through `fonts-cascadia-code`. Windows keeps its
+existing system font stack. Microsoft YaHei and Segoe UI Emoji are not Linux
+requirements and are never downloaded or bundled by mdtopdf.
+
+Emoji still use installed system fonts. The existing Linux preference is
+monochrome Noto Emoji, with Noto Color Emoji as a fallback. Browser rendering
+removes the old WeasyPrint pipeline, but does not make every font or emoji
+sequence identical across operating systems. Review representative PDFs.
+KaTeX includes its own math fonts; STIX is an optional math fallback.
+
+Images, CSS, and fonts may use local or remote resources. Document JavaScript
+is blocked during conversion, even with `--unsafe-html`; this is not a
+filesystem or network sandbox. Use restricted filesystem/network permissions
+for untrusted documents. Raw HTML exported with `--unsafe-html` remains trusted
+content when opened elsewhere.
+
 ## Development
 
 ```shell
 git clone https://github.com/ABClize/mdtopdf.git
 cd mdtopdf
-python -m pip install -e .[dev]
+python -m pip install -e ".[dev]"
+python -m playwright install chromium --no-shell
 python -m pytest tests/ -q
 ```
 
@@ -414,11 +484,12 @@ python -m twine check dist/*
 
 ## License
 
-MIT. Bundled KaTeX assets are also distributed under the MIT license; see
-`mdtopdf/vendor/katex/LICENSE`.
+MIT. Bundled KaTeX and Mermaid assets include their MIT licenses at
+`mdtopdf/vendor/katex/LICENSE` and `mdtopdf/vendor/mermaid/LICENSE`.
 
 `mdtopdf` does not bundle CJK body fonts, emoji fonts, or proprietary system
 fonts. The default theme references local system fonts such as Segoe UI,
-Microsoft YaHei, PingFang SC, Segoe UI Emoji, Noto Emoji, Noto Color Emoji,
-Cascadia Code, and Consolas, but those font files come from the user's operating
-system or runtime environment.
+Microsoft YaHei, PingFang SC, Segoe UI Emoji, Noto Sans CJK SC,
+Noto Emoji, Noto Color Emoji, Cascadia Code, and Consolas, but those font files come from
+the user's operating system or runtime environment. Public Linux images should
+prefer the open-font baseline above.