# ADR 058: Project Pitch Decks
- HTML version: https://robbiepalmer.me/projects/personal-site/adrs/058-project-pitch-decks
- Project: Personal Site (https://robbiepalmer.me/projects/personal-site.md)
- Status: Proposed
- Date: 2026-08-30
## Summary
Add an optional, project-local pitch deck to project pages. Authors will write each deck in MDX and render it with
[reveal.js 6](https://revealjs.com/). The spike will start with the official
[`@revealjs/react` package](https://revealjs.com/react/) and connect it to the site's components and Tailwind tokens.
If the published package gets in the way, vendor and cut down the relevant source.
The project page will embed the deck as a first-class tab. A separate deck route will support focused viewing,
deep links, speaker notes, fullscreen presentation, scroll view, and browser PDF export. The same source will
also produce a plain-Markdown transcript.
Take [Slidev](https://github.com/slidevjs/slidev) as the product reference for Markdown-first authoring, layouts,
framework components, presenter tools, and static hosting. Implement that experience inside the existing React and
Next.js application instead of adding Vue, UnoCSS, and a second Vite application.
Accept this ADR only after a one-deck spike proves reveal.js and its React integration against the site's Next.js
static export, React 19 lifecycle, MDX renderer, responsive layout, and Markdown-twin generation.
## Context
Project pages currently combine different kinds of document:
* product requirements and user stories;
* market and competitor analysis;
* implementation status;
* interactive design prototypes; and
* linked architecture decisions.
That material works as a reference, but it makes a poor opening explanation. A project pitch deck can tell a
shorter story: the problem, the audience, the insight, the proposed product, evidence, design, technical choices,
and current result. Keep the detailed project overview and ADRs available instead of compressing them into slides.
The recipe-site project already proves that project MDX can embed an interactive React component. Its
`DesignEmbed` uses an iframe because the design is a self-contained prototype. A deck is different. Its text,
links, diagrams, and images belong to the project's content and should remain readable, indexable, themeable, and
available in the site's `.md` twin.
### Existing constraints
The chosen design must fit these existing decisions and implementation details:
* The site uses Next.js 15, React 19, TypeScript, and static export to Cloudflare Pages.
* Project content is MDX loaded and validated at build time.
* The MDX renderer already supports React components, Mermaid, Shiki-backed code blocks, responsive images, and
GitHub Flavored Markdown.
* Major pages have agent-readable Markdown twins and appear in `/llms.txt`.
* The visual system uses Tailwind CSS and local components. A deck should look like part of the site.
* Embla Carousel is already installed, but the site does not yet have presentation state, speaker notes, overview
mode, deep linking, or print-to-PDF behavior.
* A project can have no deck. Existing project URLs and content files must remain valid.
### What Slidev gets right
Slidev is the clearest reference implementation for the desired authoring experience. Its documented feature set
includes Markdown, themes, embedded framework components, presenter mode, drawing, Mermaid, code highlighting,
recording, and PDF, PNG, and PPTX export. It can also build one or more decks as static SPAs under a configured
base path. See the [Slidev repository](https://github.com/slidevjs/slidev),
[hosting guide](https://sli.dev/guide/hosting.html), and [export guide](https://sli.dev/guide/exporting.html).
Slidev's documented runtime uses Vue 3, Vite, UnoCSS, VueUse, and Vue components. Running that runtime here would
create a second client framework, build pipeline, theme system, component model, and development server. Embedding
the resulting SPA in an iframe would also separate the deck from the page DOM and the existing Markdown-twin
pipeline. Its source remains useful, especially the parser and presentation behavior that do not depend on Vue.
## Decision
### Use reveal.js core and try its official React package first
Use `reveal.js` 6 as the browser presentation engine. Start the spike with `@revealjs/react` as a normal dependency.
Keep the site's deck components thin so they can wrap the package without exposing its API throughout the content.
Vendor and prune the wrapper only if the published package cannot meet the requirements cleanly.
reveal.js already implements the version-one browser behavior:
* embedded decks with keyboard handling limited to a focused deck;
* touch and keyboard navigation;
* URL hashes and direct slide links;
* fragments and code line stepping;
* overview, fullscreen, and speaker views;
* a mobile-oriented scroll view;
* browser PDF export; and
* a plugin API if a later deck needs math or another specialist feature.
The [official React integration](https://revealjs.com/react/) provides tested lifecycle handling and typed `Deck`,
`Slide`, `Stack`, `Fragment`, and `Code` components. Its production source is about 1,400 lines, with another 1,300
lines of tests. Try that implementation unchanged before taking ownership of it. If its generic Markdown, code,
stack, configuration, or styling paths cause integration problems, the source is small enough to copy, prune, and
adapt to the project's component API.
The embedded deck will use at least this configuration:
```tsx
{slides}
```
The [reveal.js configuration reference](https://revealjs.com/config/) explicitly supports embedded mode,
focus-scoped keyboard shortcuts, touch navigation, URL state, media autoplay control, and PDF settings.
Do not use the reveal.js Markdown plugin. The site will continue to compile MDX with its existing remark and
rehype pipeline, then map the generated slide groups to the React integration. The existing pipeline will continue
to handle links, image processing, Mermaid, Shiki themes, and agent-readable conversion.
### Keep one optional deck beside each project
A project with a pitch deck will add this file:
```text
ui/content/projects//pitch.mdx
```
The file will have deck metadata in frontmatter and use root-level thematic breaks as slide boundaries:
```mdx
---
title: "Recipe Site pitch"
description: "A cooking product built around trusted use, not star ratings"
---
# Recipe Site
Recipes improve when cooking behavior can travel with them.
---
## The problem
Collections, planning, shopping, and cooking history live in separate tools.
---
## The product
```
A pitch-only remark plugin will group root nodes between thematic breaks into standard `mdxJsxFlowElement` nodes
named `PitchSlide`. It will run after MDX parsing and only in the pitch-deck compilation pipeline. Ordinary project
MDX will not register it. Using standard MDX nodes avoids adding a custom mdast node type that another compiler or
serializer would need to understand.
The plugin will split only on root-level `thematicBreak` nodes. A `---` inside a fenced code block or JSX child
stays inside its existing node and cannot become a slide boundary. Inside `pitch.mdx`, a root-level thematic break
always separates slides. Use another visual separator inside a slide.
Transcript conversion takes a separate branch before slide grouping. It removes each complete `PitchNotes` node,
then passes the remaining, ungrouped MDX through `mdxToAgentMarkdown`. Neither `replaceMdxNodes` nor the Markdown
serializer will receive deck-only slide nodes.
MDX components may opt into layout or presentation behavior where plain Markdown is insufficient:
```mdx
## Evidence
The detailed analysis remains linked from the slide.
Explain why repeated cooking is stronger evidence than a saved recipe.
```
`PitchNotes` will render an `