Adding a new guide - Caplia Docs

Internal how-to for the Caplia team — remove this page from docs.json before making the Guides tab customer-only, or leave it as the team recipe.

Each guide is one MDX file in the guides/ folder with a video at the top. Five minutes, no code knowledge needed.

Record the video

Loom, YouTube (unlisted), or Mux all work: anything that gives you an embed URL. Keep guides under ~5 minutes; one task per guide.

Copy an existing guide

Duplicate guides/welcome-tour.mdx, rename the file to your topic in kebab-case (e.g. guides/creating-a-cohort-channel.mdx), and update the frontmatter title, description, and icon.

Paste your video embed

Replace the placeholder with your embed:

Loom

<iframe
  src="https://www.loom.com/embed/YOUR_VIDEO_ID"
  frameborder="0"
  allowfullscreen
  style={{ width: '100%', aspectRatio: '16 / 9', borderRadius: '12px' }}
></iframe>

YouTube

<iframe
  src="https://www.youtube.com/embed/YOUR_VIDEO_ID"
  frameborder="0"
  allowfullscreen
  style={{ width: '100%', aspectRatio: '16 / 9', borderRadius: '12px' }}
></iframe>

Optionally add 3-5 written steps below the video so the guide works without sound.

Add the page path to the Guides tab in docs.json ("guides/creating-a-cohort-channel"), and add a <Card> for it on guides/index.mdx so it shows in the hub.

Open a PR and merge

All changes go through a pull request: main is protected and publishes the live site the moment a PR merges. Every PR runs a Validate Docs check (links and style); the merge button unlocks when it’s green. If it fails, the check names exactly what to fix.

Ask Claude to do steps 2–5 for you: “add a guide called Creating a cohort channel with this Loom link” is enough. If you’re using Claude with the GitHub connector (Cowork), tell it to read AGENTS.md in the repo root first: it holds the style rules the checks enforce, then have it create a branch, commit the files, and open the PR for you.