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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.1.2
+Version: 0.2.0
 Summary: Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics
 Author: rainp
 License-Expression: MIT
@@ -140,10 +140,10 @@ mdtopdf html report.md -o report.html --overwrite --json
 mdtopdf convert report.md -o report.pdf --overwrite --json
 ```
 
-`convert --json` returns the input path, output path, file size, theme, 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.
+`convert --json` returns the input path, output path, file size, theme, font
+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.
 
 ## Visual output
 
@@ -175,7 +175,7 @@ remain visible as highlighted code.
 | 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, and Mermaid availability. |
+| Environment checks | `doctor --json` checks Python imports, native WeasyPrint libraries, Windows DLL paths, Mermaid availability, 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. |
@@ -215,6 +215,38 @@ mdtopdf convert report.md -o report.pdf --base-url assets
 mdtopdf convert report.md -o report.pdf --resource-dir attachments
 ```
 
+Custom CSS is the style extension point. Put document-specific rules in a CSS
+file; fonts, spacing, colors, page rules, and code block styling all live there.
+Use a system-installed font directly, or define `@font-face` for a local font
+file. Relative URLs in CSS are resolved from the Markdown file's base URL, so
+use `--base-url` when those assets live next to your document:
+
+```css
+@font-face {
+  font-family: "Report Sans";
+  src: url("fonts/NotoSansSC-Regular.otf");
+}
+
+:root {
+  font-family: "Report Sans", "Noto Sans SC", "Source Han Sans SC", sans-serif;
+}
+
+code,
+pre {
+  font-family: "Cascadia Code", "Liberation Mono", monospace;
+}
+```
+
+Then pass the CSS file:
+
+```shell
+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.
+
 Return JSON:
 
 ```shell
@@ -291,6 +323,31 @@ 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.
+
+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:
+
+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.
+
+On Debian or Ubuntu, this is a practical open-font fallback baseline:
+
+```shell
+sudo apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-stix fonts-dejavu-core
+fc-cache -f
+```
+
 On Windows, install the native libraries separately. A common MSYS2 setup is:
 
 ```powershell
@@ -310,7 +367,8 @@ if MSYS2 is installed somewhere else:
 setx WEASYPRINT_DLL_DIRECTORIES "C:\msys64\mingw64\bin"
 ```
 
-Run this after installation:
+Run this after installation. The JSON output also reports whether recommended
+CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -336,3 +394,8 @@ python -m twine check dist/*
 
 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.

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

@@ -99,10 +99,10 @@ mdtopdf html report.md -o report.html --overwrite --json
 mdtopdf convert report.md -o report.pdf --overwrite --json
 ```
 
-`convert --json` returns the input path, output path, file size, theme, 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.
+`convert --json` returns the input path, output path, file size, theme, font
+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.
 
 ## Visual output
 
@@ -134,7 +134,7 @@ remain visible as highlighted code.
 | 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, and Mermaid availability. |
+| Environment checks | `doctor --json` checks Python imports, native WeasyPrint libraries, Windows DLL paths, Mermaid availability, 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. |
@@ -174,6 +174,38 @@ mdtopdf convert report.md -o report.pdf --base-url assets
 mdtopdf convert report.md -o report.pdf --resource-dir attachments
 ```
 
+Custom CSS is the style extension point. Put document-specific rules in a CSS
+file; fonts, spacing, colors, page rules, and code block styling all live there.
+Use a system-installed font directly, or define `@font-face` for a local font
+file. Relative URLs in CSS are resolved from the Markdown file's base URL, so
+use `--base-url` when those assets live next to your document:
+
+```css
+@font-face {
+  font-family: "Report Sans";
+  src: url("fonts/NotoSansSC-Regular.otf");
+}
+
+:root {
+  font-family: "Report Sans", "Noto Sans SC", "Source Han Sans SC", sans-serif;
+}
+
+code,
+pre {
+  font-family: "Cascadia Code", "Liberation Mono", monospace;
+}
+```
+
+Then pass the CSS file:
+
+```shell
+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.
+
 Return JSON:
 
 ```shell
@@ -250,6 +282,31 @@ 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.
+
+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:
+
+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.
+
+On Debian or Ubuntu, this is a practical open-font fallback baseline:
+
+```shell
+sudo apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-stix fonts-dejavu-core
+fc-cache -f
+```
+
 On Windows, install the native libraries separately. A common MSYS2 setup is:
 
 ```powershell
@@ -269,7 +326,8 @@ if MSYS2 is installed somewhere else:
 setx WEASYPRINT_DLL_DIRECTORIES "C:\msys64\mingw64\bin"
 ```
 
-Run this after installation:
+Run this after installation. The JSON output also reports whether recommended
+CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -295,3 +353,8 @@ python -m twine check dist/*
 
 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.1.2
+Version: 0.2.0
 Summary: Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics
 Author: rainp
 License-Expression: MIT
@@ -140,10 +140,10 @@ mdtopdf html report.md -o report.html --overwrite --json
 mdtopdf convert report.md -o report.pdf --overwrite --json
 ```
 
-`convert --json` returns the input path, output path, file size, theme, 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.
+`convert --json` returns the input path, output path, file size, theme, font
+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.
 
 ## Visual output
 
@@ -175,7 +175,7 @@ remain visible as highlighted code.
 | 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, and Mermaid availability. |
+| Environment checks | `doctor --json` checks Python imports, native WeasyPrint libraries, Windows DLL paths, Mermaid availability, 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. |
@@ -215,6 +215,38 @@ mdtopdf convert report.md -o report.pdf --base-url assets
 mdtopdf convert report.md -o report.pdf --resource-dir attachments
 ```
 
+Custom CSS is the style extension point. Put document-specific rules in a CSS
+file; fonts, spacing, colors, page rules, and code block styling all live there.
+Use a system-installed font directly, or define `@font-face` for a local font
+file. Relative URLs in CSS are resolved from the Markdown file's base URL, so
+use `--base-url` when those assets live next to your document:
+
+```css
+@font-face {
+  font-family: "Report Sans";
+  src: url("fonts/NotoSansSC-Regular.otf");
+}
+
+:root {
+  font-family: "Report Sans", "Noto Sans SC", "Source Han Sans SC", sans-serif;
+}
+
+code,
+pre {
+  font-family: "Cascadia Code", "Liberation Mono", monospace;
+}
+```
+
+Then pass the CSS file:
+
+```shell
+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.
+
 Return JSON:
 
 ```shell
@@ -291,6 +323,31 @@ 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.
+
+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:
+
+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.
+
+On Debian or Ubuntu, this is a practical open-font fallback baseline:
+
+```shell
+sudo apt-get install -y fonts-noto-cjk fonts-noto-color-emoji fonts-stix fonts-dejavu-core
+fc-cache -f
+```
+
 On Windows, install the native libraries separately. A common MSYS2 setup is:
 
 ```powershell
@@ -310,7 +367,8 @@ if MSYS2 is installed somewhere else:
 setx WEASYPRINT_DLL_DIRECTORIES "C:\msys64\mingw64\bin"
 ```
 
-Run this after installation:
+Run this after installation. The JSON output also reports whether recommended
+CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -336,3 +394,8 @@ python -m twine check dist/*
 
 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.

{agent_markdown_pdf-0.1.2 → agent_markdown_pdf-0.2.0}/agent_markdown_pdf.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ mdtopdf/api.py
 mdtopdf/mdtopdf_cli.py
 mdtopdf/core/__init__.py
 mdtopdf/core/doctor.py
+mdtopdf/core/fonts.py
 mdtopdf/core/html.py
 mdtopdf/core/inline.py
 mdtopdf/core/katex.py

{agent_markdown_pdf-0.1.2 → agent_markdown_pdf-0.2.0}/mdtopdf/api.py

@@ -13,6 +13,7 @@ from typing import Any
 from urllib.parse import urlparse
 
 from mdtopdf.core.doctor import add_weasyprint_dll_directories
+from mdtopdf.core.fonts import inspect_css_font_usage, summarize_font_usage
 from mdtopdf.core.html import convert_markdown_file_to_html
 from mdtopdf.core.markdown import DEFAULT_THEME, RenderedHTML, render_markdown_to_html
 from mdtopdf.core.obsidian import build_resource_resolver, resolve_resource_dir
@@ -143,6 +144,7 @@ def markdown_to_pdf(
         include_page_footer=include_page_footer,
         page_numbers=page_numbers,
     )
+    font_usage = inspect_css_font_usage(rendered.css, document_text=markdown_text)
 
     output.parent.mkdir(parents=True, exist_ok=True)
     try:
@@ -174,6 +176,8 @@ def markdown_to_pdf(
         "page_header": effective_header,
         "page_footer": effective_footer,
         "page_numbers": bool(include_page_footer and page_numbers),
+        "font_check": summarize_font_usage(font_usage),
+        "warnings": font_usage.get("warnings", []),
         "method": "markdown-it-py+weasyprint",
     }
 

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

@@ -8,6 +8,7 @@ import sys
 from pathlib import Path
 from typing import Any
 
+from mdtopdf.core.fonts import inspect_recommended_font_groups
 from mdtopdf.core.mermaid import inspect_mermaid_backend
 
 
@@ -21,8 +22,6 @@ COMMON_WINDOWS_DLL_DIRS = (
     r"C:\msys64\mingw64\bin",
     r"D:\Environment\msys64\mingw64\bin",
 )
-
-
 def add_weasyprint_dll_directories() -> list[str]:
     """Register Windows DLL search directories from ``WEASYPRINT_DLL_DIRECTORIES``."""
 
@@ -68,6 +67,7 @@ def run_doctor() -> dict[str, Any]:
         "packages": {},
         "tools": {},
         "native_libraries": _inspect_native_libraries(),
+        "fonts": _inspect_fonts(),
         "recommendations": [],
     }
 
@@ -115,6 +115,19 @@ def format_doctor_text(result: dict[str, Any]) -> str:
                 f"missing={', '.join(probe['missing']) or '(none)'}"
             )
 
+    if result.get("fonts"):
+        lines.extend(["", "Fonts:"])
+        font_error = result["fonts"].get("error")
+        if font_error:
+            lines.append(f"  - font inspection: FAIL - {font_error}")
+        for name, info in result["fonts"].get("groups", {}).items():
+            found = ", ".join(info.get("found", [])) or "(none)"
+            recommended = ", ".join(info.get("recommended", []))
+            lines.append(
+                f"  - {name}: {'OK' if info.get('ok') else 'MISSING'} "
+                f"found={found} recommended={recommended}"
+            )
+
     if result.get("recommendations"):
         lines.extend(["", "Recommendations:"])
         for item in result["recommendations"]:
@@ -194,6 +207,10 @@ def _env_dll_directories() -> list[str]:
     return [part.strip() for part in raw.split(os.pathsep) if part.strip()]
 
 
+def _inspect_fonts() -> dict[str, Any]:
+    return inspect_recommended_font_groups()
+
+
 def _recommendations(result: dict[str, Any]) -> list[str]:
     recommendations: list[str] = []
     package_info = result.get("packages", {}).get("weasyprint", {})
@@ -216,6 +233,34 @@ def _recommendations(result: dict[str, Any]) -> list[str]:
             "npm install -g @mermaid-js/mermaid-cli"
         )
 
+    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("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"
+        )
+    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."
+        )
+    if font_groups.get("math") and not font_groups["math"].get("ok"):
+        recommendations.append(
+            "Optional: install STIX fonts for math fallback, for example: sudo apt-get install fonts-stix"
+        )
+    if font_groups.get("emoji") and not font_groups["emoji"].get("ok"):
+        recommendations.append(
+            "Provide Segoe UI Emoji in the runtime if you want the default theme's first-choice "
+            "emoji glyphs. If that is not available, install another emoji font and run fc-cache -f."
+        )
+    elif font_groups.get("emoji") and "Segoe UI Emoji" in font_groups["emoji"].get("missing", []):
+        recommendations.append(
+            "Optional: provide Segoe UI Emoji if you want the default theme's preferred emoji glyphs. "
+            "Existing emoji fallback fonts will still be used."
+        )
+
     if os.name == "nt":
         env_value = result.get("environment", {}).get(WINDOWS_DLL_ENV)
         probes = result.get("native_libraries", [])