[@layout]: ../docs.layout.md

# Build a workshop site

Turn the two pages from [Quickstart](./first-site.guide.md) into a small workshop
with shared navigation, a theme, and a reusable lesson card. Keep `bun run dev`
running as you edit.

---

## 1. Add a shared layout

Create `paths/layouts/site.layout.md`:

```md
<div class="workshop-shell">
  <header>
    <a href="../index.md">Color workshop</a>
  </header>
  <main>
    <x-source-content />
  </main>
  <x-theme-scheme-toggle />
</div>
```

The outlet `<x-source-content />` is where each page's Blocks appear. Select this
layout at the top of `paths/index.md`:

```md
[@layout.default]: ./layouts/site.layout.md

# Color workshop

Learn to build clear, readable color palettes.

[About the workshop](./about.md)
```

Open the home page and follow the About link. Both pages now have the workshop
header and scheme toggle. The root index sets the default for the whole site.
See [Layouts](../site/layouts.reference.md) for page and type overrides.

---

## 2. Add navigation

Create `paths/navigation/site.navigation.md`:

```md
---
label: Workshop
---

- [Home](../index.md)
- [About](../about.md)
```

In `paths/layouts/site.layout.md`, add this import at the top:

```md
[@nav.primary]: ../navigation/site.navigation.md
```

Add the menu inside the header, after the workshop title:

```html
<x-navigation-nav name="primary" />
```

Both pages now share the menu. Its links use the same files you open in your
editor; PathMX renders their public routes and marks the current page.
The name `primary` connects this import to the component.

---

## 3. Style the workshop

Create `paths/styles.css`:

```css
:root {
  --pmx-color-accent: light-dark(#6840c6, #bda2ff);
  --pmx-color-link: var(--pmx-color-accent);
  --pmx-radius: 0.75rem;
}

.workshop-shell {
  max-width: 64rem;
  margin-inline: auto;
  padding: clamp(1rem, 4vw, 3rem);
}

.workshop-shell > header {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: space-between;
  gap: 1rem;
  padding-block-end: 1rem;
  border-bottom: 1px solid var(--pmx-color-border);
}

.workshop-shell .pmx-nav-list {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
  padding: 0;
  list-style: none;
}

.workshop-shell [aria-current="page"] {
  font-weight: 650;
}
```

Link the stylesheet at the top of `paths/layouts/site.layout.md`:

```md
[@styles]: ../styles.css
```

The menu wraps on narrow screens and the accent changes with the scheme toggle.
Theme tokens control shared colors and shapes; your classes control the workshop
layout. See [Theme a site](../site/theme-a-site.guide.md) to give it its own
colors and type.

---

## 4. Define a lesson card

Create `paths/components/lesson.components.md`. The explanation and working
code live together in one component Block:

````md
<!-- componentName: lesson-card -->

# Lesson card

Link to a lesson and explain what the reader will practice. The named `title`
slot holds the link; the default slot holds the description.

```html
<article class="lesson-card">
  <h2><slot name="title" /></h2>
  <slot />
</article>
```

Use the shared theme tokens so the card fits both light and dark schemes.

```css
.lesson-card {
  padding: 1.25rem;
  border: 1px solid var(--pmx-color-border);
  border-radius: var(--pmx-radius);
  background: var(--pmx-color-surface);
}
```

Use the card on a page that imports this file:

```md
<lesson-card>
  <slot name="title">[Color and contrast](./color.lesson.md)</slot>
  Make text easier to read by comparing foreground and background colors.
</lesson-card>
```
````

This is a [literate Markdown component](../authoring/components.reference.md):
a readable explanation interleaved with its implementation.

---

## 5. Add a lesson and use the card

Create `paths/color.lesson.md`:

```md
# Color and contrast

Contrast helps readers distinguish text from its background.

---

<!-- id: practice -->

## Compare two palettes

Choose a light and a dark background. Try a foreground color on each, then
explain which combination is easier to read.

Return to the [workshop](./index.md).
```

Replace `paths/index.md` with:

```md
[@layout.default]: ./layouts/site.layout.md
[@lessons]: ./components/lesson.components.md

# Color workshop

Learn to build clear, readable color palettes.

---

## Start learning

<lesson-card>
  <slot name="title">[Color and contrast](./color.lesson.md)</slot>
  Make text easier to read by comparing foreground and background colors.
</lesson-card>
```

The home page shows the card. Follow its link to `/color.lesson`: the lesson
uses the same layout and has a separate practice Block. A link to
`./color.lesson.md#practice` opens that activity directly.

---

## 6. Play the lesson

Activate Player using the project-local CLI:

```sh
bun run pmx plugins add player
```

This installs the package and records its activation in `package.json`. Restart
`bun run dev` after changing installed Plugins.

Add `<x-player-app />` after `</main>` in `paths/layouts/site.layout.md`, keeping
one Player app in the layout. The lesson now has a Play button. Add these links
to `paths/index.md` below the lesson card:

```md
[@link.play.focus Read the lesson](./color.lesson.md)

[@link.play.slides Present the lesson](./color.lesson.md)
```

Open each link. Focus guides you through the lesson; Slides presents the same two
Blocks. Advance to “Compare two palettes,” then exit Play to return to reading.
The [Player reference](../learning/player.reference.md) covers controls and settings.

---

## 7. Check and publish

Run these from the project directory:

```sh
bun run check
bun run pmx tree
bun run pmx export --origin https://example.com
```

Lint should report no issues. The tree includes your pages, layout, navigation,
and component file. Export writes the public site to `dist/`; replace the example
origin with your site's address before deploying.

Before sharing, follow each menu and card link, check a narrow window, and try
both color schemes. The [publishing guide](./publish.guide.md) covers deployment
and the [site references](../site/index.md) explain each file's contract.