Skip to content

alirezarezvani/claude-skills / markdown-html/skills/md-slides

md-slides

Verified

Turn a markdown file into a single-file HTML slide deck with keyboard navigation, presenter notes and print-to-PDF. Use whenever the user wants slides or a presentation from markdown or notes.

scripts/slide_splitter.py

View on GitHub
#!/usr/bin/env python3
"""slide_splitter.py - Split a markdown deck into ordered slides.

Stdlib-only. Accepts three boundary modes:

  --boundary hr     Split on `---` HR lines (the most common convention; what
                    reveal.js / pandoc / Marp / Big all read by default).
  --boundary h1     Split on top-level `# ` headings; each H1 starts a new slide.
  --boundary auto   (default) Pick the better signal automatically:
                      - HR count ≥ 3 → use HR
                      - else H1 count ≥ 5 → use H1
                      - else FAIL — input has no clear slide boundaries

The first slide gets everything from the start of file up to the first boundary.
H1-mode treats the H1 line as part of the slide (it becomes the slide title);
HR-mode does NOT include the `---` line in either slide.

NO LLM CALLS. Pure regex + state machine.

Hard rules (refusals):
  1. 1-slide deck → exit 5 (it's a poster — route to md-document)
  2. Any slide body > 40 source lines → warning printed to stderr (signal-to-
     noise; presenters fail with too much per slide). Soft-fail; renders anyway.
  3. No boundaries detectable in auto mode → exit 6 (route to md-document)

Usage:
    python slide_splitter.py --input deck.md --output slides.json
    python slide_splitter.py --input - --boundary h1
    python slide_splitter.py --sample
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any

HR_RE = re.compile(r"^---\s*$")
H1_RE = re.compile(r"^#\s+(.+?)\s*$")

MAX_SLIDE_LINES = 40  # soft warn above this (signal-to-noise)


def _extract_title(slide_body: list[str]) -> tuple[str, list[str]]:
    """If the first non-blank line is a heading, treat it as the title and
    return (title, body_without_title_line). Otherwise return ('', body)."""
    for i, line in enumerate(slide_body):
        if not line.strip():
            continue
        m = H1_RE.match(line)
        if m:
            return (m.group(1).strip(), slide_body[:i] + slide_body[i + 1:])
        # Also accept H2 as a slide title if the slide has no H1 (common in
        # decks where H1 = whole-deck title and each slide leads with H2)
        m2 = re.match(r"^##\s+(.+?)\s*$", line)
        if m2:
            return (m2.group(1).strip(), slide_body[:i] + slide_body[i + 1:])
        break
    return ("", slide_body)


def _pick_boundary_auto(lines: list[str]) -> str:
    """Pick HR vs H1 based on signal counts. HR wins if ≥3; else H1 if ≥5."""
    hr_count = sum(1 for ln in lines if HR_RE.match(ln))
    h1_count = sum(1 for ln in lines if H1_RE.match(ln))
    if hr_count >= 3:
        return "hr"
    if h1_count >= 5:
        return "h1"
    return ""  # caller treats empty as "no boundary detected"


def split_slides(text: str, boundary: str = "auto") -> dict[str, Any]:
    lines = text.splitlines()

    if boundary == "auto":
        chosen = _pick_boundary_auto(lines)
        if not chosen:
            return {
                "slides": [],
                "boundary": "auto",
                "boundary_used": None,
                "summary": {
                    "total_slides": 0,
                    "max_slide_lines": 0,
                    "over_threshold": [],
                    "error": "no clear slide boundaries (need ≥3 HR or ≥5 H1)",
                },
            }
        boundary = chosen

    raw_groups: list[list[str]] = []
    current: list[str] = []
    boundary_lines: list[int] = []  # source line indices where each slide starts

    if boundary == "hr":
        current_start = 0
        for i, ln in enumerate(lines):
            if HR_RE.match(ln):
                raw_groups.append(current)
                boundary_lines.append(current_start)
                current = []
                current_start = i + 1
                continue
            current.append(ln)
        # Last slide
        raw_groups.append(current)
        boundary_lines.append(current_start)
    elif boundary == "h1":
        current_start = 0
        first_h1_seen = False
        for i, ln in enumerate(lines):
            if H1_RE.match(ln):
                if first_h1_seen:
                    raw_groups.append(current)
                    boundary_lines.append(current_start)
                    current = []
                    current_start = i
                else:
                    # Everything before the first H1 (if non-empty) is the
                    # opening slide; the first H1 starts slide 2.
                    if any(s.strip() for s in current):
                        raw_groups.append(current)
                        boundary_lines.append(0)
                    current = []
                    current_start = i
                    first_h1_seen = True
            current.append(ln)
        if current:
            raw_groups.append(current)
            boundary_lines.append(current_start)
    else:
        return {
            "slides": [],
            "boundary": boundary,
            "boundary_used": boundary,
            "summary": {
                "total_slides": 0,
                "max_slide_lines": 0,
                "over_threshold": [],
                "error": f"unknown --boundary mode: {boundary}",
            },
        }

    # Trim leading/trailing blank lines per slide; drop empty slides
    cleaned: list[dict[str, Any]] = []
    over_threshold: list[int] = []
    max_lines = 0
    for idx, body_lines in enumerate(raw_groups):
        while body_lines and not body_lines[0].strip():
            body_lines = body_lines[1:]
        while body_lines and not body_lines[-1].strip():
            body_lines = body_lines[:-1]
        if not body_lines:
            continue

        title, body_no_title = _extract_title(body_lines)
        line_count = len(body_lines)
        max_lines = max(max_lines, line_count)
        if line_count > MAX_SLIDE_LINES:
            over_threshold.append(idx + 1)

        cleaned.append({
            "slide_number": len(cleaned) + 1,
            "title": title,
            "body_markdown": "\n".join(body_no_title),
            "raw_body_markdown": "\n".join(body_lines),
            "source_line": boundary_lines[idx] if idx < len(boundary_lines) else 0,
            "line_count": line_count,
        })

    return {
        "slides": cleaned,
        "boundary": boundary,
        "boundary_used": boundary,
        "summary": {
            "total_slides": len(cleaned),
            "max_slide_lines": max_lines,
            "over_threshold": over_threshold,
            "max_threshold": MAX_SLIDE_LINES,
        },
    }


SAMPLE_MARKDOWN = """# The Case for Single-File HTML

Why agent-generated artifacts should ship as one .html file.

---

# Three forces converged

- Outputs got longer
- The editing relationship changed (LLM edits, not human)
- The information became spatial

Markdown can't carry any of those three at length.

<!-- notes: This is the framing slide. Start by asking the audience how
  many of them have stopped reading a markdown spec past line 100. -->

---

# What HTML restores

| Dimension | Markdown | HTML |
|-----------|----------|------|
| Hierarchy | Indented `#` | Typography scale |
| Navigation | Linear | Sticky TOC + scrollspy |
| Comparison | Lists | Tables, grids |
| Interaction | None | Search, copy, hover |

<!-- notes: Spend 30 seconds on each row. The hierarchy row is the one
  that lands hardest for engineers. -->

---

# Single-file discipline

- All CSS inline
- All JS inline
- Only externals: Google Fonts + Prism CDN
- Falls back gracefully

> One `.html` file uploads to S3, opens in any browser, attaches to email.

<!-- notes: The shareability point is the easiest sell. Skip the technical
  details unless someone asks. -->

---

# Try it now

Append "as an HTML file" to your next Claude Code prompt.

That's the whole switch.
"""


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    p.add_argument("--input", help="Path to markdown file, or '-' for stdin")
    p.add_argument("--output", help="Path to write JSON output (else stdout)")
    p.add_argument("--boundary", choices=["auto", "hr", "h1"], default="auto",
                   help="Slide boundary mode (default: auto-detect)")
    p.add_argument("--sample", action="store_true",
                   help="Run on a built-in 5-slide deck")
    args = p.parse_args(argv)

    if args.sample:
        text = SAMPLE_MARKDOWN
    elif args.input:
        text = sys.stdin.read() if args.input == "-" else Path(args.input).read_text(encoding="utf-8")
    else:
        p.print_help()
        return 0

    result = split_slides(text, args.boundary)

    # Hard rule: auto mode with no clear boundaries
    if "error" in result["summary"]:
        print(f"refusing: {result['summary']['error']}. "
              f"Add `---` between slides, or use H1 boundaries, or route to md-document.",
              file=sys.stderr)
        return 6

    # Hard rule: single-slide deck is a poster, not a deck
    if result["summary"]["total_slides"] == 1:
        print("refusing: input produces a 1-slide deck — that's a poster. "
              "Route to md-document or add more --- boundaries.",
              file=sys.stderr)
        return 5

    # Soft warn: slides over 40 source lines
    if result["summary"]["over_threshold"]:
        offenders = ", ".join(f"#{n}" for n in result["summary"]["over_threshold"])
        print(f"warning: slides {offenders} exceed {MAX_SLIDE_LINES} source lines "
              f"(signal-to-noise — consider splitting). Rendering anyway.",
              file=sys.stderr)

    payload = json.dumps(result, indent=2)
    if args.output:
        Path(args.output).write_text(payload, encoding="utf-8")
        print(f"wrote {args.output}: {result['summary']['total_slides']} slides "
              f"(boundary={result['boundary_used']}, max_lines={result['summary']['max_slide_lines']})")
    else:
        print(payload)
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
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