astro-slidev 0.1.0__tar.gz

astro_slidev-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.astro-slidev-build/

astro_slidev-0.1.0/LICENSE

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

astro_slidev-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: astro-slidev
+Version: 0.1.0
+Summary: Turn an Astro content-collection blog post into a Slidev presentation deck — deterministic, no LLM.
+Project-URL: Homepage, https://github.com/stormsidali2001/astro-slidev
+Project-URL: Repository, https://github.com/stormsidali2001/astro-slidev
+Project-URL: Issues, https://github.com/stormsidali2001/astro-slidev/issues
+Author: Sidali Assoul
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: markdown-it-py>=3.0.0
+Requires-Dist: mdit-py-plugins>=0.4.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# astro-slidev
+
+Turn an Astro content-collection blog post into a [Slidev](https://sli.dev) presentation deck — **deterministic, no LLM**. The same post always produces the same deck: a rule-based planner decides slide breaks, code grouping, table chunking, and layout, so you get a reproducible result you can tweak and re-run, not a one-off AI summary.
+
+```bash
+pip install astro-slidev
+cd my-astro-project
+astro-slidev build src/content/blog/my-post.md
+# -> .astro-slidev-build/my-post/slide.md (+ assets/, layouts/, styles/)
+
+npx @slidev/cli dev .astro-slidev-build/my-post/slide.md
+```
+
+## What it does
+
+- Parses a post's Markdown (frontmatter + body) into an intermediate representation, never touching your live site's content.
+- Plans a deck: groups short paragraphs and short code blocks onto shared slides instead of one-block-per-slide, isolates long code blocks, chunks oversized tables across continuation slides (so a 30-row table doesn't silently run off the bottom of a slide), and gives every code+list pairing a two-column "explanation" layout when it's a genuine line-by-line walkthrough.
+- Renders real Slidev markdown: a cover slide (title/description/date/tags), a section-divider slide per H2/H3, and content slides — plus an agenda and summary slide built from your headings.
+- Handles images (colocated with the post, downscaled if oversized), GFM tables, KaTeX math (`$...$` / `$$...$$`, passed through untouched), blockquote-style callouts (`> **Note:** ...`), and speaker notes (`<!-- note: ... -->`, invisible on your live site, shown in Slidev's presenter view).
+- Ships a small, optional accent-color theme (kicker bars, tag pills, tinted table headers) that stays off by default — a fresh install produces a plain, unbranded deck using Slidev's own theme.
+
+## Why not just ask an LLM to write the slides?
+
+You can, and for a one-off talk that's often faster. This exists for the opposite case: you maintain a blog with dozens of posts and want a repeatable, reviewable way to turn any of them into a deck — one whose output you can diff, whose grouping rules you can tune once for your whole content style, and that never silently changes when you rerun it.
+
+## Installation
+
+```bash
+pip install astro-slidev
+```
+
+Requires Python 3.10+. `astro-slidev` is a pure-Python CLI — it does **not** install or invoke Slidev/Node for you. Generate the deck, then run Slidev yourself:
+
+```bash
+npx @slidev/cli dev <output-dir>/slide.md      # live preview
+npx @slidev/cli build <output-dir>/slide.md --out dist/slides  # static export
+```
+
+## Usage
+
+```bash
+# Build a specific post (path or bare slug, resolved against content_dirs)
+astro-slidev build src/content/blog/my-post.md
+astro-slidev build my-post
+
+# No post given -> pick one interactively (series, then post)
+astro-slidev build
+
+# Override output directory / config file
+astro-slidev build my-post --out dist/deck --config ./my-slides.yaml
+```
+
+`astro-slidev build` always runs from your project root (the directory you invoke it from) and writes exactly one line to stdout: the path to the generated deck directory. Everything else (progress, the follow-up Slidev commands) goes to stderr, so it composes cleanly with shell capture:
+
+```bash
+npx @slidev/cli dev "$(astro-slidev build my-post)/slide.md"
+```
+
+## Configuration
+
+Drop a `slides.config.yaml` in your project root (picked up automatically) or pass `--config path/to/file.yaml`. You only need to list the keys you want to override — see [`src/astro_slidev/slides.config.yaml`](src/astro_slidev/slides.config.yaml) for the full set of defaults with comments.
+
+| Key | Default | What it controls |
+|---|---|---|
+| `content_dirs` | `["src/content/blog"]` | Where the interactive picker looks, and where a bare slug resolves against. Add more entries for a multi-collection or multi-locale project. |
+| `max_words_per_slide` | `90` | Budget for packing paragraphs/explanations onto one slide. |
+| `max_bullets_per_slide` | `6` | Max bullets before a list splits into continuation slides. |
+| `max_code_blocks_per_slide` | `3` | Max consecutive short code blocks grouped onto one slide. |
+| `max_lines_per_code_block` | `25` | A code block longer than this always gets its own slide. |
+| `max_rows_per_slide` | `5` | Max table rows before it splits into continuation slides (header repeated). |
+| `code_layout` | `two-cols` | Layout for a code block with an attached line-by-line explanation list. |
+| `max_image_dimension` | `2000` | Images wider/taller than this (px) get downscaled on copy. |
+| `include_agenda` / `include_summary` | `true` | Whether to generate an agenda slide after the cover and a summary slide at the end. |
+| `font_sans` / `font_mono` / `accent_color` | unset | Opt-in branding — set these to match your site's design system (e.g. `accent_color: "#2563EB"`). Unset means a plain Slidev deck with no custom theming. |
+
+## Supported post conventions
+
+- **Frontmatter**: only `title` is required. `description`, `pubDate`, `tags`, `series`, `seriesOrder` are all optional and degrade gracefully (no subtitle/date/pill row on the cover slide if absent).
+- **Headings**: body content should use `##`/`###` (H2/H3) — H2 becomes a section divider, H3 a subsection. A post with no headings at all still works (everything lands on one section).
+- **Images**: `![alt](./chart.png)`, resolved relative to the post's own file — the standard Astro content-collection colocated-image convention.
+- **Callouts**: an informal blockquote with a bold lead-in, e.g. `> **Note:** ...` / `> **Warning:** ...` / `> **Tip:** ...`.
+- **Speaker notes**: `<!-- note: mention the live demo -->` (single- or multi-line) anywhere in the body — invisible on your live site, shown in Slidev's presenter view on whichever slide the following content lands on.
+- **Math**: `$...$` and `$$...$$`, passed through verbatim for Slidev's built-in KaTeX rendering.
+
+## Development
+
+```bash
+git clone https://github.com/stormsidali2001/astro-slidev
+cd astro-slidev
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

astro_slidev-0.1.0/README.md

@@ -0,0 +1,97 @@
+# astro-slidev
+
+Turn an Astro content-collection blog post into a [Slidev](https://sli.dev) presentation deck — **deterministic, no LLM**. The same post always produces the same deck: a rule-based planner decides slide breaks, code grouping, table chunking, and layout, so you get a reproducible result you can tweak and re-run, not a one-off AI summary.
+
+```bash
+pip install astro-slidev
+cd my-astro-project
+astro-slidev build src/content/blog/my-post.md
+# -> .astro-slidev-build/my-post/slide.md (+ assets/, layouts/, styles/)
+
+npx @slidev/cli dev .astro-slidev-build/my-post/slide.md
+```
+
+## What it does
+
+- Parses a post's Markdown (frontmatter + body) into an intermediate representation, never touching your live site's content.
+- Plans a deck: groups short paragraphs and short code blocks onto shared slides instead of one-block-per-slide, isolates long code blocks, chunks oversized tables across continuation slides (so a 30-row table doesn't silently run off the bottom of a slide), and gives every code+list pairing a two-column "explanation" layout when it's a genuine line-by-line walkthrough.
+- Renders real Slidev markdown: a cover slide (title/description/date/tags), a section-divider slide per H2/H3, and content slides — plus an agenda and summary slide built from your headings.
+- Handles images (colocated with the post, downscaled if oversized), GFM tables, KaTeX math (`$...$` / `$$...$$`, passed through untouched), blockquote-style callouts (`> **Note:** ...`), and speaker notes (`<!-- note: ... -->`, invisible on your live site, shown in Slidev's presenter view).
+- Ships a small, optional accent-color theme (kicker bars, tag pills, tinted table headers) that stays off by default — a fresh install produces a plain, unbranded deck using Slidev's own theme.
+
+## Why not just ask an LLM to write the slides?
+
+You can, and for a one-off talk that's often faster. This exists for the opposite case: you maintain a blog with dozens of posts and want a repeatable, reviewable way to turn any of them into a deck — one whose output you can diff, whose grouping rules you can tune once for your whole content style, and that never silently changes when you rerun it.
+
+## Installation
+
+```bash
+pip install astro-slidev
+```
+
+Requires Python 3.10+. `astro-slidev` is a pure-Python CLI — it does **not** install or invoke Slidev/Node for you. Generate the deck, then run Slidev yourself:
+
+```bash
+npx @slidev/cli dev <output-dir>/slide.md      # live preview
+npx @slidev/cli build <output-dir>/slide.md --out dist/slides  # static export
+```
+
+## Usage
+
+```bash
+# Build a specific post (path or bare slug, resolved against content_dirs)
+astro-slidev build src/content/blog/my-post.md
+astro-slidev build my-post
+
+# No post given -> pick one interactively (series, then post)
+astro-slidev build
+
+# Override output directory / config file
+astro-slidev build my-post --out dist/deck --config ./my-slides.yaml
+```
+
+`astro-slidev build` always runs from your project root (the directory you invoke it from) and writes exactly one line to stdout: the path to the generated deck directory. Everything else (progress, the follow-up Slidev commands) goes to stderr, so it composes cleanly with shell capture:
+
+```bash
+npx @slidev/cli dev "$(astro-slidev build my-post)/slide.md"
+```
+
+## Configuration
+
+Drop a `slides.config.yaml` in your project root (picked up automatically) or pass `--config path/to/file.yaml`. You only need to list the keys you want to override — see [`src/astro_slidev/slides.config.yaml`](src/astro_slidev/slides.config.yaml) for the full set of defaults with comments.
+
+| Key | Default | What it controls |
+|---|---|---|
+| `content_dirs` | `["src/content/blog"]` | Where the interactive picker looks, and where a bare slug resolves against. Add more entries for a multi-collection or multi-locale project. |
+| `max_words_per_slide` | `90` | Budget for packing paragraphs/explanations onto one slide. |
+| `max_bullets_per_slide` | `6` | Max bullets before a list splits into continuation slides. |
+| `max_code_blocks_per_slide` | `3` | Max consecutive short code blocks grouped onto one slide. |
+| `max_lines_per_code_block` | `25` | A code block longer than this always gets its own slide. |
+| `max_rows_per_slide` | `5` | Max table rows before it splits into continuation slides (header repeated). |
+| `code_layout` | `two-cols` | Layout for a code block with an attached line-by-line explanation list. |
+| `max_image_dimension` | `2000` | Images wider/taller than this (px) get downscaled on copy. |
+| `include_agenda` / `include_summary` | `true` | Whether to generate an agenda slide after the cover and a summary slide at the end. |
+| `font_sans` / `font_mono` / `accent_color` | unset | Opt-in branding — set these to match your site's design system (e.g. `accent_color: "#2563EB"`). Unset means a plain Slidev deck with no custom theming. |
+
+## Supported post conventions
+
+- **Frontmatter**: only `title` is required. `description`, `pubDate`, `tags`, `series`, `seriesOrder` are all optional and degrade gracefully (no subtitle/date/pill row on the cover slide if absent).
+- **Headings**: body content should use `##`/`###` (H2/H3) — H2 becomes a section divider, H3 a subsection. A post with no headings at all still works (everything lands on one section).
+- **Images**: `![alt](./chart.png)`, resolved relative to the post's own file — the standard Astro content-collection colocated-image convention.
+- **Callouts**: an informal blockquote with a bold lead-in, e.g. `> **Note:** ...` / `> **Warning:** ...` / `> **Tip:** ...`.
+- **Speaker notes**: `<!-- note: mention the live demo -->` (single- or multi-line) anywhere in the body — invisible on your live site, shown in Slidev's presenter view on whichever slide the following content lands on.
+- **Math**: `$...$` and `$$...$$`, passed through verbatim for Slidev's built-in KaTeX rendering.
+
+## Development
+
+```bash
+git clone https://github.com/stormsidali2001/astro-slidev
+cd astro-slidev
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

astro_slidev-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "astro-slidev"
+version = "0.1.0"
+description = "Turn an Astro content-collection blog post into a Slidev presentation deck — deterministic, no LLM."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Sidali Assoul" }]
+requires-python = ">=3.10"
+dependencies = [
+  "markdown-it-py>=3.0.0",
+  "mdit-py-plugins>=0.4.0",
+  "PyYAML>=6.0",
+  "questionary>=2.0.0",
+  "Pillow>=10.0.0",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Text Processing :: Markup :: Markdown",
+  "Topic :: Software Development :: Documentation",
+]
+
+[project.urls]
+Homepage = "https://github.com/stormsidali2001/astro-slidev"
+Repository = "https://github.com/stormsidali2001/astro-slidev"
+Issues = "https://github.com/stormsidali2001/astro-slidev/issues"
+
+[project.scripts]
+astro-slidev = "astro_slidev.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/astro_slidev"]
+
+[tool.hatch.build]
+include = [
+  "src/astro_slidev/**/*.py",
+  "src/astro_slidev/**/*.vue",
+  "src/astro_slidev/**/*.css",
+  "src/astro_slidev/**/*.yaml",
+]

astro_slidev-0.1.0/src/astro_slidev/__init__.py

@@ -0,0 +1,3 @@
+"""astro-slidev: turn an Astro content-collection post into a Slidev deck."""
+
+__version__ = "0.1.0"

astro_slidev-0.1.0/src/astro_slidev/assets.py

@@ -0,0 +1,114 @@
+"""Copies images referenced by a post into the Slidev build's public/assets/
+dir.
+
+Images are resolved relative to the post's own folder — the standard Astro
+content-collection colocated-image convention (e.g. `![alt](./chart.png)`
+sitting next to the post file) — never relative to the project root or via
+Astro's `image()` schema helper.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from PIL import Image as PILImage
+
+from .models.article import Article, Image, Section
+
+
+def collect_images(sections: list[Section]) -> list[Image]:
+    """Walks the section tree in document order, returning every Image
+    block found. Used to build copy_assets' input list so first-appearance
+    collision-naming order matches the article's actual reading order.
+    """
+    images: list[Image] = []
+    for section in sections:
+        images.extend(b for b in section.blocks if isinstance(b, Image))
+        images.extend(collect_images(section.children))
+    return images
+
+
+def resolve_image_path(article: Article, image: Image) -> Path:
+    return (article.source_dir / image.src).resolve()
+
+
+def _place_image(src_path: Path, dest_path: Path, max_dimension: int) -> None:
+    """Copies `src_path` to `dest_path`, downscaling first if either
+    dimension exceeds `max_dimension`. Some images get saved at export/
+    retina resolution (far beyond what a slide ever displays them at) —
+    shipping them unscaled makes a dev server slow to load and bloats the
+    exported deck for no visual benefit. Images already within budget are
+    copied verbatim (no re-encoding, no quality loss).
+    """
+    try:
+        with PILImage.open(src_path) as img:
+            width, height = img.size
+            if width <= max_dimension and height <= max_dimension:
+                shutil.copy2(src_path, dest_path)
+                return
+
+            scale = max_dimension / max(width, height)
+            new_size = (max(1, round(width * scale)), max(1, round(height * scale)))
+            resized = img.convert("RGBA") if img.mode in ("P", "RGBA", "LA") else img.convert("RGB")
+            resized = resized.resize(new_size, PILImage.LANCZOS)
+            save_kwargs = {"optimize": True}
+            if resized.mode == "RGB" and dest_path.suffix.lower() in (".jpg", ".jpeg"):
+                save_kwargs["quality"] = 85
+            resized.save(dest_path, **save_kwargs)
+    except PILImage.UnidentifiedImageError:
+        shutil.copy2(src_path, dest_path)
+
+
+def copy_assets(
+    article: Article, images: list[Image], build_dir: Path, max_image_dimension: int = 2000
+) -> dict[str, str]:
+    """Copies each resolved image into build_dir/public/assets/, downscaling
+    oversized ones (see _place_image). Returns a mapping from the original
+    Image.src string to a root-absolute deck path (e.g. "/assets/chart.png").
+
+    Vite's public/ convention copies these files verbatim under their
+    original name and never hash-renames them — required here because our
+    renderer references images via a runtime string prop (see
+    layouts/image-caption.vue), not a statically-analyzable import, so a
+    hash-renamed file's new name would never get reflected in that
+    reference (a plain build_dir/assets/ copy gets hash-renamed by `slidev
+    build` while the rendered page keeps requesting the original, un-hashed
+    filename, producing a 404 in the exported deck).
+
+    Basename collisions between distinct source paths are disambiguated
+    deterministically by first-appearance order in `images` (not filesystem
+    iteration order, which isn't guaranteed stable): the second distinct
+    source sharing a basename becomes "name-2.ext", the third "name-3.ext",
+    etc. A repeated identical `src` is copied once and reused.
+    """
+    assets_dir = build_dir / "public" / "assets"
+    assets_dir.mkdir(parents=True, exist_ok=True)
+
+    mapping: dict[str, str] = {}
+    next_suffix: dict[str, int] = {}  # basename -> next collision suffix
+
+    for image in images:
+        src = image.src
+        if src in mapping:
+            continue
+
+        resolved = resolve_image_path(article, image)
+        if not resolved.exists():
+            raise FileNotFoundError(
+                f"Image not found: '{src}' (referenced in {article.source_path.name}, "
+                f"resolved to {resolved})"
+            )
+        basename = resolved.name
+
+        if basename not in next_suffix:
+            next_suffix[basename] = 1
+            dest_name = basename
+        else:
+            next_suffix[basename] += 1
+            dest_name = f"{resolved.stem}-{next_suffix[basename]}{resolved.suffix}"
+
+        _place_image(resolved, assets_dir / dest_name, max_image_dimension)
+        mapping[src] = f"/assets/{dest_name}"
+
+    return mapping

astro_slidev-0.1.0/src/astro_slidev/cli.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""CLI entrypoint for astro-slidev.
+
+    astro-slidev build <path-or-slug> [--out DIR] [--config FILE]
+    astro-slidev build                 # no post given -> pick interactively
+
+Only `build` writes the deck's output-directory path to stdout (and
+*only* that — everything else goes to stderr), so it composes cleanly with
+shell capture: `slidev dev "$(astro-slidev build my-post)/slide.md"`.
+
+The interactive picker runs in-process (not a separate subcommand whose
+output you'd capture) deliberately: prompt_toolkit falls back to a
+non-interactive plain-text renderer whenever its stdout isn't a real TTY
+(confirmed via prompt_toolkit's own `create_output`), which is exactly what
+capturing a *separate* pick step's stdout would trigger. Picking and
+building in the same process sidesteps that: the interactive UI runs against
+a real, unredirected terminal, and only the final build directory — printed
+after the picker has already closed — ever goes to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import shutil
+import sys
+from pathlib import Path
+
+from .assets import collect_images, copy_assets
+from .config import DEFAULT_CONFIG_PATH, SlidesConfig
+from .models.slide import ImageSlide
+from .parser.markdown_parser import parse_article
+from .planner.planner import plan_deck
+from .renderer.slidev_renderer import render_deck
+from .slug import slug_from_filename
+
+
+def _log(*args) -> None:
+    print(*args, file=sys.stderr)
+
+
+def _resolve_config_path(root: Path, override: Path | None) -> Path:
+    if override is not None:
+        return override
+    project_config = root / "slides.config.yaml"
+    return project_config if project_config.exists() else DEFAULT_CONFIG_PATH
+
+
+def _candidate_posts(root: Path, content_dirs: list[str]) -> list[Path]:
+    posts: list[Path] = []
+    for rel in content_dirs:
+        base = root / rel
+        if base.exists():
+            posts.extend(sorted(base.rglob("*.md")))
+            posts.extend(sorted(base.rglob("*.mdx")))
+    return posts
+
+
+def _relative_slug(post: Path, root: Path, content_dirs: list[str]) -> str:
+    """Folder-relative slug, e.g. 'my-series/my-post' (series folder kept,
+    numeric ordering prefix and extension stripped).
+    """
+    for rel in content_dirs:
+        base = root / rel
+        try:
+            rel_path = post.relative_to(base)
+        except ValueError:
+            continue
+        parts = list(rel_path.parts[:-1]) + [slug_from_filename(rel_path.parts[-1])]
+        return "/".join(parts)
+    return slug_from_filename(post.name)
+
+
+def resolve_post_path(arg: str, root: Path, content_dirs: list[str]) -> Path:
+    """Accepts an absolute path, a path relative to `root`, or a bare/
+    folder-relative slug (with or without a numeric ordering prefix, with or
+    without the extension), resolved against `content_dirs`.
+    """
+    candidate = Path(arg)
+    if candidate.is_absolute() and candidate.exists():
+        return candidate
+    if (root / arg).exists():
+        return (root / arg).resolve()
+
+    norm_arg = arg.strip("/")
+    parts = norm_arg.split("/")
+    parts[-1] = slug_from_filename(parts[-1])
+    norm_arg = "/".join(parts)
+
+    posts = _candidate_posts(root, content_dirs)
+    if not posts:
+        raise SystemExit(f"No posts found under {', '.join(content_dirs)} in {root}")
+
+    exact_relative = [p for p in posts if _relative_slug(p, root, content_dirs) == norm_arg]
+    if len(exact_relative) == 1:
+        return exact_relative[0]
+
+    bare = parts[-1]
+    bare_matches = [p for p in posts if slug_from_filename(p.name) == bare]
+    if len(bare_matches) == 1:
+        return bare_matches[0]
+    if len(bare_matches) > 1:
+        options = "\n".join(f"  - {_relative_slug(p, root, content_dirs)}" for p in bare_matches)
+        raise SystemExit(f"'{arg}' matches multiple posts; qualify with the series folder:\n{options}")
+
+    all_slugs = [_relative_slug(p, root, content_dirs) for p in posts]
+    close = difflib.get_close_matches(norm_arg, all_slugs, n=5)
+    hint = ("\nClosest matches:\n" + "\n".join(f"  - {c}" for c in close)) if close else ""
+    raise SystemExit(f"No post found matching '{arg}'.{hint}")
+
+
+def build(post_path: Path, config: SlidesConfig, out_dir: Path) -> Path:
+    """Parses, plans, and renders `post_path` into `out_dir/<slug>/`."""
+    _log(f"Parsing {post_path}...")
+    article = parse_article(post_path)
+
+    _log("Planning deck...")
+    slides = plan_deck(article, config)
+
+    build_dir = out_dir / article.slug
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
+    build_dir.mkdir(parents=True)
+
+    package_dir = Path(__file__).resolve().parent
+    shutil.copy2(package_dir / "global-bottom.vue", build_dir / "global-bottom.vue")
+
+    styles_dir = build_dir / "styles"
+    styles_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(package_dir / "styles" / "index.css", styles_dir / "index.css")
+
+    images = collect_images(article.sections)
+    if images:
+        _log(f"Copying {len(images)} image(s)...")
+        mapping = copy_assets(article, images, build_dir, config.max_image_dimension)
+        for slide in slides:
+            if isinstance(slide, ImageSlide) and slide.src in mapping:
+                slide.src = mapping[slide.src]
+
+        layouts_dir = build_dir / "layouts"
+        layouts_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(package_dir / "layouts" / "image-caption.vue", layouts_dir / "image-caption.vue")
+
+    _log("Rendering Slidev markdown...")
+    deck_md = render_deck(article, slides, config)
+    (build_dir / "slide.md").write_text(deck_md, encoding="utf-8")
+    _log(f"{len(slides)} slides -> {build_dir / 'slide.md'}")
+
+    return build_dir
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    config = SlidesConfig.load(_resolve_config_path(root, args.config))
+    out_dir = args.out or (root / ".astro-slidev-build")
+
+    if args.post:
+        try:
+            post_path = resolve_post_path(args.post, root, config.content_dirs)
+        except (ValueError, FileNotFoundError) as e:
+            _log(f"Error: {e}")
+            return 1
+    else:
+        from .pick import pick_post  # deferred: questionary only needed for this path
+
+        _log("No post specified — pick one:")
+        chosen = pick_post(root, config.content_dirs)
+        if chosen is None:
+            _log("No post selected. Aborting.")
+            return 130
+        post_path = chosen
+
+    try:
+        build_dir = build(post_path, config, out_dir)
+    except (ValueError, FileNotFoundError) as e:
+        _log(f"Error: {e}")
+        return 1
+
+    print(build_dir)
+    _log()
+    _log("Done. Next, preview or export it with Slidev:")
+    _log(f"  npx @slidev/cli dev {build_dir}/slide.md")
+    _log(f"  npx @slidev/cli build {build_dir}/slide.md --out <target-dir>")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="astro-slidev",
+        description="Turn an Astro content-collection post into a Slidev presentation deck.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    build_parser = sub.add_parser("build", help="Generate a Slidev deck from a post")
+    build_parser.add_argument(
+        "post",
+        nargs="?",
+        default=None,
+        help="Path or slug of the post, e.g. my-series/my-post. Omit to pick interactively.",
+    )
+    build_parser.add_argument("--config", type=Path, default=None, help="Path to a slides.config.yaml override")
+    build_parser.add_argument(
+        "--out", type=Path, default=None, help="Output directory (default: .astro-slidev-build/ in the cwd)"
+    )
+    build_parser.set_defaults(func=_cmd_build)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())