md2pdf-tool 0.1.0__tar.gz

md2pdf_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

md2pdf_tool-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include src/md2pdf *.css
+recursive-include tests *.py
+include gen_pdf.sh

md2pdf_tool-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: md2pdf-tool
+Version: 0.1.0
+Summary: Convert Markdown to a styled, Chinese-friendly A4 PDF with QA previews.
+Author-email: Ethan <zhangyuxin85@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ethanzhrepo/md2pdf
+Project-URL: Repository, https://github.com/ethanzhrepo/md2pdf
+Keywords: markdown,pdf,pandoc,playwright,chinese,cjk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Printing
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40
+Requires-Dist: PyMuPDF>=1.24
+Requires-Dist: Pillow>=10.0
+Dynamic: license-file
+
+# md2pdf
+
+Markdown 转 PDF 工具，专为中文文档优化：
+
+1. Pandoc 把 Markdown 转成带目录的 HTML。
+2. `md2pdf/style.css` 负责中文字体、封面、目录、标题、引用块、表格和分页样式。
+3. Playwright / headless Chrome 把 HTML 打印成 A4 PDF。
+4. PyMuPDF + Pillow 渲染 QA 图片和 `summary.txt`，用于检查页数、页面尺寸、乱码和抽检页面。
+
+## 安装
+
+需要先准备两个系统依赖（pip 无法安装）：
+
+- **pandoc**：`brew install pandoc`（macOS）/ `apt install pandoc`（Debian/Ubuntu）。
+- **浏览器**：装好 Python 包后运行 `playwright install chromium`，让 Playwright 下载自带的 Chromium；macOS 上若已装 Google Chrome 也可直接复用。
+
+然后安装本工具。发布名是 `md2pdf-tool`（PyPI 上 `md2pdf` 已被占用），命令仍是 `md2pdf`。
+
+**已发布后**，最终用户二选一：
+
+```bash
+# Homebrew（个人 tap）
+brew install <用户名>/md2pdf/md2pdf
+playwright install chromium
+
+# 或 pipx
+pipx install md2pdf-tool
+playwright install chromium
+```
+
+**从源码安装 / 开发**：
+
+```bash
+pipx install .          # 从仓库目录安装，得到全局 md2pdf 命令
+# 或可编辑安装：
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+playwright install chromium
+```
+
+发布到 PyPI 和搭建 Homebrew tap 的完整步骤见 [PUBLISHING.md](PUBLISHING.md)。
+
+## 使用
+
+安装后直接用 `md2pdf` 命令：
+
+```bash
+md2pdf docs/requirements.md
+```
+
+不传输出路径时，默认输出到同目录同名 `.pdf`；不传 `--title` 时，默认用文件名。
+
+也可以用 `gen_pdf.sh` 包装脚本——它会自动读取 Markdown 第一个一级标题作为封面标题：
+
+```bash
+./gen_pdf.sh docs/requirements.md docs/requirements.pdf
+./gen_pdf.sh --dry-run docs/requirements.md   # 只打印将要执行的命令
+```
+
+需要手动指定标题、副标题、日期或必检文本时，传对应参数：
+
+```bash
+md2pdf docs/requirements.md \
+  --output docs/requirements.pdf \
+  --title "4D交互式电子手册平台需求说明" \
+  --subtitle "面向大型企业私有化部署的创作、发布、播放与反馈闭环系统" \
+  --date "2026-06-03" \
+  --required-text "十八、最终一句话目标"
+```
+
+未安装时，也可以从仓库根目录用模块方式运行（需 `pip install -e .` 或设置 `PYTHONPATH=src`）：
+
+```bash
+python -m md2pdf.build_pdf path/to/input.md --output path/to/output.pdf
+```
+
+## 输出
+
+生成后会输出（以 `requirements` 为例）：
+
+- PDF：`docs/requirements.pdf`
+- 中间 HTML：`<build-dir>/requirements.html`
+- QA 摘要：`<build-dir>/qa/summary.txt`
+- 页面抽检图和缩略图：`<build-dir>/qa/*.png`
+
+`<build-dir>` 默认放在**输出 PDF 旁边**的 `.build/<stem>/`（用户可写，不会写进只读的安装目录）。需要指定别处时用 `--build-dir`，例如 `--build-dir ./.md2pdf-build`。
+
+## 依赖
+
+- `pandoc`
+- Python 包：`playwright`、`PyMuPDF`（`fitz`）、`Pillow`（随 `pip install` 自动安装）
+- Google Chrome 或 Playwright Chromium
+
+Pandoc 可能提示 `Could not load translations for zh-CN`，这不影响中文内容生成和 PDF 文本提取。
+
+## 测试
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```

md2pdf_tool-0.1.0/README.md

@@ -0,0 +1,101 @@
+# md2pdf
+
+Markdown 转 PDF 工具，专为中文文档优化：
+
+1. Pandoc 把 Markdown 转成带目录的 HTML。
+2. `md2pdf/style.css` 负责中文字体、封面、目录、标题、引用块、表格和分页样式。
+3. Playwright / headless Chrome 把 HTML 打印成 A4 PDF。
+4. PyMuPDF + Pillow 渲染 QA 图片和 `summary.txt`，用于检查页数、页面尺寸、乱码和抽检页面。
+
+## 安装
+
+需要先准备两个系统依赖（pip 无法安装）：
+
+- **pandoc**：`brew install pandoc`（macOS）/ `apt install pandoc`（Debian/Ubuntu）。
+- **浏览器**：装好 Python 包后运行 `playwright install chromium`，让 Playwright 下载自带的 Chromium；macOS 上若已装 Google Chrome 也可直接复用。
+
+然后安装本工具。发布名是 `md2pdf-tool`（PyPI 上 `md2pdf` 已被占用），命令仍是 `md2pdf`。
+
+**已发布后**，最终用户二选一：
+
+```bash
+# Homebrew（个人 tap）
+brew install <用户名>/md2pdf/md2pdf
+playwright install chromium
+
+# 或 pipx
+pipx install md2pdf-tool
+playwright install chromium
+```
+
+**从源码安装 / 开发**：
+
+```bash
+pipx install .          # 从仓库目录安装，得到全局 md2pdf 命令
+# 或可编辑安装：
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+playwright install chromium
+```
+
+发布到 PyPI 和搭建 Homebrew tap 的完整步骤见 [PUBLISHING.md](PUBLISHING.md)。
+
+## 使用
+
+安装后直接用 `md2pdf` 命令：
+
+```bash
+md2pdf docs/requirements.md
+```
+
+不传输出路径时，默认输出到同目录同名 `.pdf`；不传 `--title` 时，默认用文件名。
+
+也可以用 `gen_pdf.sh` 包装脚本——它会自动读取 Markdown 第一个一级标题作为封面标题：
+
+```bash
+./gen_pdf.sh docs/requirements.md docs/requirements.pdf
+./gen_pdf.sh --dry-run docs/requirements.md   # 只打印将要执行的命令
+```
+
+需要手动指定标题、副标题、日期或必检文本时，传对应参数：
+
+```bash
+md2pdf docs/requirements.md \
+  --output docs/requirements.pdf \
+  --title "4D交互式电子手册平台需求说明" \
+  --subtitle "面向大型企业私有化部署的创作、发布、播放与反馈闭环系统" \
+  --date "2026-06-03" \
+  --required-text "十八、最终一句话目标"
+```
+
+未安装时，也可以从仓库根目录用模块方式运行（需 `pip install -e .` 或设置 `PYTHONPATH=src`）：
+
+```bash
+python -m md2pdf.build_pdf path/to/input.md --output path/to/output.pdf
+```
+
+## 输出
+
+生成后会输出（以 `requirements` 为例）：
+
+- PDF：`docs/requirements.pdf`
+- 中间 HTML：`<build-dir>/requirements.html`
+- QA 摘要：`<build-dir>/qa/summary.txt`
+- 页面抽检图和缩略图：`<build-dir>/qa/*.png`
+
+`<build-dir>` 默认放在**输出 PDF 旁边**的 `.build/<stem>/`（用户可写，不会写进只读的安装目录）。需要指定别处时用 `--build-dir`，例如 `--build-dir ./.md2pdf-build`。
+
+## 依赖
+
+- `pandoc`
+- Python 包：`playwright`、`PyMuPDF`（`fitz`）、`Pillow`（随 `pip install` 自动安装）
+- Google Chrome 或 Playwright Chromium
+
+Pandoc 可能提示 `Could not load translations for zh-CN`，这不影响中文内容生成和 PDF 文本提取。
+
+## 测试
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```

md2pdf_tool-0.1.0/gen_pdf.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+#
+# Convenience wrapper around `python -m md2pdf.build_pdf`.
+# Reads the first level-1 Markdown heading as the PDF cover title.
+# When OUTPUT is omitted, writes <input>.pdf next to the source.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: ./gen_pdf.sh INPUT.md [OUTPUT.pdf]
+
+Convert a Markdown file to a styled, Chinese-friendly A4 PDF.
+The first "# heading" in INPUT.md becomes the cover title.
+
+Options:
+  --dry-run   Print the build command without running it.
+  -h, --help  Show this help and exit.
+EOF
+}
+
+dry_run=0
+args=()
+for arg in "$@"; do
+  case "$arg" in
+    -h|--help) usage; exit 0 ;;
+    --dry-run) dry_run=1 ;;
+    *) args+=("$arg") ;;
+  esac
+done
+
+if [ "${#args[@]}" -lt 1 ]; then
+  usage >&2
+  exit 1
+fi
+
+input="${args[0]}"
+output="${args[1]:-${input%.md}.pdf}"
+
+# First level-1 heading ("# Title"), stripped of the leading marker.
+title="$(grep -m1 '^# ' "$input" | sed 's/^# *//' || true)"
+
+if [ "$dry_run" -eq 1 ]; then
+  echo "python -m md2pdf.build_pdf \"$input\" --output \"$output\" --title \"$title\""
+  exit 0
+fi
+
+exec python -m md2pdf.build_pdf "$input" --output "$output" --title "$title"

md2pdf_tool-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+# Packaging for the md2pdf CLI.
+#
+# Distribution (PyPI) name is "md2pdf-tool" (the plain "md2pdf" name is
+# already taken on PyPI). The *import* package stays `md2pdf`, so `import md2pdf`
+# and the `md2pdf` console command are unaffected by the distribution name.
+#
+# After publishing, fill url + sha256 in packaging/homebrew/md2pdf.rb.
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "md2pdf-tool"
+version = "0.1.0"
+description = "Convert Markdown to a styled, Chinese-friendly A4 PDF with QA previews."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ethan", email = "zhangyuxin85@gmail.com" }]
+keywords = ["markdown", "pdf", "pandoc", "playwright", "chinese", "cjk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Printing",
+    "Environment :: Console",
+]
+dependencies = [
+    "playwright>=1.40",
+    "PyMuPDF>=1.24",
+    "Pillow>=10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ethanzhrepo/md2pdf"
+Repository = "https://github.com/ethanzhrepo/md2pdf"
+
+# Installs a global `md2pdf` command that calls build_pdf.main().
+[project.scripts]
+md2pdf = "md2pdf.build_pdf:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Ship the print stylesheet inside the package so the installed CLI can find it
+# at <site-packages>/md2pdf/style.css (build_pdf.py resolves it next to itself).
+[tool.setuptools.package-data]
+md2pdf = ["style.css"]

md2pdf_tool-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

md2pdf_tool-0.1.0/src/md2pdf/__init__.py

@@ -0,0 +1 @@
+"""Project-local Markdown to PDF tooling."""

md2pdf_tool-0.1.0/src/md2pdf/build_pdf.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+import argparse
+import html
+import math
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import date as local_date
+from pathlib import Path
+
+
+TOOL_DIR = Path(__file__).resolve().parent
+DEFAULT_CSS = TOOL_DIR / "style.css"
+
+
+@dataclass(frozen=True)
+class BuildConfig:
+    source: Path
+    output: Path
+    title: str
+    subtitle: str
+    date: str
+    css: Path
+    build_dir: Path
+    footer_title: str
+    toc: bool
+    toc_depth: int
+    qa: bool
+    required_text: tuple[str, ...]
+
+
+def default_output_path(source: Path) -> Path:
+    return source.with_suffix(".pdf")
+
+
+def build_metadata(title: str, subtitle: str = "", date: str = "", lang: str = "zh-CN") -> str:
+    lines = ["---", f"title: {title}"]
+    if subtitle:
+        lines.append(f"subtitle: {subtitle}")
+    if date:
+        lines.append(f"date: {date}")
+    lines.extend([f"lang: {lang}", "---", ""])
+    return "\n".join(lines)
+
+
+def selected_qa_pages(page_count: int) -> list[int]:
+    if page_count < 1:
+        raise ValueError("PDF has no pages")
+    candidates = {0, page_count // 2, page_count - 1}
+    if page_count > 1:
+        candidates.add(1)
+    if page_count > 2:
+        candidates.add(2)
+    return sorted(candidates)
+
+
+def parse_args(argv: list[str] | None = None) -> BuildConfig:
+    parser = argparse.ArgumentParser(
+        description="Convert Markdown to a styled Chinese-friendly PDF and render QA previews.",
+    )
+    parser.add_argument("source", type=Path, help="Markdown source file")
+    parser.add_argument("--output", type=Path, help="PDF output path. Defaults to SOURCE with .pdf suffix.")
+    parser.add_argument("--title", help="Cover/title metadata. Defaults to the source filename stem.")
+    parser.add_argument("--subtitle", default="", help="Optional subtitle shown on the cover.")
+    parser.add_argument("--date", default=local_date.today().isoformat(), help="Cover date. Defaults to today.")
+    parser.add_argument("--css", type=Path, default=DEFAULT_CSS, help="Print CSS file.")
+    parser.add_argument("--build-dir", type=Path, help="Intermediate HTML, metadata, and QA output directory.")
+    parser.add_argument("--footer-title", help="Footer document title. Defaults to --title.")
+    parser.add_argument("--toc-depth", type=int, default=2, help="Pandoc table-of-contents depth.")
+    parser.add_argument("--no-toc", action="store_true", help="Disable generated table of contents.")
+    parser.add_argument("--no-qa", action="store_true", help="Skip PyMuPDF/Pillow QA rendering.")
+    parser.add_argument(
+        "--required-text",
+        action="append",
+        default=[],
+        help="Text that must be extractable from the final PDF. Can be passed multiple times.",
+    )
+    args = parser.parse_args(argv)
+
+    source = args.source.resolve()
+    output = (args.output or default_output_path(source)).resolve()
+    title = args.title or source.stem
+    # Default build dir lives next to the OUTPUT, not inside the package install
+    # location (which may be read-only, e.g. a Homebrew cellar or system
+    # site-packages). The output dir is user-owned and writable.
+    build_dir = (
+        args.build_dir.resolve()
+        if args.build_dir
+        else (output.parent / ".build" / source.stem)
+    )
+
+    return BuildConfig(
+        source=source,
+        output=output,
+        title=title,
+        subtitle=args.subtitle,
+        date=args.date,
+        css=args.css.resolve(),
+        build_dir=build_dir,
+        footer_title=args.footer_title or title,
+        toc=not args.no_toc,
+        toc_depth=args.toc_depth,
+        qa=not args.no_qa,
+        required_text=tuple(args.required_text),
+    )
+
+
+def require_tool(name: str) -> None:
+    if shutil.which(name) is None:
+        raise RuntimeError(f"Required command not found: {name}")
+
+
+def run_pandoc(config: BuildConfig) -> Path:
+    require_tool("pandoc")
+    config.build_dir.mkdir(parents=True, exist_ok=True)
+    metadata = config.build_dir / "metadata.yaml"
+    html_path = config.build_dir / f"{config.source.stem}.html"
+    metadata.write_text(
+        build_metadata(config.title, config.subtitle, config.date),
+        encoding="utf-8",
+    )
+
+    command = [
+        "pandoc",
+        str(config.source),
+        "--from=markdown+smart",
+        "--to=html5",
+        "--standalone",
+        "--metadata-file",
+        str(metadata),
+        "--css",
+        str(config.css),
+        "--output",
+        str(html_path),
+    ]
+    if config.toc:
+        command.extend(["--toc", "--toc-depth", str(config.toc_depth)])
+
+    subprocess.run(command, check=True, cwd=config.source.parent)
+    return html_path
+
+
+def footer_template(title: str) -> str:
+    escaped_title = html.escape(title)
+    return f"""
+    <style>
+      .pdf-footer {{
+        width: 100%;
+        padding: 0 17mm;
+        color: #697386;
+        font-family: "Hiragino Sans GB", "STHeiti", "PingFang SC", Arial, sans-serif;
+        font-size: 8px;
+        display: flex;
+        justify-content: space-between;
+      }}
+    </style>
+    <div class="pdf-footer">
+      <span>{escaped_title}</span>
+      <span>第 <span class="pageNumber"></span> / <span class="totalPages"></span> 页</span>
+    </div>
+    """
+
+
+def launch_chromium(playwright):
+    launch_errors: list[str] = []
+    launchers = [
+        lambda: playwright.chromium.launch(channel="chrome", headless=True),
+        lambda: playwright.chromium.launch(
+            executable_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            headless=True,
+        ),
+        lambda: playwright.chromium.launch(headless=True),
+    ]
+    for launcher in launchers:
+        try:
+            return launcher()
+        except Exception as exc:  # noqa: BLE001 - preserve diagnostics for all fallbacks
+            launch_errors.append(str(exc))
+    raise RuntimeError("\n\n".join(launch_errors))
+
+
+def print_pdf(config: BuildConfig, html_path: Path) -> None:
+    from playwright.sync_api import sync_playwright
+
+    config.output.parent.mkdir(parents=True, exist_ok=True)
+    with sync_playwright() as p:
+        browser = launch_chromium(p)
+        page = browser.new_page(viewport={"width": 1240, "height": 1754})
+        page.goto(html_path.as_uri(), wait_until="networkidle")
+        page.emulate_media(media="print")
+        page.pdf(
+            path=str(config.output),
+            format="A4",
+            print_background=True,
+            display_header_footer=True,
+            header_template="<div></div>",
+            footer_template=footer_template(config.footer_title),
+            prefer_css_page_size=True,
+            margin={"top": "0", "right": "0", "bottom": "0", "left": "0"},
+        )
+        browser.close()
+
+
+def render_page(doc, page_index: int, scale: float, path: Path) -> None:
+    import fitz
+
+    page = doc.load_page(page_index)
+    pix = page.get_pixmap(matrix=fitz.Matrix(scale, scale), alpha=False)
+    pix.save(str(path))
+
+
+def make_contact_sheets(doc, qa_dir: Path) -> None:
+    import fitz
+    from PIL import Image, ImageDraw, ImageFont
+
+    per_sheet = 12
+    cols = 3
+    rows = 4
+    thumb_scale = 0.27
+    pad = 22
+    label_h = 24
+    font = ImageFont.load_default()
+
+    for sheet_index in range(math.ceil(doc.page_count / per_sheet)):
+        start = sheet_index * per_sheet
+        end = min(start + per_sheet, doc.page_count)
+        thumbs: list[Image.Image] = []
+        for page_index in range(start, end):
+            pix = doc.load_page(page_index).get_pixmap(
+                matrix=fitz.Matrix(thumb_scale, thumb_scale),
+                alpha=False,
+            )
+            img = Image.frombytes("RGB", (pix.width, pix.height), pix.samples)
+            canvas = Image.new("RGB", (img.width, img.height + label_h), "white")
+            canvas.paste(img, (0, 0))
+            draw = ImageDraw.Draw(canvas)
+            draw.rectangle((0, 0, img.width - 1, img.height - 1), outline="#c7ced8", width=1)
+            draw.text((8, img.height + 5), f"Page {page_index + 1}", fill="#334155", font=font)
+            thumbs.append(canvas)
+
+        cell_w = max(t.width for t in thumbs)
+        cell_h = max(t.height for t in thumbs)
+        sheet = Image.new(
+            "RGB",
+            (cols * cell_w + (cols + 1) * pad, rows * cell_h + (rows + 1) * pad),
+            "#f2f5f9",
+        )
+        for i, thumb in enumerate(thumbs):
+            x = pad + (i % cols) * (cell_w + pad)
+            y = pad + (i // cols) * (cell_h + pad)
+            sheet.paste(thumb, (x, y))
+
+        sheet.save(qa_dir / f"contact_sheet_{sheet_index + 1:02d}.png")
+
+
+def qa_render(config: BuildConfig, html_path: Path) -> Path:
+    import fitz
+
+    qa_dir = config.build_dir / "qa"
+    if qa_dir.exists():
+        shutil.rmtree(qa_dir)
+    qa_dir.mkdir(parents=True, exist_ok=True)
+
+    doc = fitz.open(config.output)
+    for page_index in selected_qa_pages(doc.page_count):
+        render_page(doc, page_index, 1.45, qa_dir / f"page_{page_index + 1:03d}.png")
+    make_contact_sheets(doc, qa_dir)
+
+    extracted = "\n".join(page.get_text() for page in doc)
+    required_results = {
+        item: item in extracted
+        for item in (config.title, *config.required_text)
+        if item
+    }
+    summary = {
+        "pdf": str(config.output),
+        "html": str(html_path),
+        "pages": doc.page_count,
+        "page_size_points": [round(doc[0].rect.width, 2), round(doc[0].rect.height, 2)],
+        "replacement_character_count": extracted.count("\ufffd"),
+        "required_text": required_results,
+        "very_low_text_pages": [
+            (i + 1, len(page.get_text().strip()))
+            for i, page in enumerate(doc)
+            if len(page.get_text().strip()) < 40
+        ],
+    }
+    summary_path = qa_dir / "summary.txt"
+    summary_path.write_text(
+        "\n".join(f"{key}: {value}" for key, value in summary.items()) + "\n",
+        encoding="utf-8",
+    )
+    doc.close()
+    return summary_path
+
+
+def build(config: BuildConfig) -> tuple[Path, Path | None]:
+    if not config.source.exists():
+        raise FileNotFoundError(config.source)
+    if not config.css.exists():
+        raise FileNotFoundError(config.css)
+
+    html_path = run_pandoc(config)
+    print_pdf(config, html_path)
+    summary_path = qa_render(config, html_path) if config.qa else None
+    return config.output, summary_path
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        config = parse_args(argv)
+        pdf_path, summary_path = build(config)
+    except Exception as exc:  # noqa: BLE001 - CLI should report concise failure
+        print(f"md2pdf failed: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"PDF: {pdf_path}")
+    if summary_path:
+        print(f"QA: {summary_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

md2pdf_tool-0.1.0/src/md2pdf/style.css

@@ -0,0 +1,386 @@
+@charset "UTF-8";
+
+:root {
+  --ink: #172033;
+  --muted: #5c667a;
+  --line: #d9e0ea;
+  --accent: #185b9d;
+  --accent-deep: #123f6d;
+  --accent-soft: #e8f1fb;
+  --panel: #f6f9fc;
+  --panel-line: #d7e2ee;
+}
+
+@page {
+  size: A4;
+  margin: 18mm 17mm 20mm 17mm;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  color: var(--ink);
+  font-family: "Hiragino Sans GB", "STHeiti", "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", "Source Han Sans SC", Arial, sans-serif;
+  font-size: 10.7pt;
+  line-height: 1.72;
+  text-rendering: optimizeLegibility;
+}
+
+body {
+  margin: 0;
+  padding: 0;
+  background: #fff;
+}
+
+a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+p {
+  margin: 0 0 0.72em 0;
+}
+
+strong {
+  font-weight: 700;
+}
+
+#title-block-header {
+  min-height: 190mm;
+  position: relative;
+  display: block;
+  padding: 24mm 18mm 18mm 23mm;
+  break-after: page;
+  overflow: hidden;
+  border: 0.9pt solid var(--panel-line);
+  border-left: 8mm solid var(--accent);
+  border-radius: 6px;
+  background:
+    linear-gradient(180deg, #f8fbfe 0%, #ffffff 40%, #ffffff 100%);
+}
+
+#title-block-header::before {
+  content: "需求说明书";
+  position: relative;
+  z-index: 1;
+  display: inline-block;
+  width: max-content;
+  margin: 0 0 22mm 0;
+  padding: 2.3mm 4.4mm;
+  border-radius: 999px;
+  background: var(--accent-soft);
+  color: var(--accent-deep);
+  font-size: 9.5pt;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+}
+
+#title-block-header::after {
+  content: "PRIVATE DEPLOYMENT · 4D IETM · OPERATION WORKFLOW";
+  position: absolute;
+  right: 18mm;
+  bottom: 18mm;
+  left: 23mm;
+  z-index: 0;
+  padding-top: 5mm;
+  border-top: 0.8pt solid var(--line);
+  color: #7a8798;
+  font-size: 8.4pt;
+  font-weight: 700;
+  letter-spacing: 0.09em;
+}
+
+h1.title {
+  margin: 0;
+  max-width: 165mm;
+  color: #10213d;
+  font-size: 28pt;
+  line-height: 1.18;
+  font-weight: 800;
+  letter-spacing: 0;
+}
+
+p.subtitle {
+  max-width: 160mm;
+  margin: 8mm 0 0 0;
+  color: var(--muted);
+  font-size: 13pt;
+  line-height: 1.56;
+}
+
+p.date {
+  margin: 16mm 0 0 0;
+  color: var(--muted);
+  font-size: 10.5pt;
+}
+
+#TOC {
+  break-after: page;
+  padding-top: 1mm;
+}
+
+#TOC::before {
+  content: "目录";
+  display: block;
+  margin: 0 0 8mm 0;
+  color: #10213d;
+  font-size: 21pt;
+  line-height: 1.2;
+  font-weight: 800;
+  border-bottom: 1.4pt solid var(--line);
+  padding-bottom: 4mm;
+}
+
+#TOC ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+#TOC > ul > li {
+  margin: 0 0 3.2mm 0;
+  padding: 0 0 3.2mm 0;
+  border-bottom: 0.5pt solid #edf1f5;
+}
+
+#TOC > ul > li > a {
+  color: var(--ink);
+  font-weight: 700;
+}
+
+#TOC ul ul {
+  margin-top: 1.4mm;
+  column-count: 2;
+  column-gap: 8mm;
+}
+
+#TOC ul ul li {
+  margin: 0 0 1.2mm 0;
+  break-inside: avoid;
+}
+
+#TOC ul ul a {
+  color: var(--muted);
+  font-size: 9.4pt;
+}
+
+h1,
+h2,
+h3 {
+  color: #10213d;
+  letter-spacing: 0;
+}
+
+h1 {
+  margin: 0 0 7mm 0;
+  padding-bottom: 3.2mm;
+  border-bottom: 1.4pt solid var(--line);
+  font-size: 20pt;
+  line-height: 1.28;
+  font-weight: 800;
+  break-before: page;
+  break-after: avoid;
+}
+
+#TOC + h1 {
+  break-before: auto;
+}
+
+h2 {
+  margin: 8.2mm 0 3.4mm 0;
+  font-size: 14.2pt;
+  line-height: 1.36;
+  font-weight: 780;
+  break-after: avoid;
+}
+
+h3 {
+  margin: 6mm 0 2.2mm 0;
+  color: var(--accent);
+  font-size: 11.8pt;
+  line-height: 1.36;
+  font-weight: 760;
+  break-after: avoid;
+}
+
+h4 {
+  margin: 4.5mm 0 1.8mm 0;
+  color: var(--muted);
+  font-size: 10.8pt;
+  font-weight: 740;
+  break-after: avoid;
+}
+
+#title-block-header h1.title {
+  margin: 0;
+  position: relative;
+  z-index: 1;
+  max-width: 142mm;
+  padding: 0;
+  border: none;
+  color: #10213d;
+  font-size: 30pt;
+  line-height: 1.16;
+  font-weight: 800;
+  break-before: auto;
+  break-after: auto;
+}
+
+#title-block-header p.subtitle {
+  position: relative;
+  z-index: 1;
+  max-width: 132mm;
+  margin: 9mm 0 0 0;
+  padding: 4mm 5mm;
+  border: 0.7pt solid var(--panel-line);
+  border-left: 3pt solid var(--accent);
+  border-radius: 4px;
+  background: var(--panel);
+  color: #415066;
+  font-size: 12.4pt;
+  line-height: 1.58;
+}
+
+#title-block-header p.date {
+  position: relative;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  gap: 3mm;
+  margin: 13mm 0 0 0;
+  padding: 2.4mm 4mm;
+  border: 0.7pt solid var(--line);
+  border-radius: 4px;
+  background: #ffffff;
+  color: #536176;
+  font-size: 9.8pt;
+  font-weight: 650;
+}
+
+#title-block-header p.date::before {
+  content: "DATE";
+  color: var(--accent);
+  font-size: 7.8pt;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+}
+
+ul,
+ol {
+  margin: 0 0 3.2mm 0;
+  padding-left: 7mm;
+}
+
+li {
+  margin: 0.7mm 0;
+  padding-left: 0.8mm;
+}
+
+li::marker {
+  color: var(--accent);
+}
+
+blockquote {
+  margin: 4.5mm 0 5mm 0;
+  padding: 3.4mm 4.2mm 3.2mm 4.8mm;
+  border-left: 4pt solid var(--accent);
+  background: var(--accent-soft);
+  color: #16304f;
+  break-inside: avoid;
+}
+
+blockquote p {
+  margin: 0;
+}
+
+pre,
+code {
+  font-family: Menlo, Monaco, "Courier New", monospace;
+}
+
+code {
+  padding: 0.1em 0.28em;
+  border-radius: 3px;
+  background: #f3f5f8;
+  color: #1f2a44;
+  font-size: 0.93em;
+}
+
+pre {
+  margin: 4mm 0 5mm 0;
+  padding: 4mm 5mm;
+  border: 0.7pt solid var(--line);
+  border-radius: 4px;
+  background: #f7f9fb;
+  color: #213047;
+  line-height: 1.55;
+  white-space: pre-wrap;
+  break-inside: avoid;
+}
+
+pre code {
+  padding: 0;
+  background: transparent;
+  font-size: 9.4pt;
+}
+
+table {
+  width: 100%;
+  margin: 5mm 0 6mm 0;
+  border-collapse: collapse;
+  border: 0.8pt solid var(--line);
+  font-size: 9.8pt;
+  break-inside: avoid;
+}
+
+thead {
+  display: table-header-group;
+}
+
+tr {
+  break-inside: avoid;
+}
+
+th,
+td {
+  padding: 2.7mm 3.2mm;
+  border: 0.55pt solid var(--line);
+  vertical-align: middle;
+  line-height: 1.56;
+}
+
+th {
+  background: #edf3f8;
+  color: #10213d;
+  font-weight: 760;
+}
+
+tbody tr:nth-child(even) td {
+  background: #fafbfd;
+}
+
+hr {
+  display: none;
+}
+
+figure {
+  margin: 0;
+}
+
+.footnotes,
+section.footnotes {
+  margin-top: 8mm;
+  padding-top: 4mm;
+  border-top: 1pt solid var(--line);
+  color: var(--muted);
+  font-size: 9pt;
+}
+
+@media print {
+  body {
+    orphans: 3;
+    widows: 3;
+  }
+}

md2pdf_tool-0.1.0/src/md2pdf_tool.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: md2pdf-tool
+Version: 0.1.0
+Summary: Convert Markdown to a styled, Chinese-friendly A4 PDF with QA previews.
+Author-email: Ethan <zhangyuxin85@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ethanzhrepo/md2pdf
+Project-URL: Repository, https://github.com/ethanzhrepo/md2pdf
+Keywords: markdown,pdf,pandoc,playwright,chinese,cjk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Printing
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40
+Requires-Dist: PyMuPDF>=1.24
+Requires-Dist: Pillow>=10.0
+Dynamic: license-file
+
+# md2pdf
+
+Markdown 转 PDF 工具，专为中文文档优化：
+
+1. Pandoc 把 Markdown 转成带目录的 HTML。
+2. `md2pdf/style.css` 负责中文字体、封面、目录、标题、引用块、表格和分页样式。
+3. Playwright / headless Chrome 把 HTML 打印成 A4 PDF。
+4. PyMuPDF + Pillow 渲染 QA 图片和 `summary.txt`，用于检查页数、页面尺寸、乱码和抽检页面。
+
+## 安装
+
+需要先准备两个系统依赖（pip 无法安装）：
+
+- **pandoc**：`brew install pandoc`（macOS）/ `apt install pandoc`（Debian/Ubuntu）。
+- **浏览器**：装好 Python 包后运行 `playwright install chromium`，让 Playwright 下载自带的 Chromium；macOS 上若已装 Google Chrome 也可直接复用。
+
+然后安装本工具。发布名是 `md2pdf-tool`（PyPI 上 `md2pdf` 已被占用），命令仍是 `md2pdf`。
+
+**已发布后**，最终用户二选一：
+
+```bash
+# Homebrew（个人 tap）
+brew install <用户名>/md2pdf/md2pdf
+playwright install chromium
+
+# 或 pipx
+pipx install md2pdf-tool
+playwright install chromium
+```
+
+**从源码安装 / 开发**：
+
+```bash
+pipx install .          # 从仓库目录安装，得到全局 md2pdf 命令
+# 或可编辑安装：
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+playwright install chromium
+```
+
+发布到 PyPI 和搭建 Homebrew tap 的完整步骤见 [PUBLISHING.md](PUBLISHING.md)。
+
+## 使用
+
+安装后直接用 `md2pdf` 命令：
+
+```bash
+md2pdf docs/requirements.md
+```
+
+不传输出路径时，默认输出到同目录同名 `.pdf`；不传 `--title` 时，默认用文件名。
+
+也可以用 `gen_pdf.sh` 包装脚本——它会自动读取 Markdown 第一个一级标题作为封面标题：
+
+```bash
+./gen_pdf.sh docs/requirements.md docs/requirements.pdf
+./gen_pdf.sh --dry-run docs/requirements.md   # 只打印将要执行的命令
+```
+
+需要手动指定标题、副标题、日期或必检文本时，传对应参数：
+
+```bash
+md2pdf docs/requirements.md \
+  --output docs/requirements.pdf \
+  --title "4D交互式电子手册平台需求说明" \
+  --subtitle "面向大型企业私有化部署的创作、发布、播放与反馈闭环系统" \
+  --date "2026-06-03" \
+  --required-text "十八、最终一句话目标"
+```
+
+未安装时，也可以从仓库根目录用模块方式运行（需 `pip install -e .` 或设置 `PYTHONPATH=src`）：
+
+```bash
+python -m md2pdf.build_pdf path/to/input.md --output path/to/output.pdf
+```
+
+## 输出
+
+生成后会输出（以 `requirements` 为例）：
+
+- PDF：`docs/requirements.pdf`
+- 中间 HTML：`<build-dir>/requirements.html`
+- QA 摘要：`<build-dir>/qa/summary.txt`
+- 页面抽检图和缩略图：`<build-dir>/qa/*.png`
+
+`<build-dir>` 默认放在**输出 PDF 旁边**的 `.build/<stem>/`（用户可写，不会写进只读的安装目录）。需要指定别处时用 `--build-dir`，例如 `--build-dir ./.md2pdf-build`。
+
+## 依赖
+
+- `pandoc`
+- Python 包：`playwright`、`PyMuPDF`（`fitz`）、`Pillow`（随 `pip install` 自动安装）
+- Google Chrome 或 Playwright Chromium
+
+Pandoc 可能提示 `Could not load translations for zh-CN`，这不影响中文内容生成和 PDF 文本提取。
+
+## 测试
+
+```bash
+pip install -e .
+python -m unittest discover -s tests -v
+```

md2pdf_tool-0.1.0/src/md2pdf_tool.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+gen_pdf.sh
+pyproject.toml
+src/md2pdf/__init__.py
+src/md2pdf/build_pdf.py
+src/md2pdf/style.css
+src/md2pdf_tool.egg-info/PKG-INFO
+src/md2pdf_tool.egg-info/SOURCES.txt
+src/md2pdf_tool.egg-info/dependency_links.txt
+src/md2pdf_tool.egg-info/entry_points.txt
+src/md2pdf_tool.egg-info/requires.txt
+src/md2pdf_tool.egg-info/top_level.txt
+tests/test_build_pdf.py
+tests/test_gen_pdf_shell.py

md2pdf_tool-0.1.0/src/md2pdf_tool.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

md2pdf_tool-0.1.0/src/md2pdf_tool.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+md2pdf = md2pdf.build_pdf:main

md2pdf_tool-0.1.0/src/md2pdf_tool.egg-info/requires.txt

@@ -0,0 +1,3 @@
+playwright>=1.40
+PyMuPDF>=1.24
+Pillow>=10.0

md2pdf_tool-0.1.0/src/md2pdf_tool.egg-info/top_level.txt

@@ -0,0 +1 @@
+md2pdf

md2pdf_tool-0.1.0/tests/test_build_pdf.py

@@ -0,0 +1,33 @@
+import unittest
+from pathlib import Path
+
+from md2pdf.build_pdf import build_metadata, default_output_path, selected_qa_pages
+
+
+class Md2PdfUtilityTests(unittest.TestCase):
+    def test_default_output_path_reuses_source_stem(self):
+        self.assertEqual(
+            default_output_path(Path("docs/requirements.md")),
+            Path("docs/requirements.pdf"),
+        )
+
+    def test_build_metadata_preserves_chinese_fields(self):
+        metadata = build_metadata(
+            title="中文标题",
+            subtitle="中文副标题",
+            date="2026-06-03",
+        )
+
+        self.assertIn("title: 中文标题", metadata)
+        self.assertIn("subtitle: 中文副标题", metadata)
+        self.assertIn("date: 2026-06-03", metadata)
+        self.assertIn("lang: zh-CN", metadata)
+
+    def test_selected_qa_pages_deduplicates_small_documents(self):
+        self.assertEqual(selected_qa_pages(1), [0])
+        self.assertEqual(selected_qa_pages(2), [0, 1])
+        self.assertEqual(selected_qa_pages(70), [0, 1, 2, 35, 69])
+
+
+if __name__ == "__main__":
+    unittest.main()

md2pdf_tool-0.1.0/tests/test_gen_pdf_shell.py

@@ -0,0 +1,43 @@
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = ROOT / "gen_pdf.sh"
+
+
+class GenPdfShellTests(unittest.TestCase):
+    def test_help_describes_input_and_optional_output(self):
+        result = subprocess.run(
+            ["bash", str(SCRIPT), "--help"],
+            cwd=ROOT,
+            text=True,
+            capture_output=True,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("Usage: ./gen_pdf.sh INPUT.md [OUTPUT.pdf]", result.stdout)
+
+    def test_dry_run_uses_first_heading_and_default_pdf_path(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            source = Path(tmp) / "sample.md"
+            source.write_text("# 中文标题\n\n正文。\n", encoding="utf-8")
+
+            result = subprocess.run(
+                ["bash", str(SCRIPT), "--dry-run", str(source)],
+                cwd=ROOT,
+                text=True,
+                capture_output=True,
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("python -m md2pdf.build_pdf", result.stdout)
+        self.assertIn(str(source.with_suffix(".pdf")), result.stdout)
+        self.assertIn("--title", result.stdout)
+        self.assertIn("中文标题", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()