PostHog Handbook Library / Wizard And Docs

543 words. Estimated reading time: 3 min.

# Pocket guides

Pocket guides are the docs site's use case books at /pocket-guides: 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:

    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 ``.

- `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.

1. 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.

Canonical URL: https://posthog.com/handbook/wizard-and-docs/pocket-guides

GitHub source: contents/handbook/wizard-and-docs/pocket-guides.md

Content hash: `6b150d8ae80c3189`

Static reader notes

- `MDX_COMPONENT_STATIC_ADAPTER`: Adapted interactive MDX components for static reading: LeftPage, RightPage, SeeFig, Term.