markdstage

# MarkdStage Markdown is the single source of truth. MarkdStage renders each Markdown fragment between `---` separators as one 1280x720 (16:9) slide, and the CLI renders exactly what the MarkdStage canvas and MarkdStage Desktop render. ## Requirements - Node.js 24 or later. - An installed Microsoft Edge, Google Chrome, or Chromium (never downloaded automatically). - The CLI: `npx @markdstage/markdstage <command>` or `npm install --global @markdstage/markdstage`. ## Recommended authoring workflow 1. Establish the source material, audience, objective, approximate length, theme, required diagrams, and output format. 2. Read only the relevant guidance. Start with `markdstage guide slide-format`, then retrieve `themes`, `custom-themes`, or `architecture-schema` when needed. Before drafting Architecture DSL, read the compact `architecture-schema` contract first; use `architecture-dsl` for advanced behavior. 3. Create the complete deck as one Markdown source file (see `references/slide-format.md`). 4. Validate structure, themes, and Architecture DSL before visual review: `markdstage validate slides.md --json`. Review diagnostic codes, JSON Pointers, and completeness, fix independent issues together, and preserve the same validated content when presenting. Suggestions are never automatic repairs. 5. Use `markdstage slides.md` for live source-backed authoring. It reloads on save without losing the current slide and keeps the last valid deck while a save is incomplete. 6. Check fixed 16:9 output with `markdstage inspect slides.md --json`. Use `--slide <n>` after localized changes and `--fail-on-issues` in CI. 7. Run `markdstage capture slides.md` only after inspection. Without `--pages`, it captures only clipped slides; use `--pages 2,4` for pages whose balance, spacing, or diagrams need visual judgment. 8. Revise Markdown and repeat validation plus targeted inspection until the deck is valid, unclipped, concise, and visually balanced. 9. Deliver from the same source with `markdstage present slides.md`, `markdstage export slides.md --output slides.pdf`, or `markdstage export slides.md --output slides.pptx`. The browser in `markdstage slides.md` starts in viewing mode on the fixed 16:9 output surface. **Output preview** switches to the retained responsive layout. The user can activate the pencil control to switch to the responsive layout and move Architecture elements, then choose **Advanced edit** for the detailed designer. Placement changes save immediately, while the detailed designer saves only when the user selects **Save**. Automatic refresh can be toggled from the same UI without disabling Architecture editing. Never hand-write HTML or CSS for a slide. Fix layout problems by shortening the content or by changing the layout in front matter. Prefer structured validation and layout diagnostics over capturing every slide. ## Archify imports Use an `archify` fence to import an SVG exported by Archify: ````markdown ```archify assets/checkout-architecture.svg ``` ```` The fence contains one local `.svg` path, not JSON or inline SVG. Save the file under Markdown-adjacent or workspace-root `assets/` and omit the leading slash. MarkdStage preserves geometry, applies the deck theme, and exports supported shapes, connectors, and text as editable PowerPoint objects. Re-export in Archify and refresh to update it; the Architecture Editor does not edit imported SVGs. Preview to check import errors; `validate` does not validate imported Archify SVGs. Read `references/slide-format.md` or `markdstage guide slide-format` for the complete path rules and import behavior. ## Commands | Command | Purpose | | --- | --- | | `markdstage` | Open an empty Canvas-equivalent UI and choose Markdown from the workspace. | | `markdstage <file>` | Open the full UI in live slide view with automatic refresh, editing, presenting, and UI export. | | `markdstage present <file> [--watch]` | Open the same full UI in presenter view; `--watch` enables automatic refresh initially. | | `markdstage preview <file> [--watch]` | Open the same full UI in slide view; `--watch` enables automatic refresh initially. | | `markdstage validate <file> [--json]` | Check deck structure, Architecture DSL blocks, and themes. | | `markdstage inspect <file> [--json]` | Report 1280x720 clipping diagnostics for the deck or one slide; use `--fail-on-issues` for quality gates. | | `markdstage capture <file> [--pages 2,4]` | Write 1280x720 PNG files; without `--pages` only clipped slides are captured. | | `markdstage export <file> [--output slides.pdf|slides.pptx]` | Produce a 16:9 PDF or hybrid editable PowerPoint. | | `markdstage guide <topic>` | Print the canonical MarkdStage authoring guide. | Exit codes: `0` success, `1` usage error, `2` deck or input error, `3` no Chromium-based browser, `4` rendering failure, `5` issues found with `--fail-on-issues`. ## References Read the reference that matches the task before writing Markdown: - `references/slide-format.md` — slide fragments, front matter, layouts, Archify SVG imports. - `references/themes.md` — built-in themes. - `references/custom-themes.md` — custom theme authoring and `theme-file`. - `references/theme-schema.md` — custom theme properties. - `references/architecture-dsl.md` — Architecture DSL v1 diagrams. - `references/architecture-schema.md` — Architecture DSL schema summary. - `references/overview.md` — how MarkdStage works. ## Notes for Claude Code Run the CLI through the shell. Presentation servers bind to loopback with an unguessable per-process URL token, and every generated file stays inside the workspace.