Skip to main content

Documentation Index

Fetch the complete documentation index at: https://internal.september.wtf/llms.txt

Use this file to discover all available pages before exploring further.

You write docs the same way you write code: in branches, reviewed by a human, deployed automatically. This page covers the mechanics.

​
Setup

git clone git@github.com:septemberai/engine-docs.git
cd engine-docs
npm i -g mint
mint dev
That spins up a local Mintlify server on http://localhost:3000. Edits to .mdx files are picked up live.

​
Writing a new page

  1. Decide which tab the page belongs in: Platform, Operations, or Internal.
  2. Decide the Diátaxis mode: tutorial, how-to, conceptual, or reference. See the style guide.
  3. Write the page in .mdx with frontmatter: 
    ---
title: "Your title"
description: "One-line description used in search and the sidebar."
internal: false  # set true for internal-only
---
  4. Add the page to docs.json so it shows up in the navigation. The build will fail if you forget.
  5. Cross-link from related pages.
  6. Open a PR.

​
Reviewing a doc PR

Reviewers check:
  • Mode purity. Page is one Diátaxis quadrant, not several.
  • Voice. Right person, right tense.
  • Accuracy. Endpoint paths, env var names, types — all match the Engine’s current behavior.
  • Code samples run. Reviewer should be able to copy-paste and have it work.
  • Cross-links. First mention links to canonical reference.
  • Internal/public split. Anything sensitive is gated.
  • Style. Sentence case, no marketing words, no exclamation marks.
If a page violates the style guide, the fix is to follow the style guide, not to update the style guide. The style guide changes through deliberate review, not by drift.

​
Build flavors

The same source builds two outputs:
  • Public build. Strips pages with internal: true in frontmatter. Strips internal: true blocks within pages (Mintlify supports conditional content).
  • Internal build. Includes everything.
The build script reads an environment variable to decide which flavor to produce: 
DOCS_FLAVOR=public mint build
DOCS_FLAVOR=internal mint build
The strip step is in scripts/strip-internal.mjs (TODO — script lands with the first deploy).

​
When to ask

  • Should this be a new page or an addition to an existing one? — ask in PR review.
  • Should this be public or internal? — when in doubt, internal.
  • Substantial reshape of the docs surface? — discuss in the docs channel before opening a large PR.

​
Pulling docs from the Engine source

Some pages — env vars, endpoints, event types — are best as auto-generated content. Today they’re hand-written but kept in sync with the engine repo. The longer-term plan is a generator that reads the engine source on every build and emits a _generated/ tree, which is gitignored.

​
Test before merging

There’s no CI test that catches a misleading paragraph, but there is one for broken links and frontmatter. The Mintlify CLI runs both: 
mint broken-links
mint check
Both should be clean before requesting review.

​
After merging

Mintlify rebuilds and redeploys automatically. The internal site updates within a couple of minutes. The public site updates on the next release window — see the release calendar.

​
Learning more