PathMX

Build a workshop site

Turn the two pages from Quickstart 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:

<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:

[@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 for page and type overrides.

2. Add navigation

Create paths/navigation/site.navigation.md:

---
label: Workshop
---

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

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

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

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

<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:

: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:

[@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 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:

<!-- 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: a readable explanation interleaved with its implementation.

5. Add a lesson and use the card

Create paths/color.lesson.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:

[@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:

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:

[@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 covers controls and settings.

7. Check and publish

Run these from the project directory:

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 covers deployment and the site references explain each file's contract.