obsidian2pdf 0.1.0__tar.gz

obsidian2pdf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 afamrk
+
+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.

obsidian2pdf-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: obsidian2pdf
+Version: 0.1.0
+Summary: Export Obsidian notes and folders to e-reader-ready PDFs
+Author: afamrk
+License-Expression: MIT
+Keywords: obsidian,pdf,epub,kobo,markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: markdown>=3.5
+Requires-Dist: weasyprint>=60
+Requires-Dist: pygments>=2.17
+Requires-Dist: curl_cffi>=0.7
+Requires-Dist: ebooklib>=0.19
+Requires-Dist: Pillow>=10.1
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pypdf>=4.0; extra == "test"
+Dynamic: license-file
+
+# obsidian2pdf
+
+Export an Obsidian note or folder to a single PDF — including a page preset
+matching the Kobo Libra Colour screen so notes read comfortably on the device.
+
+## Install
+
+    python3 -m venv .venv
+    .venv/bin/pip install -e .
+
+WeasyPrint needs Pango; on Debian/Ubuntu:
+`sudo apt install libpango-1.0-0 libpangoft2-1.0-0`.
+
+## Usage
+
+    obsidian2pdf <note.md | folder> [options]
+
+    -o, --output PATH     output PDF (default: <input name>.pdf next to input)
+    -s, --size SIZE       a4 (default), a5, kobo-libra-colour, kobo-clara,
+                          custom "1264x1680@300" (px@dpi) or "91x120mm";
+                          ignored when --format is epub (reflowable, no
+                          fixed page)
+    --format NAME         pdf (default) | epub
+    --order NAME          alpha (default) | makemd (manual order from the
+                          make.md plugin's .space/context.mdb)
+    --ignore EXT[,EXT..]  drop embeds of these media types, e.g. "png,mp3"
+    --no-cover            skip the cover page
+    -v, --verbose         progress info
+
+## What it does with a folder
+
+Notes merge into one PDF: each file name becomes a heading, headings inside
+the file shift one level down; subfolders become nested sections; a folder
+note (`X/X.md`) renders as the section intro. Frontmatter is stripped,
+`![[image]]` embeds are resolved vault-wide, remote images are downloaded at
+export time, YouTube/note embeds render as styled references, and fenced code
+blocks get Pygments syntax highlighting.

obsidian2pdf-0.1.0/README.md

@@ -0,0 +1,37 @@
+# obsidian2pdf
+
+Export an Obsidian note or folder to a single PDF — including a page preset
+matching the Kobo Libra Colour screen so notes read comfortably on the device.
+
+## Install
+
+    python3 -m venv .venv
+    .venv/bin/pip install -e .
+
+WeasyPrint needs Pango; on Debian/Ubuntu:
+`sudo apt install libpango-1.0-0 libpangoft2-1.0-0`.
+
+## Usage
+
+    obsidian2pdf <note.md | folder> [options]
+
+    -o, --output PATH     output PDF (default: <input name>.pdf next to input)
+    -s, --size SIZE       a4 (default), a5, kobo-libra-colour, kobo-clara,
+                          custom "1264x1680@300" (px@dpi) or "91x120mm";
+                          ignored when --format is epub (reflowable, no
+                          fixed page)
+    --format NAME         pdf (default) | epub
+    --order NAME          alpha (default) | makemd (manual order from the
+                          make.md plugin's .space/context.mdb)
+    --ignore EXT[,EXT..]  drop embeds of these media types, e.g. "png,mp3"
+    --no-cover            skip the cover page
+    -v, --verbose         progress info
+
+## What it does with a folder
+
+Notes merge into one PDF: each file name becomes a heading, headings inside
+the file shift one level down; subfolders become nested sections; a folder
+note (`X/X.md`) renders as the section intro. Frontmatter is stripped,
+`![[image]]` embeds are resolved vault-wide, remote images are downloaded at
+export time, YouTube/note embeds render as styled references, and fenced code
+blocks get Pygments syntax highlighting.

obsidian2pdf-0.1.0/obsidian2pdf/cli.py

@@ -0,0 +1,163 @@
+"""Command-line entry point: wires collector, pipeline, renderer, writer."""
+from __future__ import annotations
+
+import argparse
+import sys
+import tempfile
+from pathlib import Path
+
+from . import vault
+from .collector.ordering import AlphabeticalOrderStrategy, MakeMdOrderStrategy
+from .collector.tree import build_tree
+from .pagespec import PRESETS, resolve_size
+from .writer.epub import write_epub
+from .writer.pdf import write_pdf
+from .preprocess.pipeline import default_pipeline
+from .preprocess.transforms import NoteContext
+from .render.cover import cover_html
+from .render.document import DocumentRenderer, build_document, stylesheet
+
+ORDERINGS = {
+    "alpha": AlphabeticalOrderStrategy,
+    "makemd": MakeMdOrderStrategy,
+}
+
+
+_EXAMPLES = """\
+examples:
+  # A folder, as A4 PDF (the default)
+  obsidian2pdf ~/vault/Docker
+
+  # Kobo-ready PDF, respecting make.md's manual note order
+  obsidian2pdf ~/vault/Kubernetes -s kobo-libra-colour --order makemd -o kubernetes.pdf
+
+  # EPUB, dropping images/audio, no syntax highlighting, no cover
+  obsidian2pdf ~/vault/Docker --format epub --ignore png,jpg,mp3 --no-highlight --no-cover -o docker.epub
+
+  # EPUB with your own cover artwork instead of the generated title page
+  obsidian2pdf ~/vault/Kubernetes --format epub --cover-image ~/art/cover.jpg -o kubernetes.epub
+
+  # A single note instead of a folder
+  obsidian2pdf ~/vault/Docker/Basic.md -o basic.pdf
+
+  # Custom page size for a different e-reader (px@dpi or mm)
+  obsidian2pdf ~/vault/Kubernetes -s "1072x1448@300" -v -o kubernetes-custom.pdf
+"""
+
+
+def parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="obsidian2pdf",
+        description="Export an Obsidian note or folder to a single PDF or EPUB.",
+        epilog=_EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("input", type=Path, help="path to a .md note or folder")
+    parser.add_argument(
+        "-o", "--output", type=Path,
+        help="output file (default: <input name>.<format> next to the input)",
+    )
+    parser.add_argument(
+        "-s", "--size", default="a4",
+        help=f"page size: {', '.join(sorted(PRESETS))}, WxH@DPI, or WxHmm "
+             "(default: a4)",
+    )
+    parser.add_argument(
+        "--order", choices=sorted(ORDERINGS), default="alpha",
+        help="child ordering per folder (default: alpha)",
+    )
+    parser.add_argument(
+        "--ignore", default="", metavar="EXT[,EXT...]",
+        help='media types to drop from the output, e.g. "png,mp3"',
+    )
+    parser.add_argument(
+        "--no-cover", action="store_true", help="skip the cover page"
+    )
+    parser.add_argument(
+        "--cover-image", type=Path, default=None, metavar="PATH",
+        help="use this image as the EPUB's cover thumbnail instead of the "
+             "generated one; ignored for --format pdf and with --no-cover",
+    )
+    parser.add_argument(
+        "--no-highlight", action="store_true",
+        help="disable syntax highlighting in code blocks",
+    )
+    parser.add_argument(
+        "--format", choices=("pdf", "epub"), default="pdf",
+        help="output format (default: pdf); --size has no effect on epub",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="print progress info"
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    input_path = args.input.expanduser().resolve()
+    if not input_path.exists():
+        print(f"error: {input_path} does not exist", file=sys.stderr)
+        return 2
+    try:
+        page = resolve_size(args.size)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if args.cover_image is not None and not args.cover_image.is_file():
+        print(f"error: {args.cover_image} does not exist", file=sys.stderr)
+        return 2
+
+    ignored = frozenset(
+        ext.strip().lstrip(".").lower()
+        for ext in args.ignore.split(",")
+        if ext.strip()
+    )
+    vault_root = vault.find_vault_root(input_path)
+    attachments = vault.build_attachment_index(vault_root)
+    if args.verbose:
+        print(f"vault root: {vault_root} ({len(attachments)} attachments)")
+
+    try:
+        tree = build_tree(input_path, ORDERINGS[args.order]())
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    output = args.output or input_path.parent / (input_path.stem + f".{args.format}")
+    with tempfile.TemporaryDirectory(prefix="obsidian2pdf-") as cache:
+        def make_context(note_path: Path) -> NoteContext:
+            return NoteContext(
+                note_path=note_path,
+                vault_root=vault_root,
+                attachments=attachments,
+                ignored_exts=ignored,
+                image_cache_dir=Path(cache),
+            )
+
+        highlight = not args.no_highlight
+        renderer = DocumentRenderer(default_pipeline(), make_context, highlight)
+        cover = "" if args.no_cover else cover_html(tree.title)
+
+        if args.format == "epub":
+            css = stylesheet(PRESETS["a4"], highlight)
+            custom_cover_image = None
+            if cover and args.cover_image is not None:
+                custom_cover_image = (
+                    args.cover_image.read_bytes(),
+                    f"cover-image{args.cover_image.suffix}",
+                )
+            write_epub(tree, renderer, output, css, cover, custom_cover_image)
+        else:
+            body = renderer.render(tree)
+            document = build_document(body, stylesheet(page, highlight), cover)
+            write_pdf(document, output)
+
+    for warning in renderer.warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    if args.verbose:
+        print(f"wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

obsidian2pdf-0.1.0/obsidian2pdf/collector/ordering.py

@@ -0,0 +1,60 @@
+"""Ordering strategies for a folder's children (Strategy pattern)."""
+from __future__ import annotations
+
+import re
+import sqlite3
+from pathlib import Path
+from typing import Protocol
+
+
+class OrderingStrategy(Protocol):
+    def order(self, folder: Path, entries: list[Path]) -> list[Path]: ...
+
+
+def _natural_key(path: Path) -> list:
+    return [
+        int(tok) if tok.isdigit() else tok.casefold()
+        for tok in re.split(r"(\d+)", path.name)
+    ]
+
+
+class AlphabeticalOrderStrategy:
+    """Natural sort: '2 foo' comes before '10 foo'."""
+
+    def order(self, folder: Path, entries: list[Path]) -> list[Path]:
+        return sorted(entries, key=_natural_key)
+
+
+class MakeMdOrderStrategy:
+    """Manual order from make.md: row order of the `files` table in
+    <folder>/.space/context.mdb (verified: rowid order == sidebar order).
+
+    Entries missing from the table are appended alphabetically; table rows
+    with no file on disk are ignored. No database -> alphabetical.
+    """
+
+    def order(self, folder: Path, entries: list[Path]) -> list[Path]:
+        rank = {name: i for i, name in enumerate(self._read_order(folder))}
+        ranked = sorted(
+            (e for e in entries if e.name in rank), key=lambda e: rank[e.name]
+        )
+        unranked = [e for e in entries if e.name not in rank]
+        return ranked + AlphabeticalOrderStrategy().order(folder, unranked)
+
+    @staticmethod
+    def _read_order(folder: Path) -> list[str]:
+        db = folder / ".space" / "context.mdb"
+        if not db.is_file():
+            return []
+        try:
+            con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+            try:
+                rows = con.execute(
+                    'SELECT "File" FROM files ORDER BY rowid'
+                ).fetchall()
+            finally:
+                con.close()
+        except sqlite3.Error:
+            return []
+        # Values are vault-relative paths ("Kubernetes/Basic.md"); keep names.
+        return [Path(str(r[0])).name for r in rows]

obsidian2pdf-0.1.0/obsidian2pdf/collector/tree.py

@@ -0,0 +1,59 @@
+"""Document tree: Composite of folder sections and notes."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .ordering import OrderingStrategy
+
+
+@dataclass
+class NoteNode:
+    path: Path
+    title: str
+
+
+@dataclass
+class SectionNode:
+    path: Path
+    title: str
+    intro: NoteNode | None = None  # the folder note (X/X.md), if any
+    children: list["SectionNode | NoteNode"] = field(default_factory=list)
+
+
+def build_tree(input_path: Path, strategy: OrderingStrategy) -> SectionNode | NoteNode:
+    input_path = input_path.resolve()
+    if input_path.is_file():
+        return NoteNode(input_path, input_path.stem)
+    section = _build_section(input_path, strategy)
+    if section.intro is None and not section.children:
+        raise ValueError(f"no markdown notes found under {input_path}")
+    return section
+
+
+def _has_notes(folder: Path) -> bool:
+    return any(
+        not any(part.startswith(".") for part in p.relative_to(folder).parts)
+        for p in folder.rglob("*.md")
+    )
+
+
+def _build_section(folder: Path, strategy: OrderingStrategy) -> SectionNode:
+    section = SectionNode(folder, folder.name)
+    entries: list[Path] = []
+    for child in folder.iterdir():
+        if child.name.startswith("."):
+            continue
+        if child.is_file() and child.suffix == ".md":
+            if child.stem == folder.name:
+                section.intro = NoteNode(child, child.stem)
+            else:
+                entries.append(child)
+        elif child.is_dir() and _has_notes(child):
+            entries.append(child)
+    for path in strategy.order(folder, entries):
+        if path.is_dir():
+            section.children.append(_build_section(path, strategy))
+        else:
+            section.children.append(NoteNode(path, path.stem))
+    return section

obsidian2pdf-0.1.0/obsidian2pdf/pagespec.py

@@ -0,0 +1,49 @@
+"""Page geometry: named presets and custom size specs."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PageSpec:
+    name: str
+    width_mm: float
+    height_mm: float
+    base_font_pt: float = 10.0
+
+    @property
+    def css_size(self) -> str:
+        return f"{self.width_mm:.2f}mm {self.height_mm:.2f}mm"
+
+
+# Kobo presets are the device screens at 300 ppi, converted to millimetres.
+PRESETS = {
+    "a4": PageSpec("a4", 210.0, 297.0, 11.0),
+    "a5": PageSpec("a5", 148.0, 210.0, 10.0),
+    "kobo-libra-colour": PageSpec("kobo-libra-colour", 107.0, 142.2, 8.5),
+    "kobo-clara": PageSpec("kobo-clara", 90.8, 122.6, 8.0),
+}
+
+_PX_SPEC = re.compile(r"^(\d+)x(\d+)@(\d+)$")
+_MM_SPEC = re.compile(r"^(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)mm$")
+
+
+def resolve_size(spec: str) -> PageSpec:
+    """Resolve a preset name, 'WxH@DPI' (pixels), or 'WxHmm' into a PageSpec."""
+    key = spec.strip().lower()
+    if key in PRESETS:
+        return PRESETS[key]
+    m = _PX_SPEC.match(key)
+    if m:
+        w_px, h_px, dpi = (int(g) for g in m.groups())
+        if dpi == 0:
+            raise ValueError(f"dpi must be positive in size spec {spec!r}")
+        return PageSpec(key, w_px / dpi * 25.4, h_px / dpi * 25.4)
+    m = _MM_SPEC.match(key)
+    if m:
+        return PageSpec(key, float(m.group(1)), float(m.group(2)))
+    raise ValueError(
+        f"unknown page size {spec!r} — presets: {', '.join(sorted(PRESETS))}; "
+        "custom: WxH@DPI (pixels) or WxHmm"
+    )

obsidian2pdf-0.1.0/obsidian2pdf/preprocess/host_adapters.py

@@ -0,0 +1,66 @@
+"""Per-host adapters for fetching hotlink-protected remote images.
+
+Mirrors the ordering Strategy pattern (collector/ordering.py): each host
+that needs special handling gets its own adapter; hosts with no adapter
+fall through to a generic one that sets a parent-domain Referer.
+"""
+from __future__ import annotations
+
+import re
+import urllib.parse
+from typing import Protocol
+
+
+class HostAdapter(Protocol):
+    def matches(self, url: str) -> bool: ...
+
+    def fetch_target(self, url: str) -> tuple[str, str]:
+        """Returns (url_to_fetch, referer)."""
+        ...
+
+
+class ImgurAdapter:
+    """i.imgur.com direct links resolve to an HTML "removed" page (status
+    200, not 404) unless routed through Imgur's download endpoint with a
+    Referer from the image's own page."""
+
+    _DIRECT = re.compile(r"^https?://i\.imgur\.com/([A-Za-z0-9]+)(?:\.\w+)?$")
+
+    def matches(self, url: str) -> bool:
+        return bool(self._DIRECT.match(url))
+
+    def fetch_target(self, url: str) -> tuple[str, str]:
+        image_id = self._DIRECT.match(url).group(1)
+        return (
+            f"https://imgur.com/download/{image_id}/",
+            f"https://imgur.com/{image_id}",
+        )
+
+
+class GenericAdapter:
+    """Fallback for hosts with no dedicated adapter: leave the URL as-is
+    and set a Referer from the parent domain, since hotlink protection
+    commonly trusts same-site Referers (e.g. a CDN subdomain trusting
+    requests referred from its own root domain)."""
+
+    def matches(self, url: str) -> bool:
+        return True
+
+    def fetch_target(self, url: str) -> tuple[str, str]:
+        netloc = urllib.parse.urlparse(url).netloc
+        parts = netloc.split(".")
+        parent = ".".join(parts[1:]) if len(parts) > 2 else netloc
+        return url, f"https://{parent}/"
+
+
+_ADAPTERS: list[HostAdapter] = [ImgurAdapter()]
+_DEFAULT_ADAPTER: HostAdapter = GenericAdapter()
+
+
+def resolve_fetch_target(url: str) -> tuple[str, str]:
+    """Returns (url_to_fetch, referer) for the first matching adapter, or
+    the generic adapter's result when no host-specific adapter applies."""
+    for adapter in _ADAPTERS:
+        if adapter.matches(url):
+            return adapter.fetch_target(url)
+    return _DEFAULT_ADAPTER.fetch_target(url)

obsidian2pdf-0.1.0/obsidian2pdf/preprocess/pipeline.py

@@ -0,0 +1,57 @@
+"""Runs transforms in order with fenced and inline code masked out, so
+Obsidian syntax inside code samples is never rewritten."""
+from __future__ import annotations
+
+import re
+
+from .transforms import (
+    FrontmatterStripper,
+    IgnoredMediaFilter,
+    ImageEmbedResolver,
+    LocalMdImageResolver,
+    NoteContext,
+    NoteEmbedToLink,
+    RemoteImageFetcher,
+    Transform,
+    VideoEmbedToLink,
+    WikilinkToText,
+)
+
+
+class Pipeline:
+    _FENCED = re.compile(
+        r"^(```|~~~)[^\n]*\n.*?^\1[ \t]*$", re.DOTALL | re.MULTILINE
+    )
+    _INLINE = re.compile(r"`[^`\n]+`")
+    _SLOT = re.compile(r"\x00(\d+)\x00")
+
+    def __init__(self, transforms: list[Transform]):
+        self.transforms = list(transforms)
+
+    def run(self, text: str, ctx: NoteContext) -> str:
+        stash: list[str] = []
+
+        def mask(m: re.Match) -> str:
+            stash.append(m.group(0))
+            return f"\x00{len(stash) - 1}\x00"
+
+        masked = self._FENCED.sub(mask, text)
+        masked = self._INLINE.sub(mask, masked)
+        for transform in self.transforms:
+            masked = transform.apply(masked, ctx)
+        return self._SLOT.sub(lambda m: stash[int(m.group(1))], masked)
+
+
+def default_pipeline() -> Pipeline:
+    """Order matters: filter ignored media before resolvers; classify video
+    URLs before the remote fetcher; wiki image embeds before generic embeds."""
+    return Pipeline([
+        FrontmatterStripper(),
+        IgnoredMediaFilter(),
+        VideoEmbedToLink(),
+        ImageEmbedResolver(),
+        NoteEmbedToLink(),
+        WikilinkToText(),
+        LocalMdImageResolver(),
+        RemoteImageFetcher(),
+    ])