# slide-spec

slide-spec is a YAML-first static site and presentation tool: you edit YAML, validate, build to `dist/`, and optionally pull metrics from GitHub.

Site: https://docs.slide-spec.dev/

## Start here

- https://docs.slide-spec.dev/quickstart — install path, `init` → validate → build → serve; optional `fetch` with a token.

## Schema (four documents, validated together)

Read in order: site → presentations index → presentation → generated. Field-level rules and required keys live on each page; do not guess shapes from examples alone.

- https://docs.slide-spec.dev/schema/ — how the four files relate.
- https://docs.slide-spec.dev/schema/site — global branding, navigation copy, links, optional `data_sources`.
- https://docs.slide-spec.dev/schema/presentations-index — published presentation list and archive metadata.
- https://docs.slide-spec.dev/schema/presentation — slide list, template ids, authored content blocks.
- https://docs.slide-spec.dev/schema/generated — metrics, releases, contributors, merged PRs; may be hand-authored or produced by `fetch`.

## Templates (slide layouts)

- https://docs.slide-spec.dev/templates/ — index of layouts and how they consume `presentation.yaml` / `generated.yaml`.
- https://docs.slide-spec.dev/templates/hero
- https://docs.slide-spec.dev/templates/agenda
- https://docs.slide-spec.dev/templates/section-list-grid
- https://docs.slide-spec.dev/templates/timeline
- https://docs.slide-spec.dev/templates/progress-timeline
- https://docs.slide-spec.dev/templates/people
- https://docs.slide-spec.dev/templates/metrics-and-links
- https://docs.slide-spec.dev/templates/action-cards
- https://docs.slide-spec.dev/templates/closing

## CLI

- https://docs.slide-spec.dev/cli/ — overview.
- https://docs.slide-spec.dev/cli/init — scaffold a project.
- https://docs.slide-spec.dev/cli/validate — schema check.
- https://docs.slide-spec.dev/cli/build — static output.
- https://docs.slide-spec.dev/cli/serve — build then serve `dist/`.
- https://docs.slide-spec.dev/cli/fetch — populate `generated.yaml` from configured sources (GitHub today).

## Examples

- https://docs.slide-spec.dev/examples/ — how examples relate to the repo fixture.
- https://docs.slide-spec.dev/examples/tutorial-example — end-to-end walkthrough aligned with `docs/fixtures/reference-project/`.
- https://docs.slide-spec.dev/examples/manual-data-example — no GitHub connector; you own `generated.yaml`.

## Connectors

- https://docs.slide-spec.dev/connectors/github — GitHub-backed metrics and configuration for `fetch`.

## Meta / policies

- https://docs.slide-spec.dev/meta/ — docs meta index.
- https://docs.slide-spec.dev/meta/accessibility
- https://docs.slide-spec.dev/meta/ai
- https://docs.slide-spec.dev/meta/supply-chain
- https://docs.slide-spec.dev/meta/agent-assistance

## Facts for implementers

- Validation is strict; match the schema pages for required fields and nesting.
- GitHub is the only built-in `fetch` source today; manual `generated.yaml` is always valid if it matches the schema.
- Published screenshots and the tutorial reference the same validated fixture under `docs/fixtures/reference-project/` in the slide-spec repository.