xuanxin 0.1.1.dev0__py3-none-any.whl

xuanxin/__init__.py

@@ -0,0 +1,18 @@
+"""xuanxin — Markdown blog to beautiful static HTML."""
+
+from xuanxin.book import collect_book_markdown, default_book_output_dir, render_book
+from xuanxin.builder import BlogBuilder, render_file
+from xuanxin.processor import MarkdownProcessor, process_file, process_string
+
+__version__ = "0.1.1.dev0"
+__all__ = [
+    "BlogBuilder",
+    "MarkdownProcessor",
+    "collect_book_markdown",
+    "default_book_output_dir",
+    "process_file",
+    "process_string",
+    "render_book",
+    "render_file",
+    "__version__",
+]

xuanxin/book.py

@@ -0,0 +1,226 @@
+"""Discover and render autobiography / bubble-style book chapters to HTML."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from xuanxin.includes import find_peanut_config
+from xuanxin.paginate import count_pages
+from xuanxin.processor import MarkdownProcessor
+from xuanxin.renderer import BlogRenderer
+
+# Bubble merge order: preface → chapters 1–12 → appendix (chapterx)
+LANG_SUFFIX = {
+    "en": "",
+    "zh": "_zh",
+    "cn": "_zh",
+    "tc": "_tc",
+    "jp": "_jp",
+    "sp": "_sp",
+}
+
+
+def normalize_book_lang(lang: str) -> str:
+    """Normalize CLI language codes to canonical suffix keys."""
+    key = lang.lower().strip().replace("-", "_")
+    if key in ("cn", "zh_cn"):
+        return "zh"
+    return key
+
+
+def default_book_output_dir(root: Path | str, lang: str) -> Path:
+    """Return the default HTML output directory for a book language."""
+    root = Path(root).resolve()
+    lang = normalize_book_lang(lang)
+    if lang == "en":
+        return root / "book_html"
+    return root / f"book_html_{lang}"
+
+
+@dataclass
+class BookChapter:
+    """One rendered unit in reading order."""
+
+    md_path: Path
+    html_name: str
+    title: str
+    order: int
+
+
+def is_book_repo_root(path: Path) -> bool:
+    root = path.resolve()
+    if next(root.glob("chapter1-*"), None) is not None:
+        return True
+    chapterx = root / "chapterx"
+    return chapterx.is_dir() and any(chapterx.glob("*.md"))
+
+
+def discover_book_repo_root(start: Path | None = None) -> Path:
+    seen: set[Path] = set()
+    cur = (start or Path.cwd()).resolve()
+    while cur not in seen:
+        seen.add(cur)
+        if is_book_repo_root(cur):
+            return cur
+        if cur.parent == cur:
+            break
+        cur = cur.parent
+    raise FileNotFoundError(
+        "Cannot find book repository root (expected chapter1-*/ or chapterx/). "
+        "Run from the book repo or pass --root."
+    )
+
+
+def collect_book_markdown(root: Path, lang: str = "en") -> list[Path]:
+    """Return markdown files in reading order (preface, ch.1–12, appendix)."""
+    root = root.resolve()
+    lang = normalize_book_lang(lang)
+    suffix = LANG_SUFFIX.get(lang, lang if lang.startswith("_") else "")
+    if lang not in LANG_SUFFIX and not suffix.startswith("_"):
+        suffix = f"_{lang}" if lang != "en" else ""
+
+    files: list[Path] = []
+
+    preface = root / "chapterx" / (f"preface{suffix}.md" if suffix else "preface.md")
+    if preface.is_file():
+        files.append(preface)
+
+    for n in range(1, 13):
+        for d in sorted(root.glob(f"chapter{n}-*")):
+            if not d.is_dir():
+                continue
+            name = f"chapter{n}{suffix}.md" if suffix else f"chapter{n}.md"
+            md = d / name
+            if md.is_file():
+                files.append(md)
+                break
+
+    appendix = root / "chapterx" / (f"chapterx{suffix}.md" if suffix else "chapterx.md")
+    if appendix.is_file():
+        files.append(appendix)
+
+    return files
+
+
+def chapter_html_name(md_path: Path) -> str:
+    """Stable HTML filename for a book markdown file."""
+    stem = md_path.stem
+    parent = md_path.parent.name
+    if stem.startswith("preface"):
+        return f"{stem}.html"
+    m = re.match(r"chapter(\d+)", parent)
+    if m:
+        return f"chapter{m.group(1).zfill(2)}.html"
+    return f"{stem}.html"
+
+
+def rewrite_chapter_img_paths(html: str, md_path: Path, book_root: Path) -> str:
+    """Point img/ at the source chapter folder from flat book_html/."""
+    chapter_dir = md_path.parent.resolve()
+    try:
+        rel = chapter_dir.relative_to(book_root.resolve()).as_posix()
+    except ValueError:
+        rel = chapter_dir.name
+    prefix = f"../{rel}/img/"
+    return re.sub(r'src="img/', f'src="{prefix}', html)
+
+
+def render_book(
+    root: Path | str,
+    *,
+    output_dir: Path | str | None = None,
+    lang: str = "en",
+    site_title: str = "",
+    theme: str = "default",
+    custom_css: Path | None = None,
+    mathjax: bool = True,
+    include_config: Path | str | None = None,
+    processor: MarkdownProcessor | None = None,
+) -> dict[str, Any]:
+    """Render full book into output_dir with index and prev/next navigation."""
+    book_root = Path(root).resolve()
+    out_dir = (
+        Path(output_dir).resolve()
+        if output_dir is not None
+        else default_book_output_dir(book_root, lang)
+    )
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    md_files = collect_book_markdown(book_root, lang)
+    if not md_files:
+        raise FileNotFoundError(f"No chapter markdown found under {book_root} (lang={lang})")
+
+    cfg = include_config or find_peanut_config(book_root)
+    proc = processor or MarkdownProcessor(include_config=cfg)
+    renderer = BlogRenderer(
+        site_title=site_title,
+        base_url="",
+        theme=theme,
+        custom_css=custom_css,
+        mathjax=mathjax,
+    )
+    renderer.copy_static_assets(out_dir, custom_css)
+
+    chapters: list[BookChapter] = []
+    processed: list[dict[str, Any]] = []
+
+    for order, md_path in enumerate(md_files):
+        result = proc.process_file(md_path)
+        if not result:
+            continue
+        result["content"] = rewrite_chapter_img_paths(
+            result["content"], md_path, book_root
+        )
+        html_name = chapter_html_name(md_path)
+        chapters.append(
+            BookChapter(
+                md_path=md_path,
+                html_name=html_name,
+                title=result["metadata"]["title"],
+                order=order,
+            )
+        )
+        processed.append({**result, "html_name": html_name})
+
+    page_counts = [count_pages(item["content"]) for item in processed]
+
+    built: list[str] = []
+    for i, item in enumerate(processed):
+        ch = chapters[i]
+        prev_ch = chapters[i - 1] if i > 0 else None
+        next_ch = chapters[i + 1] if i + 1 < len(chapters) else None
+        html = renderer.render_post(
+            item,
+            book_mode=True,
+            prev_href=prev_ch.html_name if prev_ch else None,
+            prev_title=prev_ch.title if prev_ch else None,
+            next_href=next_ch.html_name if next_ch else None,
+            next_title=next_ch.title if next_ch else None,
+            prev_chapter_pages=page_counts[i - 1] if i > 0 else 0,
+        )
+        out_file = out_dir / ch.html_name
+        out_file.write_text(html, encoding="utf-8")
+        built.append(str(out_file))
+
+    index_html = renderer.render_book_index(
+        [
+            {"title": c.title, "href": c.html_name, "source": str(c.md_path)}
+            for c in chapters
+        ],
+        site_title=site_title,
+    )
+    index_path = out_dir / "index.html"
+    index_path.write_text(index_html, encoding="utf-8")
+    built.insert(0, str(index_path))
+
+    return {
+        "root": str(book_root),
+        "output_dir": str(out_dir),
+        "lang": lang,
+        "count": len(chapters),
+        "built": built,
+        "index": str(index_path),
+    }

xuanxin/builder.py

@@ -0,0 +1,128 @@
+"""Build static HTML site from Markdown blog files."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from xuanxin.includes import find_peanut_config
+from xuanxin.processor import MarkdownProcessor
+from xuanxin.renderer import BlogRenderer
+
+
+@dataclass
+class BlogBuilder:
+    """Scan a content directory and emit a static HTML blog."""
+
+    content_dir: Path
+    output_dir: Path
+    site_title: str = "Blog"
+    site_description: str = ""
+    base_url: str = ""
+    theme: str = "default"
+    custom_css: Path | None = None
+    pattern: str = "**/*.md"
+    include_drafts: bool = False
+    mathjax: bool = True
+    processor: MarkdownProcessor = field(default_factory=MarkdownProcessor)
+
+    def build(self) -> dict[str, Any]:
+        self.content_dir = Path(self.content_dir)
+        self.output_dir = Path(self.output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        posts_dir = self.output_dir / "posts"
+        posts_dir.mkdir(exist_ok=True)
+
+        renderer = BlogRenderer(
+            site_title=self.site_title,
+            site_description=self.site_description,
+            base_url=self.base_url,
+            theme=self.theme,
+            custom_css=self.custom_css,
+            mathjax=self.mathjax,
+        )
+        renderer.copy_static_assets(self.output_dir, self.custom_css)
+
+        posts: list[dict[str, Any]] = []
+        built: list[str] = []
+        skipped: list[str] = []
+
+        for md_path in sorted(self.content_dir.glob(self.pattern)):
+            if md_path.name.startswith("."):
+                continue
+            result = self.processor.process_file(md_path)
+            if not result:
+                skipped.append(str(md_path))
+                continue
+
+            meta = result["metadata"]
+            if meta.get("draft") and not self.include_drafts:
+                skipped.append(str(md_path))
+                continue
+
+            posts.append(result)
+            out_file = posts_dir / f"{meta['slug']}.html"
+            out_file.write_text(renderer.render_post(result), encoding="utf-8")
+            built.append(str(out_file))
+
+        index_html = renderer.render_index(posts)
+        (self.output_dir / "index.html").write_text(index_html, encoding="utf-8")
+
+        manifest = {
+            "site_title": self.site_title,
+            "posts": [
+                {
+                    "title": p["metadata"]["title"],
+                    "slug": p["metadata"]["slug"],
+                    "date": p["metadata"]["date"].isoformat(),
+                    "source": p.get("source_file"),
+                }
+                for p in posts
+            ],
+        }
+        (self.output_dir / "manifest.json").write_text(
+            json.dumps(manifest, indent=2), encoding="utf-8"
+        )
+
+        return {"built": built, "skipped": skipped, "count": len(built)}
+
+
+def render_file(
+    md_path: Path | str,
+    *,
+    output_dir: Path | None = None,
+    site_title: str = "",
+    theme: str = "default",
+    custom_css: Path | None = None,
+    mathjax: bool = True,
+    include_config: Path | str | None = None,
+    processor: MarkdownProcessor | None = None,
+) -> Path:
+    """Render one Markdown file to {stem}.html in the current directory."""
+    md_path = Path(md_path).resolve()
+    if not md_path.exists():
+        raise FileNotFoundError(md_path)
+
+    out_dir = Path(output_dir or Path.cwd()).resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_file = out_dir / f"{md_path.stem}.html"
+
+    cfg = include_config or find_peanut_config(md_path.parent)
+    proc = processor or MarkdownProcessor(include_config=cfg)
+    result = proc.process_file(md_path)
+    if not result:
+        raise RuntimeError(f"Failed to process {md_path}")
+
+    renderer = BlogRenderer(
+        site_title=site_title,
+        base_url="",
+        theme=theme,
+        custom_css=custom_css,
+        mathjax=mathjax,
+    )
+    renderer.copy_static_assets(out_dir, custom_css)
+    out_file.write_text(renderer.render_post(result), encoding="utf-8")
+    return out_file

xuanxin/cli.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""CLI for xuanxin — build static HTML from Markdown."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from xuanxin import __version__
+from xuanxin.book import default_book_output_dir, discover_book_repo_root, render_book
+from xuanxin.builder import BlogBuilder, render_file
+from xuanxin.processor import MarkdownProcessor
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    custom_css = Path(args.css) if args.css else None
+    if custom_css and not custom_css.exists():
+        print(f"Warning: custom CSS not found: {custom_css}", file=sys.stderr)
+
+    builder = BlogBuilder(
+        content_dir=Path(args.input),
+        output_dir=Path(args.output),
+        site_title=args.title,
+        site_description=args.description,
+        base_url=args.base_url,
+        theme=args.theme,
+        custom_css=custom_css,
+        pattern=args.pattern,
+        include_drafts=args.include_drafts,
+        mathjax=not args.no_mathjax,
+    )
+    result = builder.build()
+    print(f"Built {result['count']} post(s) → {args.output}")
+    for path in result["built"]:
+        print(f"  ✓ {path}")
+    if result["skipped"]:
+        print(f"Skipped {len(result['skipped'])} file(s)")
+    return 0
+
+
+def cmd_render(args: argparse.Namespace) -> int:
+    """Render one .md file, or the full book with --book."""
+    custom_css = Path(args.css) if args.css else None
+    if custom_css and not custom_css.exists():
+        print(f"Warning: custom CSS not found: {custom_css}", file=sys.stderr)
+
+    include_config = Path(args.config) if args.config else None
+    if include_config and not include_config.exists():
+        print(f"Warning: config not found: {include_config}", file=sys.stderr)
+
+    if args.book:
+        root = Path(args.root) if args.root else discover_book_repo_root()
+        out_dir = (
+            Path(args.output)
+            if args.output
+            else default_book_output_dir(root, args.lang)
+        )
+        result = render_book(
+            root,
+            output_dir=out_dir,
+            lang=args.lang,
+            site_title=args.title,
+            theme=args.theme,
+            custom_css=custom_css,
+            mathjax=not args.no_mathjax,
+            include_config=include_config,
+        )
+        print(f"Built {result['count']} chapter(s) → {result['output_dir']}")
+        for path in result["built"]:
+            print(f"  ✓ {path}")
+        return 0
+
+    if not args.file:
+        print("error: provide a markdown file or use --book", file=sys.stderr)
+        return 1
+
+    out_dir = Path(args.output) if args.output else Path.cwd()
+    out_file = render_file(
+        Path(args.file),
+        output_dir=out_dir,
+        site_title=args.title,
+        theme=args.theme,
+        custom_css=custom_css,
+        mathjax=not args.no_mathjax,
+        include_config=include_config,
+    )
+    print(f"✓ {out_file}")
+    return 0
+
+
+def cmd_preview(args: argparse.Namespace) -> int:
+    """Convert a single markdown file and print HTML body to stdout."""
+    processor = MarkdownProcessor()
+    result = processor.process_file(Path(args.file))
+    if not result:
+        print("Failed to process file", file=sys.stderr)
+        return 1
+    print(result["content"])
+    return 0
+
+
+def cmd_themes(_args: argparse.Namespace) -> int:
+    from xuanxin.renderer import DEFAULT_THEME_DIR
+
+    print("Available themes:")
+    for css in sorted(DEFAULT_THEME_DIR.glob("*.css")):
+        if css.name.startswith("_"):
+            continue
+        print(f"  {css.stem}")
+    print("\nCustomize: copy a theme file, edit :root variables, pass --css your-theme.css")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="xuanxin",
+        description="Write Markdown blogs, generate beautiful static HTML.",
+    )
+    parser.add_argument("--version", action="version", version=f"xuanxin {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    build = sub.add_parser("build", help="Build static site from Markdown files")
+    build.add_argument("-i", "--input", default="content", help="Content directory (default: content)")
+    build.add_argument("-o", "--output", default="dist", help="Output directory (default: dist)")
+    build.add_argument("-t", "--title", default="Blog", help="Site title")
+    build.add_argument("-d", "--description", default="", help="Site description")
+    build.add_argument("--base-url", default="", help="Base URL prefix for links (e.g. /blog)")
+    build.add_argument("--theme", default="default", help="Built-in theme name (default, dark, minimal)")
+    build.add_argument("--css", default="", help="Path to custom CSS file (overrides theme vars)")
+    build.add_argument("--pattern", default="**/*.md", help="Glob pattern for markdown files")
+    build.add_argument("--include-drafts", action="store_true", help="Include draft posts")
+    build.add_argument("--no-mathjax", action="store_true", help="Disable MathJax for LaTeX")
+    build.set_defaults(func=cmd_build)
+
+    render = sub.add_parser(
+        "render",
+        help="Render one .md file, or the full book with --book",
+    )
+    render.add_argument(
+        "file",
+        nargs="?",
+        default="",
+        help="Markdown file path (omit with --book)",
+    )
+    render.add_argument(
+        "--book",
+        action="store_true",
+        help="Render full book (preface, chapters 1–12, appendix) to book_html_{lang}/",
+    )
+    render.add_argument(
+        "--lang",
+        default="zh",
+        help="Book language suffix: en, zh, tc, jp, sp (default: zh)",
+    )
+    render.add_argument(
+        "--root",
+        default="",
+        help="Book repository root (default: auto-detect from cwd)",
+    )
+    render.add_argument(
+        "-o",
+        "--output",
+        default="",
+        help="Output directory (default: book_html/ or book_html_{lang}/ for --book)",
+    )
+    render.add_argument(
+        "-t",
+        "--title",
+        default="",
+        help="Site title (optional; shown in header and page title suffix)",
+    )
+    render.add_argument(
+        "--config",
+        default="",
+        help="Path to peanut.config for conditional includes (default: auto-detect)",
+    )
+    render.add_argument("--theme", default="default", help="Built-in theme (default, dark, minimal)")
+    render.add_argument("--css", default="", help="Path to custom CSS file")
+    render.add_argument("--no-mathjax", action="store_true", help="Disable MathJax for LaTeX")
+    render.set_defaults(func=cmd_render)
+
+    preview = sub.add_parser("preview", help="Print HTML body for one markdown file")
+    preview.add_argument("file", help="Markdown file path")
+    preview.set_defaults(func=cmd_preview)
+
+    themes = sub.add_parser("themes", help="List available built-in themes")
+    themes.set_defaults(func=cmd_themes)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())