Skip to content
Public template

About

AI-assisted Slidev workspace template for building, validating, and publishing presentation decks as code.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Slides

Deploy Slides Release Package License: MIT Version PRs Welcome Slidev

Agent-ready Slidev workspace for building, validating, versioning, and publishing reusable presentation decks.

This repository is designed for an agent role called slides-builder. slides-builder turns a user prompt into a clean deck: it asks for missing critical context, writes a local brief, reuses the component catalog, searches for appropriate image assets when a slide needs them, validates the result, and leaves the deck ready to build, export, deploy, or release. When a defect is found and fixed, the agent records the reusable lesson in the narrowest durable spec, skill, doc, template, or validator so future decks do not repeat it.

Who This Is For

  • Speakers who want presentations as code.
  • AI agents that need clear rules instead of ad-hoc slide generation.
  • Teams that want reusable components, styles, speaker data, and publishing workflows across decks.

Human entry point: this README. Agent entry point: AGENTS.md and .agents/skills/.

Pull requests are welcome. See CONTRIBUTING.md for the quality gates and PR flow.

Repository Structure

decks/
  github-enterprise-platform/
    slides.md
    components/
    public/
      media/
  _template/
    slides.md
    components/
    data/
    public/
      media/
data/
  speaker/
    README.md
    speaker.json
    person.js
    linkedin-qr.svg
  person.js              # compatibility re-export
docs/
  adr/
  component-catalog.md
  deck-brief-template.md
  deck-generation-workflow.md
  new-deck-agent-guide.md
  release-workflow.md
  slide-guidelines.md
  style-catalog.md
shared/
  components/
  styles/
    palettes.css
    theme.css
scripts/
  deck.mjs
  release.mjs
  • decks/<slug>/slides.md: main deck entry point.
  • decks/<slug>/public/media/: images, videos, GIFs, screenshots, logos, and deck-owned assets.
  • decks/<slug>/components/: deck-owned Vue components and wrappers.
  • data/speaker/: global speaker data and shared personal assets.
  • shared/components/: reusable data-driven Vue components.
  • shared/styles/theme.css: shared visual system.
  • shared/styles/palettes.css: reusable deck palettes.
  • shared/public/favicon.svg: canonical project favicon copied into every generated home and deck.
  • docs/: human and agent documentation.
  • .agents/skills/: open-standard, vendor-neutral reusable workflows for agents.
  • .github/agents/slides-builder.agent.md: Copilot-compatible adapter for the canonical slides-builder role.

Available Decks

Deck Purpose Command
github-enterprise-platform Main talk about GitHub as an enterprise platform. make dev DECK=github-enterprise-platform
intro-devops-es Spanish introduction to DevOps, DevSecOps, Platform Engineering, and learning path. make dev DECK=intro-devops-es
platform-engineering-that-teams-actually-adopt Internal platform engineering adoption and operating-model talk. make dev DECK=platform-engineering-that-teams-actually-adopt
component-showcase Reference deck for the current component and style catalog. make dev DECK=component-showcase

decks/_template/ is not a finished talk. It is a clean starting point with lorem ipsum, local wrappers, and minimal examples.

Work With Slides-builder

Give slides-builder the talk objective, audience, duration, tone, constraints, required points, available assets, and desired visual direction. If critical information is missing, the agent must ask all known clarification questions before execution starts, during triage/plan.

Recommended flow:

Triage -> Questions -> Intake -> Brief -> Plan -> Tasks -> Implement -> Validate -> Learn -> Handoff

All known clarification questions belong in Triage, Questions, or Plan before execution starts. After implementation begins, the agent should proceed from documented assumptions instead of pausing for new preference questions, unless a genuinely new blocker appears.

Example Prompt

When the prompt is executed from this repository, AGENTS.md and the project skills already define how the agent must work. The user prompt should focus on the presentation itself. Copy and adapt this example:

Create a presentation titled "Platform Engineering That Teams Actually Adopt".

Audience: engineering managers, platform engineers, and senior developers.
Audience level: intermediate.
Duration: 30 minutes.
Event context: an internal engineering conference where teams are evaluating
whether to invest in a platform organization.

Goal: attendees should leave with a practical operating model for building,
adopting, and measuring an internal developer platform.

Core message: a platform succeeds when teams choose to use it, not merely when
the organization deploys more tools.

The presentation must cover:
- the difference between a platform and a collection of tools,
- product thinking and developer experience,
- golden paths and self-service workflows,
- governance and security without unnecessary friction,
- adoption and outcome metrics,
- a phased implementation roadmap.

Tone: practical, candid, and executive-friendly. Use concrete examples and
delivery trade-offs. Avoid marketing language and beginner-level definitions.

Presentation constraints:
- reserve the final 5 minutes for questions,
- do not depend on a live demo,
- keep product references vendor-neutral,
- include a concise closing takeaway and recommended next steps.

Available material: I do not have images or diagrams yet. I can provide the
event logo later if needed.

Visual preference: a light, modern, editorial style with restrained motion.
Favor diagrams, one clear data visualization, and a few strong images over
dense text or dashboard-like slides.

Every new deck must have decks/<slug>/deck.brief.md created from docs/deck-brief-template.md. The brief is the source of truth for requirements, assumptions, asset plan, visual mode, and validation.

Agent Discovery

  • .agents/skills/ is the canonical project skill location and is discovered directly by Agent Skills-compatible tools, including GitHub Copilot.
  • .github/agents/slides-builder.agent.md exposes the slides-builder custom agent to GitHub Copilot CLI and supported Copilot surfaces.
  • .github/copilot-instructions.md is a thin Copilot entry point; AGENTS.md remains the canonical repository specification.
  • Run npm run check:agent to validate all discovery assets.
  • Restart Copilot CLI after pulling changes so it reloads project agents and skills, then select slides-builder with /agent or --agent slides-builder.

Required Prompt Inputs

A useful prompt should include:

  • topic or title,
  • audience and audience level,
  • duration,
  • desired outcome,
  • required points,
  • tone and context,
  • constraints,
  • available assets,
  • visual background mode: light, dark, or black/keynote.

If only non-critical details are missing, such as slug, palette, or suggested assets, the agent may infer them and record the assumption in the brief.

Every deck must include a title/cover slide, a data-driven speaker profile slide, and a final close/Q&A slide.

For new decks or substantial visual changes, visual validation must inspect every slide and visible click/state at 1440x900. Small isolated edits must inspect every changed slide plus adjacent or risky slides.

Install

npm install

Or:

make install

Daily Commands

make list
make dev DECK=github-enterprise-platform
make build DECK=github-enterprise-platform
make check DECK=github-enterprise-platform
make build-all
make pdf DECK=github-enterprise-platform
make pptx DECK=github-enterprise-platform
npm run check:agent

Equivalent npm commands:

npm run list
npm run dev -- github-enterprise-platform
npm run build -- github-enterprise-platform
npm run build:all
npm run export:pdf -- github-enterprise-platform
npm run export:pptx -- github-enterprise-platform

make dev validates the requested deck, accepts an unambiguous close typo, and frees the requested PORT if another process is listening there.

PPTX export is a static delivery format. Slidev exports PPTX slides as images, so native PowerPoint click animations are not preserved. For live click-driven motion, use the hosted Slidev web deck. For PPTX handoff, model click steps as separate Slidev click states or explicit slides. See docs/pptx-export-limits.md.

Versioning And Release

The workspace uses SemVer. Version 1.0.0 is the first stable release of the slides-builder workspace.

Prepare a release:

npm run release:prepare -- 1.0.0
make release-check VERSION=1.0.0
make build-all

After committing and pushing the version change, run the Release Package workflow with version = 1.0.0. The workflow validates the repo, creates the annotated tag v1.0.0, creates slides-builder-1.0.0.tgz, and publishes a GitHub Release.

Details:

Deployment

The Deploy Slides workflow publishes GitHub Pages:

  • target = all: publish every deck under dist/<deck>/.
  • target = <slug>: publish one deck.
  • target = custom: provide a deck slug manually.

Before the first deployment, enable GitHub Pages in Settings > Pages and set the source to GitHub Actions. The workflow does not try to create the Pages site because some repository or organization policies block that call for GITHUB_TOKEN.

The generated home at dist/index.html renders deck cards with preview, title, and description from each deck frontmatter.

The production workflow targets the custom domain https://slides.0vas.com/. It builds the site index at /, each deck at /<deck>/. The domain itself remains configured in Settings > Pages; GitHub ignores CNAME files when Pages uses a custom Actions workflow. Local builds keep the GitHub project-site prefix /slides/ by default. To reproduce the custom-domain build locally, run:

SITE_BASE_PATH=/ npm run build:all

BASE_PATH remains available as an exact per-deck override for exceptional builds.

Media And Data Rules

  • Deck-owned media lives in decks/<slug>/public/media/.
  • Reference public assets as media/<file> from Markdown or props.
  • From Vue components, build public asset paths with import.meta.env.BASE_URL.
  • Stable speaker data and shared personal assets live in data/speaker/.
  • Deck-specific speaker overrides live in decks/<slug>/data/speaker.js.
  • When a slide needs an image, search SVG Repo, Pexels, Unsplash, Pixabay, or similar reputable free-media sources as part of the slide implementation. Download assets locally, choose distinct images for distinct slide roles, and record source/license notes.

Components

Reusable components live in shared/components/. Slidev auto-imports only deck-local components, so use a thin wrapper under decks/<slug>/components/ when a deck needs a shared component.

Current shared components include:

Component Primary Use
SpeakerProfile Data-driven speaker intro with QR and public profiles.
TypingTitle Clean title reveal for covers and section breaks.
PlatformMap Stages, domains, or transformation maps.
EnterpriseTopology Compact enterprise dependency map.
GovernanceGrid 2x2 governance or operating model grid.
SecurityRadar Capability, risk, or posture radar.
MaturityCurve Maturity stages and decisions.
GraphDiagram SVG graph of relationships.
SequenceDiagram Actor/message sequence view.
MermaidDiagram Styled Mermaid wrapper for curated syntax.
MermaidSyntaxCatalog Mermaid syntax decision map.
MermaidJourney Mermaid user journey preset.
MermaidRoadmap Mermaid timeline preset.
MermaidQuadrant Mermaid quadrant chart preset.
EChart Animated ECharts wrapper for charts and dynamic diagrams.
MediaFrame Image, video, GIF, or media placeholder frame.
StylePalette Visual palette reference.
BrowserMockup Generic product or dashboard mockup.
MetricStrip Large KPI row.
ComparisonTable Visual comparison table.
DecisionMatrix 2x2 decision matrix.
HierarchyTree Root and branch hierarchy.
IconGrid Compact icon/concept grid.
ShapeSystem Reusable 2D shape language.
TimelineFlow Horizontal milestone timeline.
SwimlaneFlow Role or system swimlanes.
PyramidDiagram Layered pyramid.
VennDiagram Three-domain intersection.
CalloutStack Stack of insights, risks, or decisions.
QuoteFrame Editorial quote or insight.
ArchitectureLayers Horizontal architecture layers.
Shape3DStage Three.js 3D stage.

See docs/component-catalog.md for usage rules.

Styles And Palettes

Decks choose a palette through class and defaults.class:

---
class: my-deck palette-crystal
defaults:
  class: my-deck palette-crystal
---

palette-crystal is the recommended default for new decks, templates, and the showcase. Dark and black/keynote modes must be deliberate and recorded in the deck brief.

See docs/style-catalog.md.

Operational Documentation

Maintenance rule: when a component, palette, workflow, or public contract changes, update the matching README, docs, showcase, and validation commands in the same commit.

About

AI-assisted Slidev workspace template for building, validating, and publishing presentation decks as code.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages