> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# Pocket guides - Handbook

Copy page

# Pocket guides - Handbook

Pocket guides are the docs site's use case books at [/pocket-guides](/pocket-guides.md): each volume is a shelf cover, a 101, and a set of use cases that each end in a one-click "Add this scout" CTA. They render as a full-window e-reader – figures embedded where the prose cites them – and everything a reader sees is authored in MDX.

This page is the short version for authors. The source of truth for the component side lives in the repo: `src/components/PocketGuides/README.md` (the reader, figures, and MDX traps) and `src/components/SelfDrivingInbox/README.md` (the report frontmatter contract, the SKILL.md format, and the agent-mirror constraints).

## How a guide is authored

A use case is one directory:

PostHog AI

```
contents/pocket-guides/<volume>/<slug>/
├── index.mdx    everything a human reads
└── SKILL.md     the scout itself, verbatim
```

-   **Copy `contents/pocket-guides/self-driving/_starter/`** to begin – it's a commented skeleton of both files, kept out of every gallery by the `_` prefix.
-   **Frontmatter carries the structured data**: `title`, `shortTitle`, `bookOrder` (reading order; 0 is the front matter, omit to keep a draft unlisted), the `report` block that renders as the inbox figures, `watches`, `requires`, `category`, and `schedule`.
-   **The body carries every word.** `<LeftPage>` holds the figures, `<RightPage>` the prose; the reader interleaves each figure after the first block that cites it via `<SeeFig n={1} />`.
-   **`SKILL.md` is a real file, not a string** – same frontmatter as the canonical scouts in the monorepo, so one can be pasted in or lifted out without reformatting. The page renders it byte-for-byte, and the "Add this scout" deep link prefills PostHog from it.

## The two MDX traps

1.  **Never start a line with an inline component** (`<Term>`): MDX v1 treats a line-leading tag as a block and splits the paragraph. Keep inline tags mid-sentence.
2.  **Don't hand-wrap block components in paragraphs** – and if a figure ever renders inside a `<p>`, check the `gatsby-remark-inline-jsx-paragraphs` plugin's pocket-guides guard first, then remember Gatsby caches compiled MDX (the fix shows only after the `.mdx` changes or `pnpm clean`).

## Term definitions

`<Term>` hover-card definitions live in `src/components/SelfDrivingInbox/terms.tsx`, each quoted from the docs page it links to. If a docs definition changes, update the quote there.

## Adding new content elements

The book styles every markdown element itself (its container opts out of the site's prose styling), so a new kind of content – a table, a new list style, anything the guides haven't used before – renders unstyled until the book's component map supports it.

-   **Check the rendered page** whenever you introduce an element the guides haven't used yet. Unsupported elements fail silently: browser-default styling, not an error.
-   **Inherit website defaults instead of reinventing them.** Wrap the element in the site's native styling (see how lists and tables borrow `.article-content` in `src/components/PocketGuides/bookPieces.tsx`) rather than writing book-specific styles.
-   **Test text resizing on web and mobile.** Use the Aa control at every size, at desktop and phone widths – the book's type scales from one base size, and new elements need to keep up.

## Measuring

Reader interactions emit the `pocket_guide_interaction` event (marker glosses, term hovers, contents, font size, scout-file expansion) and both "Add this scout" CTAs emit it with `kind: add_scout_click` – that click is the conversion.

### Was this page useful?

HelpfulCould be better