overview getting started

Getting started

Active contributors: Andy Taylor, Eno Reyes

Purpose

This page walks a new contributor from git clone to a previewed change.

Prerequisites

• Git

• A local Mintlify CLI install for live preview (Node.js + npm). Mintlify is the rendering engine for the site; it is not vendored in this repo, so install it globally:

  npm install -g mint

  (Mintlify has shipped the CLI under both mintlify and mint. If mint is not available on your platform, npm install -g mintlify works too.)

• A Markdown editor with MDX support. VS Code with an MDX extension is a common choice.

Clone and preview

git clone https://github.com/Factory-AI/factory.git
cd factory/docs
mint dev   # or: mintlify dev

The dev server serves the same content that goes to docs.factory.ai, with hot reload on file changes.

Authoring a page

1. Decide which top-level area the page belongs to — see the section map. Pages live in docs/<area>/<subarea>/<slug>.mdx.

2. Create the .mdx file with frontmatter:

   ---
   title: "Page title"
   description: "One-sentence description used in search and previews"
   keywords: ['keyword', 'keyword']
   ---

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

4. Add the page to docs/docs.json under the right group. The path is the file path without .mdx (e.g., cli/features/missions).

5. If you renamed an existing page, add a redirects entry in docs.json from the old path to the new one.

6. Mirror the change to docs/jp/<same-path>.mdx, or let the JP sync workflow handle it after merge.

Editing existing pages

Find the page either by clicking the GitHub edit link from the live site or by grepping docs/:

rg "exact phrase from the page" docs/

Make the change, run mint dev locally to confirm rendering, then open a PR.

Adding images

Drop the asset under docs/images/ and reference it by absolute path:

<img src="/images/my-screenshot.png" alt="..." className="rounded-lg" />

Prefer PNG for screenshots, GIF for short animations, and SVG for diagrams or logos. Compress large PNGs before committing.

Running the doc-quality droid locally

The repo uses Factory's own droid for review. You don't need to install it to contribute, but if you want to try the same review the bot would run, install the CLI and use droid /review:

npm install -g droid
cd factory
droid
> /review

Submitting a PR

1. Push your branch.
2. Open a PR against main.
3. The droid-review.yml workflow runs the review droid on the diff and leaves comments.
4. The sync-jp-docs.yml workflow translates English changes to Japanese after merge if you didn't update docs/jp/ yourself.
5. After merge, pr-merge-slack.yml posts to Slack and the changelog automation pushes any release notes to Discord and Linear.

See How to contribute for review expectations and conventions.