Skip to content
Annot

Install the living-product-docs trio

The living-product-docs packages turn a Playwright tour suite into always-fresh user manuals, and Excel screen specifications — same MDX source, dual rendering targets, drift between MDX + live UI caught as a CI lint step.

Three packages compose into the flow:

PackageRole
@ingcreators/annot-product-docsCore: MDX parser, Playwright screen fixture, drift detector, annot docs CLI
@ingcreators/annot-product-docs-astroAstro components (<Screen> / <Overlay> / …) + the Image Service that composes annotated PNGs at build time
@ingcreators/annot-product-docs-xlsxExcel adapter — emits one .xlsx per book using either the OSS default layout or a customer-supplied template populated via {var} placeholders + Named Ranges

Install

Section titled “Install”
Terminal window
pnpm add @ingcreators/annot-product-docs
pnpm add @ingcreators/annot-product-docs-astro      # if you want a docs site
pnpm add @ingcreators/annot-product-docs-xlsx       # if you want Excel screen-spec output


# Playwright is a peer dep of the core package.
pnpm add -D @playwright/test

Scaffold

Section titled “Scaffold”
Terminal window
pnpm annot-docs init

Drops three files into the repo:

annot-docs.config.ts              # project + book config
tests/docs/example.spec.ts        # Playwright tour
docs/books/example/SC-001-login.mdx  # one screen, three overlays

Author one screen

Section titled “Author one screen”
---
annot:
  id: SC-001
  title: Login screen
  xlsx:
    book: Screen spec
    sheet: SC-001 Login
    role: screen
---


import Screen from "@ingcreators/annot-product-docs-astro/components/Screen.astro";
import Overlay from "@ingcreators/annot-product-docs-astro/components/Overlay.astro";


# Login screen


<Screen id="login" src="./shots/login.png">


<Overlay match={{ role: "textbox", name: "Email" }} intent="required" number={1}>
**Email** — Enter your registered email.
</Overlay>


<Overlay match={{ role: "button", name: "Sign in" }} intent="action" number={2}>
Click to sign in.
</Overlay>


</Screen>

match keys are persistent — Playwright’s ref=eN markers in aria snapshots are not. The resolver re-finds each overlay’s target element on every tour run.

Wire up the tour

Section titled “Wire up the tour”
tests/docs/auth.spec.ts
import { test } from "@ingcreators/annot-product-docs";


test("login flow", async ({ page, productDocs }) => {
  await page.goto("/login");
  await productDocs.sync({
    id: "login",
    mdxPath: "docs/books/example/SC-001-login.mdx",
  });
});

productDocs.sync(...) updates the annot:snapshot + annot:attributes comment blocks in the MDX in-place, byte-stably — diffs are stable across reruns when the UI hasn’t changed.

Render the docs

Section titled “Render the docs”
Terminal window
# Astro docs site
pnpm --filter docs-site build


# Excel screen specifications
pnpm annot-docs-xlsx render

Lint for drift in CI

Section titled “Lint for drift in CI”
Terminal window
annot-docs lint --ci --json --url http://localhost:5173

Six finding kinds — added / removed / renamed / role-changed / duplicated / attribute-drift. The example GitHub Actions workflow shipped with the package converts the JSON to per-line core.warning annotations on the PR diff view.

Next steps

Section titled “Next steps”