Skip to content
supermdtDocs

Contributing to the docs

Rules and workflow for the team writing the documentation.

On this page03
  1. Where the docs live
  2. Adding a page
  3. Screenshots

This page is for the SuperMDT team.

Where the docs live

Section titled “Where the docs live”

The documentation is a Starlight site in apps/site. French is the reference language, served under /docs/; English is served under /en/docs/. A page uses the same file name in both languages: this is how Starlight links translations (language picker, fallback to French when a translation is missing).

  • Directoryapps/site/src/
    • Directoryassets/screens/ generated screenshots (do not edit by hand)
      • Directoryen/ screenshots of the English interface
        • …
    • components/Screenshot.astro
    • Directorycontent/docs/
      • Directorydocs/ French pages (/docs/…)
        • index.mdx
        • getting-started.mdx
      • Directoryen/
        • Directorydocs/ English pages (/en/docs/…)
          • index.mdx
          • getting-started.mdx

Adding a page

Section titled “Adding a page”

  1. Create the French page in apps/site/src/content/docs/docs/, for example patrols.mdx. The file name becomes the URL: /docs/patrols/.

  2. Fill in the frontmatter: title, description and, to position the page in the sidebar, sidebar.order.

    ---
    title: Patrouilles
    description: Organiser les patrouilles depuis le dispatch.
    sidebar:
      order: 10
    ---

  3. Create the English translation with the same file name in apps/site/src/content/docs/en/docs/. It will be served under /en/docs/patrols/.

  4. Check the result with pnpm --filter @supermdt/site dev, then open http://localhost:4321/en/docs/.

The sidebar is generated automatically from the docs/ folder: no extra configuration is needed.

Screenshots

Section titled “Screenshots”

Screenshots are never taken by hand: they are generated by tools/screenshots (Playwright), in dark and light themes, on desktop and mobile.

  1. Declare the scene in tools/screenshots/scenes.ts:

    { name: 'patrols', path: '/dispatch/patrols' }

  2. Start the web app (http://localhost:5180), then regenerate the screenshots:

    Fenêtre de terminal
    pnpm screenshots
    pnpm screenshots --lang en

    Files are written to apps/site/src/assets/screens/ (and en/ for English) as <name>.<theme>.<device>.png.

  3. Insert the screenshot in the page with the Screenshot component:

    import Screenshot from '../../../../components/Screenshot.astro';
    

    <Screenshot name="patrols" caption="The patrol board" />

    Add device="mobile" for the mobile version. The component shows the dark or light version depending on the reader’s theme, and a “Screenshot coming soon” placeholder until the file exists.

Signed-in screens and open panels

Section titled “Signed-in screens and open panels”

Most screens require being signed in. A scene asks for it with auth: 'demo': the script first regenerates the “San Andreas RP” demo organization (address demo) in the screenshot language, then signs in once with the development sign-in (name “demo”) and reuses the session for every scene. The local Convex backend must be running with DEV_LOGIN=true (and VITE_DEV_LOGIN=true on the app side).

To capture an open panel, add actions, played in order. Elements are always targeted by their accessible role and name, never by a CSS class; a name can be given per language.

{
  name: 'nav-panel',
  path: '/o/demo',
  auth: 'demo',
  devices: ['desktop'],
  actions: [{ click: { role: 'button', name: { fr: 'Dossiers', en: 'Records' } } }],
}

Available actions: click, fill (by label), press (keyboard shortcut, e.g. 'Control+K'), waitFor and wait (a delay, as a last resort). The demo can also be regenerated by hand:

Fenêtre de terminal
pnpm --filter @supermdt/backend exec convex run seed:demo '{"locale":"en"}'

pnpm screenshots --no-seed skips this step.