astro-slidev 0.3.0

Turn an Astro content-collection blog post into a Slidev presentation deck — deterministic, no LLM.

astro-slidev

Turn an Astro content-collection blog post into a Slidev 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.

pip install astro-slidev
cd my-astro-project
astro-slidev dev src/content/blog/my-post.md
# generates the deck and opens a live-reloading preview at http://localhost:3030

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.

Prerequisites

• Python 3.10+ — astro-slidev itself is a pure-Python CLI.
• An existing Astro project with a content collection — e.g. posts as Markdown files under src/content/blog/, each with frontmatter. This is what you point astro-slidev at; it never modifies your project, only reads a post and writes its output to a separate directory.
• Node.js — needed the moment you want to actually preview or export a deck, since Slidev itself is a Node/Vite tool. dev/export will use @slidev/cli from your project's own node_modules if it's already a devDependency there, or fall back to npx (which fetches it on the fly) otherwise. Not required just to pip install or run astro-slidev build.

Installation

Install it once, globally on your machine — it's a standalone CLI tool, not a per-project dependency, so pipx (or pip install --user) is the right way to install it:

pipx install astro-slidev

No Node packages to add to your Astro project's package.json, no config file required to get started.

Quickstart: using it in an Astro project

Starting from an existing Astro project with a content collection (e.g. src/content/blog/my-post.md):

# 1. Install the CLI once, globally (not a project dependency)
pipx install astro-slidev

# 2. From your Astro project's root, generate + preview a deck for one post
cd my-astro-project
astro-slidev dev src/content/blog/my-post.md
# opens a live-reloading preview at http://localhost:3030

# 3. When you're happy with it, export a static build to share/host
astro-slidev export src/content/blog/my-post.md
# -> dist/slides/my-post/index.html

Don't know the exact path offhand? Run astro-slidev dev (or export) with no post argument and it'll ask you interactively (series, then post) instead of making you type the path.

Usage

# Generate + launch Slidev's live-reloading dev server
astro-slidev dev src/content/blog/my-post.md
astro-slidev dev my-post          # bare slug also resolves against content_dirs
astro-slidev dev                  # no post given -> pick one interactively

# Generate + export a static, hostable build
astro-slidev export my-post
astro-slidev export my-post --dest public/slides   # -> public/slides/my-post/ (default base: dist/slides)

# Generate only — markdown/assets, no Slidev invocation at all (for CI or
# a completely custom pipeline; the printed path is the only stdout output,
# so it composes with shell capture)
astro-slidev build my-post --out dist/deck --config ./my-slides.yaml

dev and export handle every Slidev invocation detail internally — locating @slidev/cli (your project's local install, or npx as a fallback), the working-directory/--base quirks Slidev's asset resolution needs, all of it. There's nothing to wire up in your own project beyond installing astro-slidev.

Wiring up a permanent dev/build command

For a standing pnpm slides / npm run slides instead of typing the full command each time, add this to your package.json — no shell scripting needed:

{
  "scripts": {
    "slides": "astro-slidev dev",
    "slides:build": "astro-slidev export"
  }
}

pnpm slides                    # no post given -> interactive series/post picker
pnpm slides -- my-post         # dev server for a specific post
pnpm slides:build -- my-post   # static export for a specific post

pnpm forwards a literal -- as an argument when you run pnpm slides -- my-post (npm strips it instead) — astro-slidev's argument parser already treats a standalone -- as the conventional "end of options" marker and discards it either way, so both package managers work with the same script definition.

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 for the full set of defaults with comments.

Key	Default	What it controls
content_dirs	auto-detected	Where the interactive picker looks, and where a bare slug resolves against. Unset by default: auto-detects src/content/blog, or every subdirectory of src/content/ if that doesn't exist — most projects need zero config here. Set explicitly if discovery picks the wrong thing, or for a multi-locale project (e.g. ["src/content/blog", "src/content/blog-fr"]).
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.

Contributing to astro-slidev itself

This is about hacking on the astro-slidev package's own source — not running slides in dev mode (see Usage above for astro-slidev dev).

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.