how to contribute development workflow

Development workflow

Local preview

cd docs
mint dev   # or: mintlify dev

Mint serves the same content tree that goes to docs.factory.ai and hot-reloads on file changes.

Adding a new page

1. Create the MDX file under the right area in docs/. See the section map for where things live.

2. Add frontmatter:

   ---
   title: "Page title"
   sidebarTitle: "Optional shorter sidebar label"
   description: "One-sentence description"
   keywords: ['keyword', 'another']
   ---

3. Write the body. Use Mintlify components (<Card>, <CardGroup>, <Note>, <Tip>, <Warning>, <Steps>, <CodeGroup>, <Tabs>, <AccordionGroup>).

4. Reference the new page in docs/docs.json under the appropriate group (and, for bilingual coverage, the matching JP group).

5. Validate locally with mint dev.

Renaming or moving a page

1. Move the file to its new location.

2. Add a redirects entry in docs/docs.json:

   {
     "source": "/old/path",
     "destination": "/new/path"
   }

3. Update internal links that pointed at the old path. (Internal links use absolute paths starting with /, e.g., /cli/getting-started/quickstart.)

4. Move and update the JP counterpart, or let sync-jp-docs.yml handle it.

Adding images

• Place files under docs/images/ (use a subfolder if it makes sense — features/, quickstart/, tutorial/).
• Reference them with absolute paths: <img src="/images/foo.png" alt="..." className="rounded-lg" />.
• Compress large PNGs before committing — repo size shows up in clone times.

Working with snippets

Reusable MDX fragments live in docs/snippets/. Import them:

import Snippet from '/snippets/my-snippet.mdx';

<Snippet />

Editing the changelog

docs/changelog/release-notes.mdx is the canonical changelog and gets a new entry per CLI release. Entries follow the existing format. The file is large (~127 KB) so split-page experiments (1-8.mdx, 1-9.mdx, 1-10.mdx) live alongside it; treat those as the long-term direction.

Running the review droid

.github/workflows/droid-review.yml runs on PRs and posts review comments. To run it locally:

npm install -g droid
cd factory
droid
> /review

Translating to Japanese

You don't have to. The sync-jp-docs.yml workflow translates merged English changes automatically. If you want to seed a JP edit yourself, place it at the parallel path under docs/jp/.

Testing

There is no traditional test suite — this is a content repo. The validation surface is:

• Mint dev preview — the closest thing to "did it compile".
• Droid review — opinions on prose quality, missing context, broken links.
• PR review — humans.

If you add a new product feature page, also check that the existing pages that should link to it (often docs.json's sidebar entries, plus cli/getting-started/overview.mdx and web/getting-started/overview.mdx) are updated.