How a page is built

These docs are Markdown files in a Git repository, built with Fumadocs on Next.js and styled with the Zym Labs design system. This page is for anyone adding or changing a page.

Where pages liveCopy Anchor Link

Every page is an .mdx file under content/docs. The folder it's in is its section; the file name is its URL.

index.mdx                 /docs
getting-started/
  meta.json               the section's title and page order
  index.mdx               /docs/cloud/sign-in
  workspaces.mdx          /docs/cloud/workspaces

Start a page with npm run new, which copies the template for its type. A page starts with its title, a one-line description and its type:

---
title: Quick start
description: From a new account to a test email in your inbox.
type: quickstart
---

This guide takes you from a new account to a test email in your inbox.

The description shows under the title, in search results and in the Markdown versions agents read (/llms.txt), so write it as a sentence.

A product's overview or a welcome page may add illustration: with the name of a file from the design system's library (public/illustrations, e.g. zymlabs-spot-experiments). It shows beside the title. Use one only where the brand book allows: a first step, a welcome, an empty screen or an error, never on a page that's already doing its job.

Order a sectionCopy Anchor Link

Each folder's meta.json names the section and lists its pages in order:

{
  "title": "Argon",
  "pages": ["index", "quick-start"]
}

A page left out of the list goes at the end, alphabetically. The root meta.json orders the sections.

Write in our voiceCopy Anchor Link

Friendly, direct, technically exact. The short version:

• Open with what a thing is and who it's for, then how it works, then the steps.
• Write "you" for the reader and "we" for Zym Labs. Use contractions.
• Headings in sentence case: "Environment variables", "Roll back a release". A verb when the section is a task.
• Steps start with the verb and name the UI element in bold exactly as it appears.

• No "simply", "just" or "easy". No exclamation marks.
• Numbers as numerals. The company is Zym Labs, never "ZYM Labs" or "Zymlabs".

The full guide is the design system's Voice and tone section.

Check a pageCopy Anchor Link

These checks run on every pull request, and you can run them before you push:

npm run lint:prose   # the voice: Vale, with the rules in .vale/styles/ZymLabs
npm test             # the structure: front matter, links, headings and callouts

Each Vale rule quotes the line of the voice guide it comes from. An error fails the pull request; a warning is for you to judge. When a rule is wrong for one sentence, such as a page that quotes a word it bans, turn Vale off around it:

{/* vale off */}
Never write "simply".
{/* vale on */}

A product or proper name that Vale marks as a spelling mistake goes in .vale/styles/config/vocabularies/ZymLabs/accept.txt; one that should keep its capitals in a heading goes in .vale/styles/ZymLabs/Headings.yml.

Run the siteCopy Anchor Link

export NODE_AUTH_TOKEN=$(gh auth token)   # reads @zymlabs/ui from GitHub Packages
npm ci
npm run dev                                # http://localhost:3000

What's nextCopy Anchor Link

• Components: callouts, steps, tabs, cards, screenshots and code blocks.
• Quick start: a finished guide, with every part of a page.