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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.2.1
+Version: 0.2.2
 Summary: Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics
 Author: rainp
 License-Expression: MIT
@@ -326,28 +326,25 @@ 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.
+poorly. Chinese text still falls back to the CJK side of the stack.
 
-For Linux containers or agent sandboxes, install fontconfig plus the fonts you
-expect the default theme to use. A practical open-font baseline is:
+For Linux containers or agent sandboxes, use open fonts that can be installed
+from the distribution package manager. The recommended baseline is:
 
 ```shell
 sudo apt-get install -y --no-install-recommends \
   fontconfig \
-  fonts-noto-cjk \
   fonts-liberation \
-  fonts-dejavu-core
+  fonts-dejavu-core \
+  fonts-noto-cjk \
+  fonts-stix
 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.
+With that setup, Linux output uses `Liberation Sans` / `DejaVu Sans` for Latin
+text and digits, `Noto Sans CJK SC` for Chinese, and STIX for math fallback.
+Microsoft YaHei and Segoe UI Emoji are not Linux runtime requirements and are
+not installed or distributed by `mdtopdf`.
 
 Code blocks prefer `Cascadia Mono` / `Cascadia Code`, then `Consolas`,
 `Noto Sans Mono CJK SC`, `Liberation Mono`, and `DejaVu Sans Mono`. On Debian,
@@ -355,20 +352,10 @@ Code blocks prefer `Cascadia Mono` / `Cascadia Code`, then `Consolas`,
 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
-```
+Emoji are rendered through the system emoji font. On Linux, prefer monochrome
+`Noto Emoji` for stable PDF layout. `Noto Color Emoji` is easier to install from
+many distro package managers and is safe to use as a fallback, but color emoji
+often render too small or misaligned in WeasyPrint/Pango/Cairo/PDFium output.
 
 On Windows, install the native libraries separately. A common MSYS2 setup is:
 
@@ -419,6 +406,7 @@ MIT. Bundled KaTeX assets are also distributed under the MIT license; see
 
 `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.

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

@@ -285,28 +285,25 @@ 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.
+poorly. Chinese text still falls back to the CJK side of the stack.
 
-For Linux containers or agent sandboxes, install fontconfig plus the fonts you
-expect the default theme to use. A practical open-font baseline is:
+For Linux containers or agent sandboxes, use open fonts that can be installed
+from the distribution package manager. The recommended baseline is:
 
 ```shell
 sudo apt-get install -y --no-install-recommends \
   fontconfig \
-  fonts-noto-cjk \
   fonts-liberation \
-  fonts-dejavu-core
+  fonts-dejavu-core \
+  fonts-noto-cjk \
+  fonts-stix
 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.
+With that setup, Linux output uses `Liberation Sans` / `DejaVu Sans` for Latin
+text and digits, `Noto Sans CJK SC` for Chinese, and STIX for math fallback.
+Microsoft YaHei and Segoe UI Emoji are not Linux runtime requirements and are
+not installed or distributed by `mdtopdf`.
 
 Code blocks prefer `Cascadia Mono` / `Cascadia Code`, then `Consolas`,
 `Noto Sans Mono CJK SC`, `Liberation Mono`, and `DejaVu Sans Mono`. On Debian,
@@ -314,20 +311,10 @@ Code blocks prefer `Cascadia Mono` / `Cascadia Code`, then `Consolas`,
 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
-```
+Emoji are rendered through the system emoji font. On Linux, prefer monochrome
+`Noto Emoji` for stable PDF layout. `Noto Color Emoji` is easier to install from
+many distro package managers and is safe to use as a fallback, but color emoji
+often render too small or misaligned in WeasyPrint/Pango/Cairo/PDFium output.
 
 On Windows, install the native libraries separately. A common MSYS2 setup is:
 
@@ -378,6 +365,7 @@ MIT. Bundled KaTeX assets are also distributed under the MIT license; see
 
 `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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-markdown-pdf
-Version: 0.2.1
+Version: 0.2.2
 Summary: Agent-friendly Markdown-to-PDF CLI with HTML preview and JSON diagnostics
 Author: rainp
 License-Expression: MIT
@@ -326,28 +326,25 @@ 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.
+poorly. Chinese text still falls back to the CJK side of the stack.
 
-For Linux containers or agent sandboxes, install fontconfig plus the fonts you
-expect the default theme to use. A practical open-font baseline is:
+For Linux containers or agent sandboxes, use open fonts that can be installed
+from the distribution package manager. The recommended baseline is:
 
 ```shell
 sudo apt-get install -y --no-install-recommends \
   fontconfig \
-  fonts-noto-cjk \
   fonts-liberation \
-  fonts-dejavu-core
+  fonts-dejavu-core \
+  fonts-noto-cjk \
+  fonts-stix
 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.
+With that setup, Linux output uses `Liberation Sans` / `DejaVu Sans` for Latin
+text and digits, `Noto Sans CJK SC` for Chinese, and STIX for math fallback.
+Microsoft YaHei and Segoe UI Emoji are not Linux runtime requirements and are
+not installed or distributed by `mdtopdf`.
 
 Code blocks prefer `Cascadia Mono` / `Cascadia Code`, then `Consolas`,
 `Noto Sans Mono CJK SC`, `Liberation Mono`, and `DejaVu Sans Mono`. On Debian,
@@ -355,20 +352,10 @@ Code blocks prefer `Cascadia Mono` / `Cascadia Code`, then `Consolas`,
 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
-```
+Emoji are rendered through the system emoji font. On Linux, prefer monochrome
+`Noto Emoji` for stable PDF layout. `Noto Color Emoji` is easier to install from
+many distro package managers and is safe to use as a fallback, but color emoji
+often render too small or misaligned in WeasyPrint/Pango/Cairo/PDFium output.
 
 On Windows, install the native libraries separately. A common MSYS2 setup is:
 
@@ -419,6 +406,7 @@ MIT. Bundled KaTeX assets are also distributed under the MIT license; see
 
 `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.

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

@@ -52,10 +52,11 @@ def run_doctor() -> dict[str, Any]:
 
     add_weasyprint_dll_directories()
 
+    platform_system = platform.system()
     result: dict[str, Any] = {
         "ok": False,
         "platform": {
-            "system": platform.system(),
+            "system": platform_system,
             "release": platform.release(),
             "machine": platform.machine(),
         },
@@ -69,7 +70,7 @@ def run_doctor() -> dict[str, Any]:
         "packages": {},
         "tools": {},
         "native_libraries": _inspect_native_libraries(),
-        "fonts": _inspect_fonts(),
+        "fonts": _inspect_fonts(platform_system),
         "recommendations": [],
     }
 
@@ -211,8 +212,8 @@ 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_fonts(platform_system: str | None = None) -> dict[str, Any]:
+    return inspect_recommended_font_groups(platform_system)
 
 
 def _inspect_fontconfig() -> dict[str, Any]:
@@ -283,15 +284,15 @@ def _recommendations(result: dict[str, Any]) -> list[str]:
             "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 is_linux:
+            recommendations.append(
+                "Install Noto CJK for Chinese text on Linux: sudo apt-get install fonts-noto-cjk"
+            )
+        else:
+            recommendations.append(
+                "Install or enable a CJK sans font for Chinese text, such as Microsoft YaHei, "
+                "PingFang SC, Noto Sans CJK SC, or Source Han Sans SC."
+            )
     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: "
@@ -314,11 +315,32 @@ def _recommendations(result: dict[str, Any]) -> list[str]:
             "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"):
+        if is_linux:
+            recommendations.append(
+                "Provide a monochrome emoji font such as Noto Emoji for stable PDF output on Linux. "
+                "Noto Color Emoji is widely packaged, but PDF viewers can render color emoji too small "
+                "or misaligned."
+            )
+        else:
+            recommendations.append(
+                "Install or enable a system emoji font such as Segoe UI Emoji, Apple Color Emoji, "
+                "Noto Color Emoji, or Twemoji Mozilla."
+            )
+    elif (
+        is_linux
+        and font_groups.get("emoji")
+        and "Noto Emoji" in font_groups["emoji"].get("missing", [])
+        and "Noto Color Emoji" in font_groups["emoji"].get("found", [])
+    ):
         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."
+            "Noto Color Emoji was found. It provides glyph coverage, but color emoji can render too small "
+            "or misaligned in WeasyPrint/PDFium output. Prefer monochrome Noto Emoji if emoji layout matters."
         )
-    elif font_groups.get("emoji") and "Segoe UI Emoji" in font_groups["emoji"].get("missing", []):
+    elif (
+        not is_linux
+        and 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."

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

@@ -91,6 +91,14 @@ RECOMMENDED_FONT_GROUPS = {
         ),
     },
 }
+PLATFORM_PREFERRED_FONT_GROUPS = {
+    "Linux": {
+        "latin_sans": ("Liberation Sans", "DejaVu Sans"),
+        "cjk_sans": ("Noto Sans CJK SC", "Noto Sans SC"),
+        "math": ("STIXGeneral", "STIX Two Math"),
+        "emoji": ("Noto Emoji",),
+    },
+}
 CJK_CAPABLE_FONT_FAMILIES = (
     "Noto Sans SC",
     "Noto Sans CJK SC",
@@ -136,7 +144,7 @@ def match_font_name(family: str, available: set[str]) -> str | None:
     return None
 
 
-def inspect_recommended_font_groups() -> dict[str, Any]:
+def inspect_recommended_font_groups(platform_system: str | None = None) -> dict[str, Any]:
     result: dict[str, Any] = {
         "ok": False,
         "backend": "matplotlib.font_manager",
@@ -153,7 +161,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]))
+        preferred = list(_preferred_families(group_name, group, platform_system))
         found = []
         for family in recommended:
             match = match_font_name(family, available)
@@ -180,6 +188,17 @@ def inspect_recommended_font_groups() -> dict[str, Any]:
     return result
 
 
+def _preferred_families(
+    group_name: str,
+    group: dict[str, Any],
+    platform_system: str | None,
+) -> tuple[str, ...]:
+    platform_preferred = PLATFORM_PREFERRED_FONT_GROUPS.get(platform_system or "", {})
+    if isinstance(platform_preferred, dict) and group_name in platform_preferred:
+        return platform_preferred[group_name]
+    return group.get("preferred", group["families"][:1])
+
+
 def inspect_css_font_usage(css: str, *, document_text: str | None = None) -> dict[str, Any]:
     result: dict[str, Any] = {
         "ok": True,

{agent_markdown_pdf-0.2.1 → agent_markdown_pdf-0.2.2}/mdtopdf/skills/SKILL.md

@@ -75,15 +75,19 @@ apt-get install -y --no-install-recommends \
   shared-mime-info \
   fonts-liberation \
   fonts-dejavu-core \
-  fonts-noto-cjk
+  fonts-noto-cjk \
+  fonts-stix
 fc-cache -f
 ```
 
+For emoji-heavy documents on Linux, prefer a monochrome emoji font such as
+Noto Emoji. `fonts-noto-color-emoji` is a fallback, but it can render too small
+or misaligned in PDF viewers.
+
 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:

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-markdown-pdf"
-version = "0.2.1"
+version = "0.2.2"
 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.1 → agent_markdown_pdf-0.2.2}/tests/test_core.py

@@ -1191,7 +1191,7 @@ def test_doctor_font_groups_match_default_theme_font_fallbacks(monkeypatch):
         lambda: {"ok": False, "families": [], "file": None, "error": "not found"},
     )
 
-    result = doctor._inspect_fonts()
+    result = doctor._inspect_fonts("Windows")
 
     assert result["ok"] is True
     assert result["groups"]["latin_sans"]["found"] == ["Arial"]
@@ -1206,7 +1206,37 @@ def test_doctor_font_groups_match_default_theme_font_fallbacks(monkeypatch):
     assert result["groups"]["emoji"]["found"] == ["Segoe UI Emoji"]
 
 
-def test_doctor_linux_recommends_windows_like_preferred_fonts():
+def test_doctor_linux_font_groups_prefer_open_font_baseline(monkeypatch):
+    monkeypatch.setattr(
+        fonts_core,
+        "available_font_names",
+        lambda: {
+            "Liberation Sans",
+            "DejaVu Sans",
+            "Noto Sans CJK SC",
+            "Cascadia Mono",
+            "STIXGeneral",
+            "Noto Emoji",
+            "Noto Color Emoji",
+        },
+    )
+    monkeypatch.setattr(
+        fonts_core,
+        "_fontconfig_emoji_match",
+        lambda: {"ok": True, "families": ["Noto Color Emoji"], "file": None, "error": None},
+    )
+
+    result = doctor._inspect_fonts("Linux")
+
+    assert result["groups"]["latin_sans"]["preferred"] == ["Liberation Sans", "DejaVu Sans"]
+    assert result["groups"]["cjk_sans"]["preferred"] == ["Noto Sans CJK SC", "Noto Sans SC"]
+    assert result["groups"]["emoji"]["preferred"] == ["Noto Emoji"]
+    assert result["groups"]["latin_sans"]["preferred_found"] is True
+    assert result["groups"]["cjk_sans"]["preferred_found"] is True
+    assert result["groups"]["emoji"]["preferred_found"] is True
+
+
+def test_doctor_linux_accepts_open_font_baseline_without_microsoft_recommendations():
     result = {
         "ok": True,
         "platform": {"system": "Linux"},
@@ -1238,15 +1268,17 @@ def test_doctor_linux_recommends_windows_like_preferred_fonts():
                     "missing": ["Cascadia Mono", "Cascadia Code"],
                 },
                 "math": {"ok": True, "found": ["STIXGeneral"], "missing": ["Cambria Math"]},
-                "emoji": {"ok": True, "found": ["Noto Color Emoji"], "missing": ["Segoe UI Emoji"]},
+                "emoji": {"ok": True, "found": ["Noto Color Emoji"], "missing": ["Segoe UI Emoji", "Noto Emoji"]},
             }
         },
     }
 
     recommendations = doctor._recommendations(result)
 
-    assert any("Microsoft YaHei" in item and "Windows-like" in item for item in recommendations)
+    assert not any("Microsoft YaHei" in item for item in recommendations)
+    assert not any("Segoe UI Emoji" in item for item in recommendations)
     assert any("Cascadia Code" in item and "code blocks" in item for item in recommendations)
+    assert any("Noto Color Emoji" in item and "Noto Emoji" in item for item in recommendations)
 
 
 def test_doctor_linux_recommends_fontconfig_when_missing():
@@ -1309,6 +1341,39 @@ def test_doctor_recommends_latin_fonts_when_missing():
     assert any("Latin sans" in item and "digits" in item for item in recommendations)
 
 
+def test_doctor_linux_recommends_noto_fonts_when_cjk_or_emoji_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": True, "found": ["Liberation Sans"], "missing": []},
+                "cjk_sans": {"ok": False, "found": [], "missing": ["Noto Sans CJK SC"]},
+                "monospace": {"ok": True, "found": ["Cascadia Code"], "missing": []},
+                "math": {"ok": True, "found": ["STIXGeneral"], "missing": []},
+                "emoji": {"ok": False, "found": [], "missing": ["Noto Emoji"]},
+            }
+        },
+    }
+
+    recommendations = doctor._recommendations(result)
+
+    assert any("fonts-noto-cjk" in item for item in recommendations)
+    assert any("Noto Emoji" in item and "monochrome" in item for item in recommendations)
+    assert not any("Microsoft YaHei" in item for item in recommendations)
+    assert not any("Segoe UI Emoji" in item for item in recommendations)
+
+
 def test_doctor_reports_missing_mini_racer(monkeypatch):
     real_import = importlib.import_module