# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

An mdbook preprocessor (`mdbook-slides`) that enables slide presentations within mdbook. A single markdown file marked with `slides: true` in YAML frontmatter renders as an interactive slideshow, while appearing as a single entry in the sidebar. After the slideshow, navigation continues to the next page.

**Key constraint:** Zero external dependencies — no CDN, no JavaScript frameworks. The slideshow is pure HTML/CSS/JS generated by the Rust preprocessor.

## Architecture

The Rust preprocessor handles all markdown-to-slides conversion at build time:
1. Detects `slides: true` in YAML frontmatter
2. Splits markdown on `---` separators into individual slides
3. Strips speaker notes (`Note:` / `Notes:` blocks)
4. Renders each slide's markdown to HTML via pulldown-cmark
5. Wraps in a slideshow container with ~30 lines of vanilla JS

## Project Structure

```
Cargo.toml                  # Binary: mdbook-slides
src/
  main.rs                   # CLI: stdin/stdout protocol, `supports`, `install` subcommands
  lib.rs                    # Preprocessor trait impl, chapter iteration
  frontmatter.rs            # YAML frontmatter parser (detect slides: true)
  html_template.rs          # Slide splitting, markdown rendering, HTML generation
  install.rs                # `install` subcommand: write assets, update book.toml
assets/
  slides.css                # Slideshow layout and styling
  slides-print.css          # Print/PDF: landscape slides, portrait chapters
tests/
  integration.rs            # End-to-end with Book structs
test-book/                  # Manual test book (not part of cargo tests)
```

## Build & Test

```sh
cargo build                 # Compile
cargo test                  # Run all unit + integration tests
```

To manually test with the test book:
```sh
cd test-book && mdbook build    # Requires mdbook installed
cd test-book && mdbook serve    # Live preview at localhost:3000
```

## Key Design Details

- Output is pure HTML blocks (starts with `<div>`) so mdbook's markdown renderer passes it through unchanged
- The `<div>` starts a CommonMark type-6 HTML block — **no blank lines allowed** in the div section or mdbook will break it. Blank lines in rendered slide HTML are replaced with `<!-- -->` comments. The `<script>` block follows after a blank line separator, starting its own type-1 block where blank lines are fine.
- mdbook's chapter navigation arrows (`.nav-chapters`) are removed on slides pages; their URLs are saved for boundary navigation
- Direction-aware entry: `document.referrer` is compared against the next chapter URL to detect backward navigation and start from the last slide
- CSS assets are embedded in the binary via `include_str!()` and written by the `install` subcommand

## PDF / Print Support

Ships `slides-print.css` (included via `[output.html.additional-css]`) that uses CSS named pages (`page: slide` on `.slides-container`) to render slides as landscape while keeping other content portrait. The mdbook chapter-break div before slides is hidden via `:has(+ .slides-container)` to prevent blank pages.
