Skip to content

zach22-1999/generic-skills / skills/zach-md-html

zach-md-html

Verified

已降级的 Markdown→HTML 兼容转换器。仅当用户明确要求“使用 zach-md-html”、或明确说“不要重组内容,只把现成 Markdown 机械转换成 HTML/套用旧主题”时使用。不要因为用户只说“输出成 HTML”“生成 HTML 报告”“把日常报告做成 HTML”“数据报告/交付报告”而触发;这些任务应由模型从原始资料直接组织并生成自包含 HTML。此 Skill 不负责数据可视化、工作面、自由设计、万物转 md、html 转 md 或 md 转 docx。

scripts/md_to_html.py

View on GitHub
#!/usr/bin/env python3
"""
md_to_html.py — Convert Markdown to a polished, self-contained HTML using Pandoc + zach-md-html themes.

Three-tier mode (zach-md-html public workflow):

  Tier A · default (no extra token):
    Five reading-oriented themes — article / report / reading / interactive / wechat.
    Pandoc + theme CSS, 5-second turn-around. Use for linear prose.

  Tier B · workspace (light token):
    Thariq-style work surface scene templates — comparison / plan-board /
    annotated-pr / incident-timeline / feature-explainer / status-weekly / auto.
    Pandoc + workspace template + whitelisted vanilla JS. Self-contained.

  Tier C · free-design (heavy token):
    AI generates HTML directly without pandoc. Must pass 6-point anti-slop
    self-check (see references/anti-ai-slop.md).

NOTE: As of Tier B/C scaffold rollout, --scene and --free-design parse and
print intent, then **gracefully fall back to default** with an explicit notice.
The AI agent should generate workspace/free HTML directly per the references
(workspace-scene-catalog.md, visual-designer-mode.md) rather than relying on
this script's scaffolding. Tier A is rock-solid and always available.

Part of zach-md-html skill — md is source, html is product.
"""
from __future__ import annotations

import argparse
import base64
import mimetypes
import re
import shutil
import subprocess
import sys
from pathlib import Path


SKILL_ROOT = Path(__file__).resolve().parent.parent
TEMPLATE_DIR = SKILL_ROOT / "templates"
VALID_THEMES = ("article", "report", "reading", "interactive", "wechat")
VALID_SCENES = (
    "comparison",
    "plan-board",
    "annotated-pr",
    "incident-timeline",
    "feature-explainer",
    "status-weekly",
    "auto",
)
VALID_MODES = ("default", "workspace", "free")


HELP_PANDOC = """\
pandoc is not installed. Install it with:

    brew install pandoc       # macOS
    apt install pandoc        # Debian/Ubuntu
    choco install pandoc      # Windows

Or download from https://pandoc.org/installing.html
"""


def ensure_pandoc() -> str:
    pandoc = shutil.which("pandoc")
    if not pandoc:
        sys.stderr.write(HELP_PANDOC)
        sys.exit(2)
    return pandoc


def parse_args() -> argparse.Namespace:
    p = argparse.ArgumentParser(
        description=(
            "Convert Markdown to polished HTML using Pandoc + zach-md-html. "
            "Three tiers: default (5 reading themes, no extra token) / "
            "workspace (Thariq-style scene templates) / free-design (AI direct)."
        ),
    )
    p.add_argument("input", help="Input .md file path.")
    p.add_argument(
        "-o", "--output",
        help="Output .html path. Defaults to <input-stem>.html.",
    )
    p.add_argument(
        "--theme",
        choices=VALID_THEMES,
        default="article",
        help="Reading-oriented theme to use in default tier (default: article).",
    )
    p.add_argument(
        "--scene",
        choices=VALID_SCENES,
        default=None,
        help=(
            "Workspace scene template (Thariq-style work surface). "
            "Implies --mode workspace. Currently scaffolded — falls back to "
            "default tier with notice; AI should generate workspace HTML "
            "directly per references/workspace-scene-catalog.md."
        ),
    )
    p.add_argument(
        "--free-design",
        action="store_true",
        help=(
            "Free-design tier: AI generates full HTML without pandoc. "
            "Implies --mode free. Currently scaffolded — falls back to default."
        ),
    )
    p.add_argument(
        "--mode",
        choices=VALID_MODES,
        default=None,
        help=(
            "Explicit three-tier mode. Default: inferred from --scene / "
            "--free-design or 'default'. Workspace/free fall back to default "
            "with a notice until script-side support lands."
        ),
    )
    p.add_argument(
        "--inline-images",
        action="store_true",
        help="Embed referenced local images as base64 (single self-contained file).",
    )
    p.add_argument(
        "--copy-images",
        action="store_true",
        help="Copy referenced local images next to the output html (relative paths).",
    )
    p.add_argument(
        "--toc",
        action="store_true",
        help="Render a table of contents (auto-on for theme=interactive).",
    )
    p.add_argument(
        "--no-toc",
        action="store_true",
        help="Disable TOC even if the theme would default to it.",
    )
    p.add_argument(
        "--standalone",
        action="store_true",
        default=True,
        help="Produce a self-contained single HTML file (default).",
    )
    p.add_argument(
        "--katex",
        action="store_true",
        help="Render math via KaTeX (loaded from CDN; requires network for first view).",
    )
    p.add_argument(
        "--highlight-style",
        default="pygments",
        help="Pandoc highlight style (default: pygments).",
    )
    p.add_argument(
        "--title",
        help="Override the document title (otherwise inferred from first H1 or filename).",
    )
    p.add_argument(
        "--quiet",
        action="store_true",
        help="Suppress non-error stderr output.",
    )
    return p.parse_args()


def load_theme(theme: str) -> tuple[Path, Path | None]:
    theme_dir = TEMPLATE_DIR / theme
    css_path = theme_dir / "theme.css"
    if not css_path.exists():
        sys.stderr.write(f"[error] theme '{theme}' is missing CSS at: {css_path}\n")
        sys.exit(2)
    template_path = theme_dir / "template.html5"
    if template_path.exists():
        return css_path, template_path
    shared_template = TEMPLATE_DIR / "_shared" / "template.html5"
    return css_path, shared_template if shared_template.exists() else None


def infer_title_and_strip(md_path: Path, override: str | None) -> tuple[str, str]:
    """Return (title, md_text_with_leading_h1_stripped).

    Pandoc's --standalone renders a title block from metadata, so we strip
    the leading H1 from the body to avoid duplicate titles.
    """
    raw = md_path.read_text(encoding="utf-8")
    lines = raw.splitlines()

    # Find first non-blank line
    first_non_blank = next(
        (i for i, line in enumerate(lines) if line.strip()),
        None,
    )

    title = override
    body_lines = lines

    if first_non_blank is not None:
        first_line = lines[first_non_blank].strip()
        if first_line.startswith("# ") and not first_line.startswith("## "):
            extracted = first_line[2:].strip()
            if not title:
                title = extracted
            # Strip the H1 line and any blank lines that immediately follow it
            cut = first_non_blank + 1
            while cut < len(lines) and not lines[cut].strip():
                cut += 1
            body_lines = lines[:first_non_blank] + lines[cut:]

    if not title:
        title = md_path.stem

    return title, "\n".join(body_lines)


def should_emit_toc(args: argparse.Namespace) -> bool:
    if args.no_toc:
        return False
    if args.toc:
        return True
    return args.theme == "interactive"


def collect_local_images(md_text: str, base_dir: Path) -> list[Path]:
    """Find referenced local images in markdown that exist on disk."""
    pattern = re.compile(r'!\[[^\]]*\]\(([^)\s"]+)')
    found: list[Path] = []
    for m in pattern.finditer(md_text):
        ref = m.group(1)
        if ref.startswith(("http://", "https://", "data:")):
            continue
        candidate = (base_dir / ref).resolve()
        if candidate.exists() and candidate.is_file():
            found.append(candidate)
    return found


def inline_images_in_html(html: str, base_dir: Path) -> str:
    """Replace local img src references with base64 data URIs."""
    pattern = re.compile(r'(<img[^>]+src=)"([^"]+)"')

    def replace(match: re.Match[str]) -> str:
        prefix, src = match.group(1), match.group(2)
        if src.startswith(("http://", "https://", "data:")):
            return match.group(0)
        candidate = (base_dir / src).resolve()
        if not candidate.exists():
            return match.group(0)
        mime, _ = mimetypes.guess_type(candidate)
        if not mime:
            mime = "application/octet-stream"
        b64 = base64.b64encode(candidate.read_bytes()).decode("ascii")
        return f'{prefix}"data:{mime};base64,{b64}"'

    return pattern.sub(replace, html)


def copy_images_alongside(images: list[Path], src_base: Path, out_dir: Path, quiet: bool) -> None:
    out_dir.mkdir(parents=True, exist_ok=True)
    for img in images:
        try:
            relative = img.relative_to(src_base)
        except ValueError:
            relative = Path(img.name)
        dest = out_dir / relative
        dest.parent.mkdir(parents=True, exist_ok=True)
        if img.resolve() != dest.resolve():
            shutil.copy2(img, dest)
            if not quiet:
                sys.stderr.write(f"[copied] {img} → {dest}\n")


def build_pandoc_command(
    pandoc_bin: str,
    md_input: Path | str,
    output_html: Path,
    css_path: Path,
    template_path: Path | None,
    title: str,
    args: argparse.Namespace,
) -> list[str]:
    cmd = [
        pandoc_bin,
        str(md_input),
        "--from", "markdown+smart+pipe_tables+task_lists+fenced_divs+bracketed_spans",
        "--to", "html5",
        "--metadata", f"title={title}",
        "--metadata", f"theme={args.theme}",
        "--highlight-style", args.highlight_style,
        "-o", str(output_html),
    ]
    if args.standalone:
        cmd.append("--standalone")
        cmd.append("--embed-resources")
    cmd.extend(["--css", str(css_path)])
    if template_path:
        cmd.extend(["--template", str(template_path)])
    if should_emit_toc(args):
        cmd.extend(["--toc", "--toc-depth=3"])
    if args.katex:
        cmd.append("--katex")
    return cmd


def resolve_mode(args: argparse.Namespace) -> str:
    """Infer effective tier from --mode / --scene / --free-design.

    Precedence: explicit --mode > --free-design > --scene > default.
    """
    if args.mode:
        return args.mode
    if args.free_design:
        return "free"
    if args.scene:
        return "workspace"
    return "default"


def main() -> int:
    args = parse_args()

    mode = resolve_mode(args)
    if mode != "default":
        sys.stderr.write(
            f"[notice] tier='{mode}' is scaffolded but not yet implemented in this script. "
            f"Falling back to tier='default' (theme={args.theme}). "
            f"For workspace / free-design HTML, the AI agent should generate the file "
            f"directly per references/workspace-scene-catalog.md, "
            f"references/visual-designer-mode.md, and references/anti-ai-slop.md.\n"
        )

    pandoc_bin = ensure_pandoc()

    input_md = Path(args.input).resolve()
    if not input_md.exists():
        sys.stderr.write(f"[error] input file not found: {input_md}\n")
        return 1

    output_html = Path(args.output).resolve() if args.output else input_md.with_suffix(".html")
    output_html.parent.mkdir(parents=True, exist_ok=True)

    css_path, template_path = load_theme(args.theme)
    title, md_text = infer_title_and_strip(input_md, args.title)
    src_base = input_md.parent

    if args.copy_images:
        images = collect_local_images(md_text, src_base)
        if images:
            copy_images_alongside(images, src_base, output_html.parent, args.quiet)

    # Pipe the stripped markdown to pandoc via stdin to avoid temp files
    cmd = build_pandoc_command(
        pandoc_bin, "-", output_html, css_path, template_path, title, args,
    )

    try:
        proc = subprocess.run(cmd, input=md_text, capture_output=True, text=True)
    except FileNotFoundError:
        sys.stderr.write(HELP_PANDOC)
        return 2

    if proc.returncode != 0:
        sys.stderr.write(proc.stderr or "[error] pandoc failed without stderr output.\n")
        return proc.returncode

    if args.inline_images:
        html_text = output_html.read_text(encoding="utf-8")
        html_text = inline_images_in_html(html_text, src_base)
        output_html.write_text(html_text, encoding="utf-8")

    if not args.quiet:
        sys.stderr.write(f"[ok] {input_md.name} → {output_html} (theme: {args.theme})\n")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall