Related Pages

Related topics: Deck JSON Schema, Layouts, and Themes, Rendering, Export, and Import Pipeline, Agent Integration, MCP Tools, and Deck Design Judge

Overview and Repository Architecture

presentation-md is a Markdown-driven presentation toolchain packaged as a pnpm monorepo. It centers on authoring slides in Markdown and rendering them through a layered set of packages that progressively add export, rendering, and skill-pack distribution capabilities. The repository combines a renderer, an exporter, and a separate "skill pack" that integrates with Claude Code through a one-line installer. Source: README.md:1-60

Project Purpose and Scope

The project's purpose is to let authors write slide decks as Markdown while still producing presentation-ready output, including PPTX, with predictable visual behavior. The README documents the toolchain and its headline features, and explicitly advertises deck-design-judge as a carried skill so users can lint and improve slide design during authoring. Source: README.md:1-60

Project governance, contribution flow, and licensing/attribution are split into dedicated documents so the README stays focused on usage. ATTRIBUTION.md records upstream credits, and CONTRIBUTING.md defines the workflow for outside contributors. Source: ATTRIBUTION.md:1-20, Source: CONTRIBUTING.md:1-40

Monorepo Structure

The repository is structured as a pnpm workspace. The root package.json defines top-level scripts and dev tooling, while pnpm-workspace.yaml enumerates the packages that live inside the workspace. Source: package.json:1-60, Source: pnpm-workspace.yaml:1-20

Published packages visible in the release history include:

Source: CHANGELOG.md:1-40

The renderer and exporter versions are coupled: a recent @presentation-md/[email protected] patch bumped its @presentation-md/export dependency to 1.3.1, indicating that the two packages share an interface that is kept in lock-step. Source: CHANGELOG.md:1-20

Distribution and Skill Pack Pipeline

The distribution story has two tracks. The first is the standard npm release path governed by Changesets, recorded in CHANGELOG.md with patch, minor, and major sections per package. Source: CHANGELOG.md:1-40

The second track is the skill-pack installer for Claude Code. The README documents the command npx @presentation-skill-pack/install claude-code as the way to bring the project into an agent environment. Source: README.md:40-60 Under the hood, this command resolves @presentation-skill-pack/core/skill and copies the files listed in that package's manifest into the agent's working directory. Source: CHANGELOG.md:1-40

The renderer has been actively hardened for visual and security concerns. The 1.2.3 patch introduced local file:// path prefetching for embedded PPTX assets, gated by an allowedRoots confinement, and raised AA contrast for neon, vapor, and loud comparison surfaces as well as the feature grid. Source: CHANGELOG.md:1-20

Known Architectural Gaps

Issue #9 highlights a documentation-versus-implementation gap surfaced during PR #7. The README now lists deck-design-judge as a skill carried by the repo, but the installer's files list in @presentation-skill-pack/core/skill does not yet include it. Source: README.md:46, Source: CHANGELOG.md:1-40

The practical effect is that a user running the documented one-command install will not receive the deck-design-judge files locally, even though the README implies they are part of the skill bundle. Closing this gap requires either expanding the package's files manifest or pruning the README reference so the two stay aligned. Source: README.md:46, Source: CHANGELOG.md:1-40

Contributors addressing this kind of gap are expected to follow the workflow described in CONTRIBUTING.md and to record user-visible changes through the Changesets pipeline so they appear in CHANGELOG.md. Source: CONTRIBUTING.md:1-40, Source: CHANGELOG.md:1-40

Related Pages

Related topics: Overview and Repository Architecture, Rendering, Export, and Import Pipeline

Deck JSON Schema, Layouts, and Themes

The @presentation-md/core package defines the canonical JSON contract for every deck produced in the system. A deck is a single document that combines structural metadata, an ordered list of slides, layout assignments per slide, and an optional theme reference. Two JSON Schema files (deck.schema.json and theme.schema.json) lock the shape of these documents, and two TypeScript validators (validate-deck.ts, validate-theme.ts) enforce them at build/load time before the renderer can consume the artifact. Source: packages/core/SKILL.md and packages/core/deck.schema.json.

Deck Schema

A deck document is a top-level object that must validate against deck.schema.json. It typically carries identifying metadata (title, author, locale), a theme reference, and a slides array. Each slide element embeds a layout identifier plus arbitrary content blocks (titles, bullets, code, images, embeds, grids). The schema enforces required fields, slide ordering, and the union of allowed content block types so downstream tools — including the renderer and the deck-design-judge skill — can rely on a stable shape. Source: packages/core/deck.schema.json.

validate-deck.ts is the runtime gatekeeper: it compiles the schema with a JSON Schema validator, walks the document, and surfaces structured errors (path + reason) rather than throwing. This lets the CLI exit with a non-zero code while still printing a human-readable diagnostic, which is the contract used by CI and by the one-command installer pipeline. Source: packages/core/src/validate-deck.ts.

Layouts

Layouts are first-class named templates referenced from each slide via slide.layout. The renderer ships a small set of built-in layouts (e.g., title, content, section, two-column, quote, blank) and a deck may extend this set through its theme or through inline layout declarations. A layout definition describes the grid (rows/columns), slot names, default typography, and which content block types are accepted in each slot. Because layouts are referenced by string id rather than embedded inline, the same layout can be reused across slides and themes, and the deck-design-judge skill can reason about layout balance across an entire deck. Source: packages/core/SKILL.md.

A slide-level layout override lets a single slide diverge from the deck's default layout while still inheriting theme tokens. This separation — layout (structure) vs. theme (style) — is what enables the same content to be re-skinned without rewriting slide bodies.

Themes

A theme is a separate JSON document validated by theme.schema.json. It defines the visual surface: color tokens (background, foreground, accent, muted, semantic states), typography scales (font families, sizes, weights, line heights), spacing tokens, radii, shadows, and per-layout style overrides. Theme files are resolved relative to the deck via the loader in theme-loader.ts, which supports bundled themes, user-provided themes, and remote theme URLs. Source: packages/core/theme.schema.json and packages/core/src/theme-loader.ts.

validate-theme.ts runs the same compiled-schema pattern as the deck validator, but with stricter requirements on token completeness — a theme that omits a referenced token is rejected rather than silently falling back, which prevents visual drift between the local preview and the rendered output. Source: packages/core/src/validate-theme.ts.

How They Fit Together

The validation pipeline runs in a fixed order: theme load → theme validate → deck validate → render. If any step fails, the artifact never reaches the renderer, and the deck-design-judge skill consumes the same validated document to score layout balance, contrast, and information density. This is why community issue #9 ("Wire deck-design-judge into the npx install pipeline") matters: the skill depends on the schema-stable shape produced by validate-deck.ts, and the installer must ship that file alongside the core skill so on-disk decks can be evaluated offline. Source: packages/core/src/validate-deck.ts and packages/core/src/theme-loader.ts.

In short, the deck schema defines *what* a slide is, layouts define *how* it is arranged, and themes define *what it looks like*. Each layer has its own schema and validator, and the loader sits between the theme layer and the renderer so authors can swap visual identity without touching content.

Related Pages

Related topics: Deck JSON Schema, Layouts, and Themes, Agent Integration, MCP Tools, and Deck Design Judge

Rendering, Export, and Import Pipeline

The presentation-md project ships two parallel renderer implementations — a Node.js package and a Python package — that share a common HTML/CSS/theme surface to convert Markdown slide sources into browser-ready presentation documents. Export and import flows (PPTX embed prefetch, theme catalogs, skill-pack wiring) are layered on top of these renderers through the @presentation-md/render and @presentation-md/export packages.

Renderer Architecture

The pipeline is delivered as a monorepo with three coordinated layers:

The Node CLI surface is defined in cli.ts, which wires commander-style argument parsing into the renderer exposed by index.ts. Source: packages/renderer-node/src/cli.ts:1-120

The Python mirror lives at packages/renderer-python/src/presentation_md_render/cli.py, providing the same command-line ergonomics for environments where Node is unavailable. Source: packages/renderer-python/src/presentation_md_render/cli.py:1-120

Shared Document Surface

Both renderers emit a single HTML document using document.html as the template, styled by base.css, and themed via the structured catalog in theme-surfaces.json.

• document.html declares the slide shell, slide-list containers, and the script tags that hydrate runtime behavior such as keyboard navigation, fragment stepping, and embed rendering.
• base.css provides the design-token baseline: typography scale, layout grid, and the AA-contrast floor that the most recent patch raised for the neon, vapor, and loud themes plus the feature-grid component.
• theme-surfaces.json enumerates every theme (background palette, accent palette, surface treatments) the renderers can apply at build time.

Source: packages/renderer-node/shared/document.html:1-200 Source: packages/renderer-node/shared/base.css:1-400 Source: packages/renderer-node/shared/theme-surfaces.json:1-200

Export Flow (PPTX and Asset Embeds)

Export is handled by @presentation-md/export, which the renderer depends on at runtime. The current @presentation-md/[email protected] patch introduced an embed-prefetch pass:

• Local file:/// PPTX embeds are prefetched before HTML emission so the embedded slide raster is bundled with the rendered output.
• Prefetch is confined to an allowedRoots allow-list, preventing the renderer from reading arbitrary local paths during export.
• The accompanying base.css revisions raise the AA contrast ratio for neon, vapor, loud, and the feature-grid component to keep embedded slides legible.

Source: packages/renderer-node/src/index.ts:1-200 Source: packages/renderer-node/shared/base.css:1-400

Data Flow

flowchart LR
    MD[Markdown source] --> NodeCLI[renderer-node CLI]
    MD --> PyCLI[presentation_md_render CLI]
    NodeCLI --> Index[index.ts renderer]
    PyCLI --> Index
    Index --> Shared[shared/document.html + base.css + theme-surfaces.json]
    Shared --> Export[@presentation-md/export]
    Export --> Prefetch[file:// PPTX prefetch with allowedRoots]
    Prefetch --> Out[Rendered HTML / PPTX bundle]
    Installer[npx @presentation-skill-pack/install] -. gap .-> Judge[deck-design-judge]

Import / Install Pipeline

The skill-pack installer (npx @presentation-skill-pack/install claude-code) is the canonical import path for Claude Code users. It currently resolves only @presentation-skill-pack/core/skill, whose files manifest does not include the deck-design-judge skill that the README documents.

This gap is tracked in community issue #9 ("Wire deck-design-judge into the npx install pipeline"), flagged by Codex on PR #7 against README.md:46. Until the files list in @presentation-skill-pack/core/skill is extended, users who want the design-judge skill must install it manually rather than through the one-command installer.

Source: packages/renderer-node/src/cli.ts:1-120

Known Limitations

• The one-command installer does not yet ship deck-design-judge; manual wiring is required (issue #9).
• Contrast and embed-prefetch behavior are tied to specific @presentation-md/render patch versions — older builds will not enforce allowedRoots confinement on local PPTX embeds, and will not include the raised AA-contrast floor for the affected themes.

Related Pages

Related topics: Overview and Repository Architecture, Rendering, Export, and Import Pipeline

Agent Integration, MCP Tools, and Deck Design Judge

This page documents how presentation-md distributes its agent-side assets (skills, prompts, and tooling hooks) into AI coding agents such as Claude Code and Cursor, and how the deck-design-judge skill is currently split between the main installer and a secondary install script.

1. The `npx` Install Pipeline and `presentation-skill-pack`

The one-command installer advertised in the README is npx @presentation-skill-pack/install claude-code (or …cursor). The implementation lives in packages/install/src/index.ts, which resolves the package @presentation-skill-pack/core/skill and stages its files list into the target agent's configuration directory. The repo ships per-target adapter directories (adapters/claude-code/, adapters/cursor/) that wrap the same core payload and add agent-specific paths and hooks.

Source: packages/install/src/index.ts

2. `deck-design-judge` — A Skill Outside the Core Payload

The README documents deck-design-judge as a skill this repo carries (README.md:46, per issue #9). However, the @presentation-skill-pack/core/skill files list does not currently include the judge skill, so calling npx @presentation-skill-pack/install claude-code alone will not place it on disk. A dedicated install script — adapters/_common/install-judge-skill.sh — exists to fill that gap and must be run separately (or wired into the main installer).

This separation is the root cause of the integration gap tracked in issue #9 — "Wire deck-design-judge into the npx install pipeline", which Codex flagged on PR #7 during review.

Source: adapters/_common/install-judge-skill.sh

3. Per-Agent Adapters

3.1 Claude Code

• Shell entry point: adapters/claude-code/install.sh
• Windows entry point: adapters/claude-code/install.ps1
• Documentation: adapters/claude-code/README.md

These scripts back the claude-code argument of the npm CLI and handle platform-specific staging (POSIX cp/mkdir vs. PowerShell Copy-Item/New-Item).

3.2 Cursor

• Shell entry point: adapters/cursor/install.sh

A parallel adapter targets Cursor's skill/config layout; other agents will follow the same pattern (adapter directory + adapter-specific install script + optional README).

Source: adapters/claude-code/README.md, adapters/cursor/install.sh

4. MCP Tools and Bridge to Renderers

@presentation-md/render v1.2.3 (released alongside @presentation-md/export 1.3.1) introduced file:/ prefetching for PPTX embeds guarded by an allowedRoots confinement, plus raised contrast on the neon/vapor/loud comparison surfaces and the feature grid (23e3a1f). These changes give the agent side a safe primitive — fetching a local PPTX before handing its bytes to a downstream MCP tool — without leaking arbitrary filesystem paths. The install scripts are the on-ramp that makes those MCP-callable surfaces available inside Claude Code and Cursor environments.

Source: @presentation-md/render changelog, change 23e3a1f

5. Known Gap and Workaround

Until #9 is resolved, users must run bash adapters/_common/install-judge-skill.sh (or the equivalent PowerShell path once available) after the npx installer in order to obtain the deck-design-judge skill. Once the core files list is updated to include the judge skill, this manual step should disappear and the unified npx @presentation-skill-pack/install <agent> command will be sufficient.

Source: issue #9 — "Wire deck-design-judge into the npx install pipeline"

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/isatimur/presentation-md/issues/9

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/isatimur/presentation-md

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/isatimur/presentation-md

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/isatimur/presentation-md

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/isatimur/presentation-md

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/isatimur/presentation-md

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/isatimur/presentation-md/issues/8

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/isatimur/presentation-md

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/isatimur/presentation-md

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using presentation-md with real data or production workflows.

• Wire deck-design-judge into the npx install pipeline - github / github_issue
• render_slides.sh: per-slide screenshot fragment-scroll doesn't move the - github / github_issue
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release
• @presentation-md/[email protected] - github / github_release