[@layout]: ../layouts/site.layout.md
[@preview]: ./basics.components.md

# Small docs patterns

Working candidates for compact links, actions, and example/result layouts.
Return to the [design workbench](./index.md) to review the larger patterns.

---

# Foundations

Let the content set the hierarchy. A heading introduces an idea, prose explains
it, and an example makes it concrete. Use ordinary Markdown for paragraphs,
lists, tables, and code. Use a component when a repeated layout helps the reader.

These patterns inherit the current theme. Text uses `--pmx-color-text`, secondary
copy uses `--pmx-color-muted`, and borders use `--pmx-color-border`. Heading fonts,
accent colors, and corner radii also come from the theme. Change the theme once
instead of maintaining a second palette for docs.

Links open destinations. Buttons perform actions. The shared `.pmx-button` class
can emphasize either without changing its native behavior. Labels describe the
reader's next step. See [Shared UI](../docs/site/ui.reference.md#shared-controls) for the
underlying tokens and control states.

---

## Use these patterns

Import this Source from another docs page, then write the components with your
own content. Paths in the example below assume a page beside this file.

```md
[@docs]: ./basics.components.md

<doc-actions>
  <a class="pmx-button" href="../docs/start/first-site.guide.md">Build your first site</a>
  <a class="pmx-button" data-variant="outline" href="../docs/authoring/index.md">Explore authoring</a>
</doc-actions>
```

Keep related explanation and examples in a Block, separated from the next idea
with `---`. This gives reading, Focus, and Slides the same useful sequence.
These components use normal flow and wrapping, so their content can grow with
the available space.

---

<!-- componentName: guide-row -->

## Guide links

Use a compact row when a reader is choosing among related guides. The title
names the destination and the description explains what it helps them do. The
whole row is one link, with a visible outline for keyboard focus.

<guide-row href="../docs/start/first-site.guide.md" title="Your first site" description="Create a Source, run the site, and see an edit appear." />
<guide-row href="../docs/authoring/components.reference.md" title="Components" description="Turn repeated markup into elements you can explain and reuse." />

The template accepts `href`, `title`, and `description`. A Source query supplies
these fields automatically. This is a candidate refinement of the existing
Authoring index rows.

```html
<a class="pmx-guide-row" href="{{ href }}">
  <strong>{{ title }}</strong>
  <span>{{ description }}</span>
</a>
```

The layout follows the width of its container: a narrow sidebar or slide can
stack the title and description independently of the browser's width.

```css
.pmx-guide-row {
  display: flex;
  flex-wrap: wrap;
  gap: 0.25rem 1rem;
  padding: 0.8rem 0;
  border-bottom: 1px solid var(--pmx-color-border);
  color: var(--pmx-color-text);
  text-decoration: none;
  overflow-wrap: anywhere;
}
.pmx-guide-row strong {
  flex: 1 1 10rem;
  font-family: var(--pmx-font-heading);
  font-weight: 650;
}
.pmx-guide-row > span {
  flex: 3 1 17rem;
  color: var(--pmx-color-muted);
  font-size: 0.92em;
}
.pmx-guide-row:is(:hover, :focus-visible) strong {
  color: var(--pmx-color-accent);
}
.pmx-guide-row:focus-visible {
  outline: 2px solid var(--pmx-color-accent);
  outline-offset: 4px;
}
```

---

## Choose the destinations

For a curated list, author the title and description explicitly. For an index
that follows a folder, use a query with `component: guide-row`.

```md
<guide-row href="../docs/start/first-site.guide.md"
  title="Your first site"
  description="Create a Source and see an edit appear." />
```

This query shape can supply a generated index after importing the component Source:

````md
```query
from: .
type: reference
sort:
  - by: meta.title
component: guide-row
```
````

Use [ordinary links or rich references](../docs/authoring/links.reference.md) when a
sentence or a preview card better fits the content.

---

<!-- componentName: doc-actions -->

## Actions together

Group a primary next step with a related alternative. The component only arranges
its children; the shared control styles own size, color, hover, and focus. All
labels and destinations come from the page that uses it.

<doc-actions>
  <a class="pmx-button" href="../docs/start/first-site.guide.md">Build your first site</a>
  <a class="pmx-button" data-variant="outline" href="../docs/start/build-a-site.guide.md">Build a workshop</a>
</doc-actions>

```html
<div class="pmx-doc-actions"><slot /></div>
```

Wrapping keeps each action intact when the group runs out of room. Long labels
can wrap within a control without widening the page. Markdown's paragraph
wrapper also arranges its links as a group.

```css
.pmx-doc-actions,
.pmx-doc-actions > p {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 0.75rem;
}
.pmx-doc-actions { margin-block: 1.25rem; }
.pmx-doc-actions > p { margin: 0; }
.pmx-doc-actions :is(a, button) {
  max-inline-size: 100%;
  white-space: normal;
  text-align: center;
}
```

---

<!-- componentName: doc-example -->

## Example and result

Pair a short authoring example with its live result. The default slot holds the
code or explanation; the named `result` slot holds the working content. Both are
authored by the consuming page, so the component adds no generic visible labels.

<doc-example>

```md
**Write once. Read and reuse.**
```

<slot name="result">

**Write once. Read and reuse.**

</slot>
</doc-example>

```html
<div class="pmx-doc-example">
  <div class="pmx-doc-example-authoring"><slot /></div>
  <div class="pmx-doc-example-result"><slot name="result" /></div>
</div>
```

A quiet surface separates the result. The layout stacks when two readable
columns no longer fit. Code keeps its own horizontal scrolling.

```css
.pmx-doc-example {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
  margin-block: 1.25rem;
}
.pmx-doc-example > * {
  flex: 1 1 16rem;
  min-inline-size: 0;
}
.pmx-doc-example-result {
  padding: 1.25rem;
  background: var(--pmx-color-surface);
  border: 1px solid var(--pmx-color-border);
  border-radius: var(--pmx-radius);
}
.pmx-doc-example > * > :first-child { margin-block-start: 0; }
.pmx-doc-example > * > :last-child { margin-block-end: 0; }
```

---

## Compose an example

Keep the code sample and its result close enough to compare. The fenced sample
is readable Markdown; content inside the `result` slot is rendered normally.
Edit both when the example changes.

````md
<doc-example>

```md
**Write once. Read and reuse.**
```

<slot name="result">

**Write once. Read and reuse.**

</slot>
</doc-example>
````

For larger examples, link to the [working Source](../examples/index.md) instead
of copying an entire application into a narrow panel. Use
[Source embeds](../docs/authoring/components.reference.md#source-embeds) when the
reader needs to interact with a complete page.