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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.1.2
+Version: 0.2.1
 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,53 @@ 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 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:
+
+```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
+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:
 
 ```powershell
@@ -310,7 +389,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
+Latin, CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -336,3 +416,9 @@ 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 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.1.2 → agent_markdown_pdf-0.2.1}/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,53 @@ 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 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:
+
+```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
+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:
 
 ```powershell
@@ -269,7 +348,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
+Latin, CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -295,3 +375,9 @@ 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 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.1.2 → 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.1.2
+Version: 0.2.1
 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,53 @@ 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 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:
+
+```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
+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:
 
 ```powershell
@@ -310,7 +389,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
+Latin, CJK, emoji, monospace, and math fallback fonts are present:
 
 ```shell
 mdtopdf doctor --json
@@ -336,3 +416,9 @@ 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 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.1.2 → agent_markdown_pdf-0.2.1}/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.1}/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.1}/mdtopdf/core/doctor.py

@@ -4,10 +4,13 @@ import ctypes
 import importlib
 import os
 import platform
+import shutil
+import subprocess
 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 +24,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 +69,7 @@ def run_doctor() -> dict[str, Any]:
         "packages": {},
         "tools": {},
         "native_libraries": _inspect_native_libraries(),
+        "fonts": _inspect_fonts(),
         "recommendations": [],
     }
 
@@ -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
@@ -115,6 +119,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,8 +211,42 @@ 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 _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")
@@ -215,6 +266,63 @@ 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(
+            "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(
+            "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(
+            "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)