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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.2.0
+Version: 0.2.1
 Summary: Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics
 Author: rainp
 License-Expression: MIT
@@ -323,15 +323,37 @@ rendering is available.
 WeasyPrint also needs native libraries such as Pango, GLib, and Cairo. Linux
 and macOS package managers usually provide them through system packages.
 
-The default theme names `Microsoft YaHei` first in its CSS on every platform,
-including Linux. If that font is installed in the environment, WeasyPrint will
-use it. 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.
+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 stable CJK output in Linux containers or agent sandboxes where Microsoft
-YaHei is not installed, install the CJK font you want to use. Noto CJK is a
-practical fallback on Debian or Ubuntu:
+For Linux containers or agent sandboxes, install fontconfig plus the fonts you
+expect the default theme to use. A practical open-font baseline is:
+
+```shell
+sudo apt-get install -y --no-install-recommends \
+  fontconfig \
+  fonts-noto-cjk \
+  fonts-liberation \
+  fonts-dejavu-core
+fc-cache -f
+```
+
+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
@@ -341,10 +363,10 @@ provides that font. If Segoe UI Emoji is not available, the theme falls back to
 fonts. Whether the final PDF keeps color emoji still depends on WeasyPrint,
 Pango/Cairo, and the PDF viewer.
 
-On Debian or Ubuntu, this is a practical open-font fallback baseline:
+Optional fallback fonts:
 
 ```shell
-sudo apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-stix fonts-dejavu-core
+sudo apt-get install -y --no-install-recommends fonts-noto-color-emoji fonts-stix
 fc-cache -f
 ```
 
@@ -368,7 +390,7 @@ setx WEASYPRINT_DLL_DIRECTORIES "C:\msys64\mingw64\bin"
 ```
 
 Run this after installation. The JSON output also reports whether recommended
-CJK, emoji, monospace, and math fallback fonts are present:
+Latin, CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -396,6 +418,7 @@ MIT. Bundled KaTeX assets are also distributed under the MIT license; see
 `mdtopdf/vendor/katex/LICENSE`.
 
 `mdtopdf` does not bundle CJK body fonts, emoji fonts, or proprietary system
-fonts. The default theme references local system fonts such as Microsoft YaHei,
-PingFang SC, Segoe UI, Segoe UI Emoji, Noto Emoji, Noto Color Emoji, and Consolas, but
-those font files come from the user's operating system or runtime environment.
+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.

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/README.md

@@ -282,15 +282,37 @@ rendering is available.
 WeasyPrint also needs native libraries such as Pango, GLib, and Cairo. Linux
 and macOS package managers usually provide them through system packages.
 
-The default theme names `Microsoft YaHei` first in its CSS on every platform,
-including Linux. If that font is installed in the environment, WeasyPrint will
-use it. 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.
+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 stable CJK output in Linux containers or agent sandboxes where Microsoft
-YaHei is not installed, install the CJK font you want to use. Noto CJK is a
-practical fallback on Debian or Ubuntu:
+For Linux containers or agent sandboxes, install fontconfig plus the fonts you
+expect the default theme to use. A practical open-font baseline is:
+
+```shell
+sudo apt-get install -y --no-install-recommends \
+  fontconfig \
+  fonts-noto-cjk \
+  fonts-liberation \
+  fonts-dejavu-core
+fc-cache -f
+```
+
+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
@@ -300,10 +322,10 @@ provides that font. If Segoe UI Emoji is not available, the theme falls back to
 fonts. Whether the final PDF keeps color emoji still depends on WeasyPrint,
 Pango/Cairo, and the PDF viewer.
 
-On Debian or Ubuntu, this is a practical open-font fallback baseline:
+Optional fallback fonts:
 
 ```shell
-sudo apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-stix fonts-dejavu-core
+sudo apt-get install -y --no-install-recommends fonts-noto-color-emoji fonts-stix
 fc-cache -f
 ```
 
@@ -327,7 +349,7 @@ setx WEASYPRINT_DLL_DIRECTORIES "C:\msys64\mingw64\bin"
 ```
 
 Run this after installation. The JSON output also reports whether recommended
-CJK, emoji, monospace, and math fallback fonts are present:
+Latin, CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -355,6 +377,7 @@ MIT. Bundled KaTeX assets are also distributed under the MIT license; see
 `mdtopdf/vendor/katex/LICENSE`.
 
 `mdtopdf` does not bundle CJK body fonts, emoji fonts, or proprietary system
-fonts. The default theme references local system fonts such as Microsoft YaHei,
-PingFang SC, Segoe UI, Segoe UI Emoji, Noto Emoji, Noto Color Emoji, and Consolas, but
-those font files come from the user's operating system or runtime environment.
+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.

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/agent_markdown_pdf.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.2.0
+Version: 0.2.1
 Summary: Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics
 Author: rainp
 License-Expression: MIT
@@ -323,15 +323,37 @@ rendering is available.
 WeasyPrint also needs native libraries such as Pango, GLib, and Cairo. Linux
 and macOS package managers usually provide them through system packages.
 
-The default theme names `Microsoft YaHei` first in its CSS on every platform,
-including Linux. If that font is installed in the environment, WeasyPrint will
-use it. 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.
+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 stable CJK output in Linux containers or agent sandboxes where Microsoft
-YaHei is not installed, install the CJK font you want to use. Noto CJK is a
-practical fallback on Debian or Ubuntu:
+For Linux containers or agent sandboxes, install fontconfig plus the fonts you
+expect the default theme to use. A practical open-font baseline is:
+
+```shell
+sudo apt-get install -y --no-install-recommends \
+  fontconfig \
+  fonts-noto-cjk \
+  fonts-liberation \
+  fonts-dejavu-core
+fc-cache -f
+```
+
+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
@@ -341,10 +363,10 @@ provides that font. If Segoe UI Emoji is not available, the theme falls back to
 fonts. Whether the final PDF keeps color emoji still depends on WeasyPrint,
 Pango/Cairo, and the PDF viewer.
 
-On Debian or Ubuntu, this is a practical open-font fallback baseline:
+Optional fallback fonts:
 
 ```shell
-sudo apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-stix fonts-dejavu-core
+sudo apt-get install -y --no-install-recommends fonts-noto-color-emoji fonts-stix
 fc-cache -f
 ```
 
@@ -368,7 +390,7 @@ setx WEASYPRINT_DLL_DIRECTORIES "C:\msys64\mingw64\bin"
 ```
 
 Run this after installation. The JSON output also reports whether recommended
-CJK, emoji, monospace, and math fallback fonts are present:
+Latin, CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -396,6 +418,7 @@ MIT. Bundled KaTeX assets are also distributed under the MIT license; see
 `mdtopdf/vendor/katex/LICENSE`.
 
 `mdtopdf` does not bundle CJK body fonts, emoji fonts, or proprietary system
-fonts. The default theme references local system fonts such as Microsoft YaHei,
-PingFang SC, Segoe UI, Segoe UI Emoji, Noto Emoji, Noto Color Emoji, and Consolas, but
-those font files come from the user's operating system or runtime environment.
+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.

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/mdtopdf/core/doctor.py

@@ -4,6 +4,8 @@ import ctypes
 import importlib
 import os
 import platform
+import shutil
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any
@@ -76,6 +78,8 @@ def run_doctor() -> dict[str, Any]:
     result["packages"]["latex2mathml"] = _check_python_package("latex2mathml")
     result["packages"]["matplotlib"] = _check_python_package("matplotlib")
     result["tools"]["mermaid"] = inspect_mermaid_backend()
+    if result["platform"]["system"] == "Linux":
+        result["tools"]["fontconfig"] = _inspect_fontconfig()
     result["ok"] = all(info["ok"] for info in result["packages"].values())
     result["recommendations"] = _recommendations(result)
     return result
@@ -211,8 +215,38 @@ def _inspect_fonts() -> dict[str, Any]:
     return inspect_recommended_font_groups()
 
 
+def _inspect_fontconfig() -> dict[str, Any]:
+    executable = shutil.which("fc-match")
+    result: dict[str, Any] = {
+        "ok": False,
+        "executable": executable,
+        "sample": None,
+        "error": None,
+    }
+    if not executable:
+        result["error"] = "fc-match was not found on PATH."
+        return result
+
+    try:
+        proc = subprocess.run(
+            [executable, "-f", "%{family}\n", "sans-serif"],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except Exception as exc:
+        result["error"] = f"{type(exc).__name__}: {exc}"
+        return result
+
+    result["sample"] = proc.stdout.strip() or None
+    result["ok"] = True
+    return result
+
+
 def _recommendations(result: dict[str, Any]) -> list[str]:
     recommendations: list[str] = []
+    is_linux = result.get("platform", {}).get("system") == "Linux"
     package_info = result.get("packages", {}).get("weasyprint", {})
     if not package_info.get("ok"):
         recommendations.append("Install Python dependencies with: python -m pip install agent-markdown-pdf")
@@ -232,19 +266,48 @@ def _recommendations(result: dict[str, Any]) -> list[str]:
             "Optional: install Mermaid rendering support with Node.js plus: "
             "npm install -g @mermaid-js/mermaid-cli"
         )
+    fontconfig_info = result.get("tools", {}).get("fontconfig")
+    if is_linux and fontconfig_info and not fontconfig_info.get("ok"):
+        recommendations.append(
+            "Install fontconfig so WeasyPrint/Pango can resolve system fonts, for example: "
+            "sudo apt-get install fontconfig"
+        )
 
     font_info = result.get("fonts", {})
     font_groups = font_info.get("groups", {})
     if font_info.get("error"):
         recommendations.append("Font inspection failed; run conversion once and verify CJK text visually.")
+    if font_groups.get("latin_sans") and not font_groups["latin_sans"].get("ok"):
+        recommendations.append(
+            "Install a Latin sans font so digits, dates, versions, and page counters avoid CJK font subsets. "
+            "On Debian or Ubuntu, use: sudo apt-get install fonts-liberation fonts-dejavu-core"
+        )
     if font_groups.get("cjk_sans") and not font_groups["cjk_sans"].get("ok"):
         recommendations.append(
-            "Install Microsoft YaHei when you want the default theme to match its first-choice CJK font. "
-            "On Debian or Ubuntu, Noto CJK is a practical fallback: sudo apt-get install fonts-noto-cjk"
+            "Provide Microsoft YaHei in the runtime to match the default theme's Windows-like Chinese typography. "
+            "On Debian or Ubuntu, Noto CJK is a supported fallback: sudo apt-get install fonts-noto-cjk"
+        )
+    elif is_linux and font_groups.get("cjk_sans") and "Microsoft YaHei" in font_groups["cjk_sans"].get("missing", []):
+        recommendations.append(
+            "Optional: provide Microsoft YaHei in the Linux runtime to match the default theme's Windows-like "
+            "Chinese typography. Without it, output falls back to installed CJK fonts such as Noto CJK."
         )
     if font_groups.get("monospace") and not font_groups["monospace"].get("ok"):
         recommendations.append(
-            "Optional: install a monospace font such as Cascadia Code or Liberation Mono for stable code blocks."
+            "Install a monospace font for code blocks. On Debian or Ubuntu, use: "
+            "sudo apt-get install fonts-cascadia-code if that package is available; "
+            "otherwise provide Cascadia Code in the runtime."
+        )
+    elif (
+        is_linux
+        and font_groups.get("monospace")
+        and "Cascadia Mono" in font_groups["monospace"].get("missing", [])
+        and "Cascadia Code" in font_groups["monospace"].get("missing", [])
+    ):
+        recommendations.append(
+            "Optional: install Cascadia Code on Linux for default-theme code blocks: "
+            "sudo apt-get install fonts-cascadia-code if that package is available, "
+            "or provide Cascadia Code in the runtime."
         )
     if font_groups.get("math") and not font_groups["math"].get("ok"):
         recommendations.append(

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/mdtopdf/core/fonts.py

@@ -33,8 +33,19 @@ GENERIC_FONT_FAMILIES = {
 }
 
 RECOMMENDED_FONT_GROUPS = {
+    "latin_sans": {
+        "description": "Latin body text and digits",
+        "preferred": ("Segoe UI", "Arial", "Liberation Sans", "DejaVu Sans"),
+        "families": (
+            "Segoe UI",
+            "Arial",
+            "Liberation Sans",
+            "DejaVu Sans",
+        ),
+    },
     "cjk_sans": {
         "description": "CJK body text",
+        "preferred": ("Microsoft YaHei",),
         "families": (
             "Microsoft YaHei",
             "PingFang SC",
@@ -47,6 +58,7 @@ RECOMMENDED_FONT_GROUPS = {
     },
     "monospace": {
         "description": "Code blocks",
+        "preferred": ("Cascadia Mono", "Cascadia Code"),
         "families": (
             "Cascadia Mono",
             "Cascadia Code",
@@ -58,6 +70,7 @@ RECOMMENDED_FONT_GROUPS = {
     },
     "math": {
         "description": "Math fallback",
+        "preferred": ("Cambria Math",),
         "families": (
             "Cambria Math",
             "STIX Two Math",
@@ -67,6 +80,7 @@ RECOMMENDED_FONT_GROUPS = {
     },
     "emoji": {
         "description": "Emoji glyphs",
+        "preferred": ("Segoe UI Emoji",),
         "families": (
             "Segoe UI Emoji",
             "Apple Color Emoji",
@@ -115,6 +129,8 @@ def match_font_name(family: str, available: set[str]) -> str | None:
     target = family.lower()
     for name in sorted(available):
         current = name.lower()
+        if "emoji" not in target and " emoji" in current:
+            continue
         if current == target or current.startswith(target + " "):
             return name
     return None
@@ -137,6 +153,7 @@ def inspect_recommended_font_groups() -> dict[str, Any]:
     fontconfig_emoji = _fontconfig_emoji_match()
     for group_name, group in RECOMMENDED_FONT_GROUPS.items():
         recommended = list(group["families"])
+        preferred = list(group.get("preferred", group["families"][:1]))
         found = []
         for family in recommended:
             match = match_font_name(family, available)
@@ -146,12 +163,15 @@ def inspect_recommended_font_groups() -> dict[str, Any]:
             for family in fontconfig_emoji.get("families", []):
                 if family not in found:
                     found.append(family)
+        missing = [family for family in recommended if not match_font_name(family, available)]
         result["groups"][group_name] = {
             "ok": bool(found),
             "description": group["description"],
+            "preferred": preferred,
+            "preferred_found": any(family not in missing for family in preferred),
             "recommended": recommended,
             "found": found,
-            "missing": [family for family in recommended if not match_font_name(family, available)],
+            "missing": missing,
         }
         if group_name == "emoji":
             result["groups"][group_name]["fontconfig"] = fontconfig_emoji

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/mdtopdf/core/markdown.py

@@ -43,6 +43,11 @@ from mdtopdf.core.obsidian import (
 
 DEFAULT_THEME = "default"
 SUPPORTED_THEMES = (DEFAULT_THEME,)
+PAGE_MARGIN_FONT_FAMILY = (
+    '"Segoe UI", Arial, "Liberation Sans", "DejaVu Sans", '
+    '"Microsoft YaHei", "PingFang SC", "Hiragino Sans GB", '
+    '"Noto Sans SC", "Noto Sans CJK SC", "Source Han Sans SC", sans-serif'
+)
 
 
 @dataclass(frozen=True)
@@ -990,6 +995,7 @@ def _page_margin_css(page_header: str | None, page_footer: str | None, page_numb
                 "  @top-center {",
                 f"    content: {_css_string(page_header)};",
                 '    color: #6b7280;',
+                f"    font-family: {PAGE_MARGIN_FONT_FAMILY};",
                 '    font-size: 8.5pt;',
                 '    vertical-align: middle;',
                 "  }",
@@ -1003,6 +1009,7 @@ def _page_margin_css(page_header: str | None, page_footer: str | None, page_numb
                 "  @bottom-center {",
                 f"    content: {footer_content};",
                 '    color: #6b7280;',
+                f"    font-family: {PAGE_MARGIN_FONT_FAMILY};",
                 '    font-size: 8.5pt;',
                 '    vertical-align: middle;',
                 "  }",

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/mdtopdf/core/mermaid.py

@@ -120,7 +120,7 @@ def _replace_foreign_object_labels(svg: str) -> str:
         return (
             f'{match.group(1)}<text x="{width / 2:.3f}" y="{height / 2:.3f}" '
             'text-anchor="middle" dominant-baseline="central" '
-            'font-family="Microsoft YaHei, PingFang SC, Hiragino Sans GB, Noto Sans SC, Noto Sans CJK SC, Arial, sans-serif" '
+            'font-family="Segoe UI, Arial, Liberation Sans, DejaVu Sans, Microsoft YaHei, PingFang SC, Hiragino Sans GB, Noto Sans SC, Noto Sans CJK SC, Source Han Sans SC, sans-serif" '
             'font-size="16" fill="#333">'
             f"{escape(text)}"
             "</text></g>"

agent_markdown_pdf-0.2.1/mdtopdf/skills/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: "mdtopdf"
+description: "Install and run mdtopdf, an agent-friendly Markdown-to-PDF CLI. Use when converting Markdown to PDF or HTML, checking WeasyPrint/mdtopdf runtime health, using Obsidian-style resources, custom CSS, KaTeX, Mermaid, fonts, or JSON diagnostics."
+---
+
+# mdtopdf
+
+## Names
+
+- PyPI package: `agent-markdown-pdf`
+- CLI command: `mdtopdf`
+- Python import: `mdtopdf`
+
+## Basic Flow
+
+Install or upgrade if the command is missing:
+
+```shell
+python -m pip install -U agent-markdown-pdf
+```
+
+Check the runtime before converting on a new machine:
+
+```shell
+mdtopdf doctor --json
+```
+
+Convert Markdown to PDF:
+
+```shell
+mdtopdf convert INPUT.md -o OUTPUT.pdf --overwrite --json
+```
+
+Use HTML preview only when layout needs debugging:
+
+```shell
+mdtopdf html INPUT.md -o preview.html --overwrite --json
+mdtopdf convert INPUT.md -o OUTPUT.pdf --overwrite --json
+```
+
+## Useful Options
+
+- `--base-url PATH_OR_URL`: resolve relative images and links.
+- `--resource-dir PATH`: resolve Obsidian-style image names such as `![[image.png]]`.
+- `--css print.css`: apply custom print CSS.
+- `--unsafe-html`: allow raw HTML only for trusted local Markdown.
+- `--json`: prefer this for agent workflows.
+
+## Environment
+
+`mdtopdf` uses WeasyPrint. If PDF export fails, run:
+
+```shell
+mdtopdf doctor --json
+```
+
+Windows usually needs MSYS2 Pango/GLib/Cairo DLLs:
+
+```powershell
+pacman -S mingw-w64-x86_64-pango
+setx WEASYPRINT_DLL_DIRECTORIES "D:\Environment\msys64\mingw64\bin"
+```
+
+Linux containers need native libraries and fonts:
+
+```shell
+apt-get update
+apt-get install -y --no-install-recommends \
+  fontconfig \
+  libcairo2 \
+  libffi-dev \
+  libgdk-pixbuf-2.0-0 \
+  libpango-1.0-0 \
+  libpangoft2-1.0-0 \
+  shared-mime-info \
+  fonts-liberation \
+  fonts-dejavu-core \
+  fonts-noto-cjk
+fc-cache -f
+```
+
+Install optional support only when needed:
+
+```shell
+npm install -g @mermaid-js/mermaid-cli
+apt-get install -y --no-install-recommends fonts-stix fonts-noto-color-emoji
+```
+
+Use Cascadia Code for closer default code-block styling when available:
+
+```shell
+apt-get install -y --no-install-recommends fonts-cascadia-code
+```
+
+## Failure Handling
+
+- Read JSON errors first; do not guess from stderr alone.
+- If conversion fails with WeasyPrint, Pango, GLib, Cairo, or DLL errors, fix the items reported by `doctor --json`.
+- If images are missing, add `--base-url` or `--resource-dir`.
+- If Mermaid diagrams do not render, install local `mmdc`; `mdtopdf` does not call Mermaid.ink or auto-download Mermaid CLI.
+- If CJK text renders as boxes, install a CJK font such as Noto CJK or provide the intended system font.
+- If digits disappear in Chrome/PDFium output, verify the runtime has Latin fonts such as Liberation Sans or DejaVu Sans and render a PDFium screenshot to confirm.
+- Do not look for Pandoc; this CLI uses `markdown-it-py` and WeasyPrint.

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/mdtopdf/themes/default.css

@@ -5,7 +5,7 @@
 
 :root {
   color: #172033;
-  font-family: "Microsoft YaHei", "PingFang SC", "Hiragino Sans GB", "Noto Sans SC", "Noto Sans CJK SC", "Source Han Sans SC", "Segoe UI", "Segoe UI Emoji", Arial, "Apple Color Emoji", "Noto Emoji", "Noto Color Emoji", sans-serif;
+  font-family: "Segoe UI", Arial, "Liberation Sans", "DejaVu Sans", "Microsoft YaHei", "PingFang SC", "Hiragino Sans GB", "Noto Sans SC", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", sans-serif;
   font-size: 11.5pt;
   line-height: 1.55;
 }
@@ -497,7 +497,7 @@ table.math-array .math-inline {
 .mathlabel {
   color: #1474b4;
   float: right;
-  font-family: "Microsoft YaHei", "PingFang SC", "Hiragino Sans GB", "Noto Sans SC", "Noto Sans CJK SC", "Source Han Sans SC", "Segoe UI", Arial, sans-serif;
+  font-family: "Segoe UI", Arial, "Liberation Sans", "DejaVu Sans", "Microsoft YaHei", "PingFang SC", "Hiragino Sans GB", "Noto Sans SC", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", sans-serif;
   font-size: 0.85em;
 }
 
@@ -586,7 +586,7 @@ blockquote.callout .callout-title::before {
   color: #ffffff;
   content: "i";
   display: inline-block;
-  font-family: "Microsoft YaHei", "PingFang SC", "Noto Sans SC", "Noto Sans CJK SC", "Segoe UI", Arial, sans-serif;
+  font-family: "Segoe UI", Arial, "Liberation Sans", "DejaVu Sans", "Microsoft YaHei", "PingFang SC", "Noto Sans SC", "Noto Sans CJK SC", "Source Han Sans SC", sans-serif;
   font-size: 0.78em;
   font-weight: 800;
   height: 1.34em;

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-markdown-pdf"
-version = "0.2.0"
+version = "0.2.1"
 description = "Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics"
 readme = "README.md"
 requires-python = ">=3.10"

{agent_markdown_pdf-0.2.0 → agent_markdown_pdf-0.2.1}/tests/test_core.py

@@ -635,6 +635,7 @@ def test_prepare_mermaid_svg_rewrites_foreign_object_labels():
 
     assert "<foreignObject" not in prepared
     assert "<text" in prepared
+    assert 'font-family="Segoe UI, Arial, Liberation Sans, DejaVu Sans' in prepared
     assert "Node A" in prepared
 
 
@@ -780,7 +781,8 @@ def test_theme_loading():
 
     assert "@page" in css
     assert "A4" in css
-    assert '"Microsoft YaHei", "PingFang SC", "Hiragino Sans GB"' in css
+    assert '"Segoe UI", Arial, "Liberation Sans", "DejaVu Sans"' in css
+    assert css.index('"Segoe UI", Arial') < css.index('"Microsoft YaHei"')
     assert ".mdtopdf-emoji {" in css
     emoji_block = css.rsplit(".mdtopdf-emoji {", 1)[1].split("}", 1)[0]
     assert emoji_block.index('"Segoe UI Emoji"') < emoji_block.index('"Noto Color Emoji"')
@@ -971,6 +973,7 @@ def test_page_header_footer_can_be_disabled_or_overridden():
     assert "@bottom-center" not in disabled.css
     assert 'content: "Quoted \\"Title\\"";' in custom.css
     assert 'content: "Draft";' in custom.css
+    assert 'font-family: "Segoe UI", Arial, "Liberation Sans", "DejaVu Sans"' in custom.css
     assert "counter(page)" not in custom.css
 
 
@@ -1171,6 +1174,7 @@ def test_doctor_json_shape():
     assert "tools" in result
     assert "mermaid" in result["tools"]
     assert "fonts" in result
+    assert "latin_sans" in result["fonts"]["groups"]
     assert "cjk_sans" in result["fonts"]["groups"]
     assert "recommendations" in result
 
@@ -1179,7 +1183,7 @@ def test_doctor_font_groups_match_default_theme_font_fallbacks(monkeypatch):
     monkeypatch.setattr(
         fonts_core,
         "available_font_names",
-        lambda: {"Microsoft YaHei", "Consolas", "Cambria Math", "Segoe UI Emoji"},
+        lambda: {"Arial", "Microsoft YaHei", "Consolas", "Cambria Math", "Segoe UI Emoji"},
     )
     monkeypatch.setattr(
         fonts_core,
@@ -1190,12 +1194,121 @@ def test_doctor_font_groups_match_default_theme_font_fallbacks(monkeypatch):
     result = doctor._inspect_fonts()
 
     assert result["ok"] is True
+    assert result["groups"]["latin_sans"]["found"] == ["Arial"]
+    assert result["groups"]["latin_sans"]["preferred_found"] is True
     assert result["groups"]["cjk_sans"]["found"] == ["Microsoft YaHei"]
+    assert result["groups"]["cjk_sans"]["preferred"] == ["Microsoft YaHei"]
+    assert result["groups"]["cjk_sans"]["preferred_found"] is True
     assert result["groups"]["monospace"]["found"] == ["Consolas"]
+    assert result["groups"]["monospace"]["preferred"] == ["Cascadia Mono", "Cascadia Code"]
+    assert result["groups"]["monospace"]["preferred_found"] is False
     assert result["groups"]["math"]["found"] == ["Cambria Math"]
     assert result["groups"]["emoji"]["found"] == ["Segoe UI Emoji"]
 
 
+def test_doctor_linux_recommends_windows_like_preferred_fonts():
+    result = {
+        "ok": True,
+        "platform": {"system": "Linux"},
+        "packages": {
+            "weasyprint": {"ok": True},
+            "mini-racer": {"ok": True},
+            "latex2mathml": {"ok": True},
+            "matplotlib": {"ok": True},
+        },
+        "tools": {
+            "mermaid": {"ok": True},
+            "fontconfig": {"ok": True},
+        },
+        "fonts": {
+            "groups": {
+                "cjk_sans": {
+                    "ok": True,
+                    "found": ["Noto Sans CJK SC"],
+                    "missing": ["Microsoft YaHei"],
+                },
+                "latin_sans": {
+                    "ok": True,
+                    "found": ["Liberation Sans"],
+                    "missing": ["Segoe UI", "Arial", "DejaVu Sans"],
+                },
+                "monospace": {
+                    "ok": True,
+                    "found": ["Liberation Mono"],
+                    "missing": ["Cascadia Mono", "Cascadia Code"],
+                },
+                "math": {"ok": True, "found": ["STIXGeneral"], "missing": ["Cambria Math"]},
+                "emoji": {"ok": True, "found": ["Noto Color Emoji"], "missing": ["Segoe UI Emoji"]},
+            }
+        },
+    }
+
+    recommendations = doctor._recommendations(result)
+
+    assert any("Microsoft YaHei" in item and "Windows-like" in item for item in recommendations)
+    assert any("Cascadia Code" in item and "code blocks" in item for item in recommendations)
+
+
+def test_doctor_linux_recommends_fontconfig_when_missing():
+    result = {
+        "ok": True,
+        "platform": {"system": "Linux"},
+        "packages": {
+            "weasyprint": {"ok": True},
+            "mini-racer": {"ok": True},
+            "latex2mathml": {"ok": True},
+            "matplotlib": {"ok": True},
+        },
+        "tools": {
+            "mermaid": {"ok": True},
+            "fontconfig": {"ok": False, "error": "fc-match was not found on PATH."},
+        },
+        "fonts": {
+            "groups": {
+                "cjk_sans": {"ok": True, "found": ["Microsoft YaHei"], "missing": []},
+                "latin_sans": {"ok": True, "found": ["Arial"], "missing": []},
+                "monospace": {"ok": True, "found": ["Cascadia Code"], "missing": []},
+                "math": {"ok": True, "found": ["Cambria Math"], "missing": []},
+                "emoji": {"ok": True, "found": ["Segoe UI Emoji"], "missing": []},
+            }
+        },
+    }
+
+    recommendations = doctor._recommendations(result)
+
+    assert any("fontconfig" in item for item in recommendations)
+
+
+def test_doctor_recommends_latin_fonts_when_missing():
+    result = {
+        "ok": True,
+        "platform": {"system": "Linux"},
+        "packages": {
+            "weasyprint": {"ok": True},
+            "mini-racer": {"ok": True},
+            "latex2mathml": {"ok": True},
+            "matplotlib": {"ok": True},
+        },
+        "tools": {
+            "mermaid": {"ok": True},
+            "fontconfig": {"ok": True},
+        },
+        "fonts": {
+            "groups": {
+                "latin_sans": {"ok": False, "found": [], "missing": ["Segoe UI", "Arial", "Liberation Sans"]},
+                "cjk_sans": {"ok": True, "found": ["Noto Sans CJK SC"], "missing": ["Microsoft YaHei"]},
+                "monospace": {"ok": True, "found": ["Liberation Mono"], "missing": ["Cascadia Code"]},
+                "math": {"ok": True, "found": ["STIXGeneral"], "missing": ["Cambria Math"]},
+                "emoji": {"ok": True, "found": ["Noto Color Emoji"], "missing": ["Segoe UI Emoji"]},
+            }
+        },
+    }
+
+    recommendations = doctor._recommendations(result)
+
+    assert any("Latin sans" in item and "digits" in item for item in recommendations)
+
+
 def test_doctor_reports_missing_mini_racer(monkeypatch):
     real_import = importlib.import_module
 

agent_markdown_pdf-0.2.0/mdtopdf/skills/SKILL.md

@@ -1,108 +0,0 @@
----
-name: "mdtopdf"
-description: "Use when an agent needs to install or run mdtopdf: an agent-friendly Markdown-to-PDF CLI with JSON diagnostics, HTML preview, Obsidian-compatible Markdown, local KaTeX math, optional local Mermaid rendering, and WeasyPrint environment checks."
----
-
-# mdtopdf
-
-Use this skill to turn local Markdown into a local PDF with the `mdtopdf` CLI.
-Prefer the CLI over the Python API unless the user explicitly asks for code
-integration.
-
-## Names
-
-| Purpose | Name |
-| --- | --- |
-| PyPI distribution | `agent-markdown-pdf` |
-| CLI command | `mdtopdf` |
-| Python import | `mdtopdf` |
-
-Install the package when the command is missing:
-
-```powershell
-python -m pip install agent-markdown-pdf
-```
-
-## Workflow
-
-Check a new or unknown machine first:
-
-```powershell
-mdtopdf doctor --json
-```
-
-Generate a PDF:
-
-```powershell
-mdtopdf convert .\input.md -o .\output.pdf --overwrite --json
-```
-
-Use HTML preview only when layout needs debugging:
-
-```powershell
-mdtopdf html .\input.md -o .\preview.html --overwrite --json
-mdtopdf convert .\input.md -o .\output.pdf --overwrite --json
-```
-
-## Resource Paths
-
-- Use `--base-url PATH_OR_URL` when the Markdown contains relative images or links.
-- Use `--resource-dir PATH` for Obsidian-style image names such as `![[image.png]]`.
-- Use `--css custom.css` when the user provides print CSS.
-- Conversion checks CSS font stacks after theme and custom CSS are combined.
-  Missing fonts are warnings, not hard failures.
-- Use `--unsafe-html` only for trusted local Markdown.
-
-## Environment Fixes
-
-`mdtopdf` uses WeasyPrint, so PDF output needs native Pango, GLib, and Cairo
-libraries.
-
-On Windows, run `mdtopdf doctor --json` before guessing. If the JSON output says
-native DLLs are missing, install MSYS2 Pango and set the DLL directory for that
-machine, for example:
-
-```powershell
-pacman -S mingw-w64-x86_64-pango
-setx WEASYPRINT_DLL_DIRECTORIES "D:\Environment\msys64\mingw64\bin"
-```
-
-The exact MSYS2 path may differ.
-
-On Linux containers, install the native WeasyPrint packages before installing
-`agent-markdown-pdf`.
-
-For stable Chinese/Japanese/Korean and emoji output in containers, install the
-CJK and emoji fonts the user wants. Emoji spans prefer Segoe UI Emoji on every
-platform, including Linux. Linux containers only get the same glyphs when that
-font is available in the runtime; otherwise mdtopdf falls back to installed
-emoji fonts such as Apple Color Emoji, Noto Emoji, or Noto Color Emoji. Noto
-CJK plus Noto Color Emoji is still a practical open-font fallback on Debian or
-Ubuntu, but color emoji in the final PDF is best-effort because it depends on
-WeasyPrint, Pango/Cairo, and the PDF viewer:
-
-```shell
-apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-stix fonts-dejavu-core
-fc-cache -f
-```
-
-`mdtopdf doctor --json` reports recommended CJK, emoji, monospace, and math
-fallback font availability. Missing fonts do not always stop conversion, but
-they can change glyph coverage, emoji size, line breaks, and pagination.
-
-## Failure Handling
-
-- Prefer `--json` so failures are structured.
-- If CJK text renders as boxes or pagination differs between machines, install
-  Noto CJK fonts and rerun the conversion.
-- If emoji render as boxes, missing glyphs, or tiny glyphs on Linux, provide
-  Segoe UI Emoji in the runtime or install a fallback emoji font, run
-  `fc-cache -f`, and rerun the conversion.
-- If conversion fails with a WeasyPrint, Pango, GLib, Cairo, or DLL error, run
-  `mdtopdf doctor --json` and follow its recommendations.
-- If Mermaid diagrams do not render, check whether local `mmdc` is installed.
-  Mermaid is optional; `mdtopdf` does not call Mermaid.ink or download Mermaid
-  CLI during conversion.
-- Do not look for Pandoc; this CLI uses `markdown-it-py` and WeasyPrint.
-- Report the exact command, JSON error, and output path when handing results
-  back to the user.