Contains source Markdown files for Zoo's documentation. Handwritten pages live alongside directories mirrored from other repositories.
Did you find a typo? Please make a pull request!
Edit generated documentation in its authoritative repository. Changes made to the downstream mirrors in this repository will be overwritten.
| Path in this repository | Authoritative source |
|---|---|
content/pages/docs/kcl-lang/** |
KittyCAD/modeling-app docs/kcl-lang/** |
content/pages/docs/kcl-std/** |
modeling-app/rust/kcl-lib/std/** doc comments, rendered into modeling-app/docs/kcl-std/** |
content/kcl-test-outputs/** |
modeling-app/rust/kcl-lib/tests/outputs/** |
content/pages/docs/cli/manual/zoo*.md |
KittyCAD/cli, generated with make gen-md |
The remaining file in the CLI manual, index.md, is handwritten here. The
API reference is generated separately and is not
stored in this repository.
See AGENTS.md for generator commands and the exact ownership
rules used by coding agents.
For blog, research, and press posts, use frontmatter tags for content categories.
Do not add the New tag manually. The website frontend uses the frontmatter date to
automatically show a New badge for posts published within the last two calendar
months. It checks recency when the page loads, including on preview cards, article
headings, and the New tag results page. Refreshing or revisiting the page updates
the badge; no content edits or site rebuilds are needed for it to expire.
Image frames use the website's page accent by default. To choose a different
accent for an image, set theme="green" (or another supported theme) on
FramedImage, or frameColor="var(--green)" on ZoomableImage. The frame,
corner markers, and zoom control use the same accent.
By default, ZoomableImage preserves the source image's proportions and draws a
frame around its preview. Use unframed when the surrounding component already
provides a frame. Custom thumbnails, including FramedImage, keep their own frames.
Provide image width and height for a stable layout while loading; galleries
use the first image's dimensions to size their previews.
When adding a FramedImage, set aspect to the source image's width and height
(or an equivalent ratio such as 1 / 1 for a square image). Run
npm run check:images to compare these values with the image files. The pull
request build runs the same check and rejects differences above 5%.
Use frameAspect when a different frame shape is intentional; the image will
remain undistorted inside that frame.
npm run build fails with a nonzero exit status for malformed frontmatter,
missing required fields, incompatible field values, unknown metadata fields,
or documents that do not match a content type. Invalid pages must be corrected
instead of being silently omitted from the website. The error output identifies
the affected file and, for YAML syntax errors, the line and column.
Run npm run test:metadata to exercise the build against valid and invalid
metadata, including the unclosed ogImage.url quote that previously caused Ben's
post to disappear. These regression tests and the full content build run in the
build PR check, which is required by the repository's CI ruleset for main.
If you have access to our website repository and you'd like to live preview your content in the website as your write/edit it, head over to that repo's README to get instructions on how to set it up.
You can request a website preview without installing anything locally:
- Push your edits to a branch in
KittyCAD/documentation. No pull request is needed. - Go to Actions → Preview documentation.
- Click Run workflow, leave Use workflow from set to main, enter
your documentation branch name (such as
bens-build-logsorcodex/my-edit), and click the green Run workflow button. - Wait for the run to finish, then open the Open website preview link in
the run's summary. Add
/blogor the path of your edited page to that URL.
Previews are manual snapshots. Saving more edits or opening a PR does not
request a preview; press Run workflow again when you want a new one. The
workflow resolves the selected branch to an exact commit when it starts and
combines it with the website's current main. Both commit IDs appear in the
summary. An existing preview continues to show the snapshot it was built from.
You need write access to this repository to run the workflow. You do not need website repository membership or Vercel deployment permissions: a stored Vercel token authorizes the deployment on your behalf. Fork branches and tags are not accepted; the branch must exist in this repository. Opening the preview is a separate permission check: the website's existing Vercel preview protection still applies. A maintainer may need to grant viewer access or provide a Vercel shareable link. If a run fails, check its logs and the website's Vercel deployment logs.
The workflow becomes available after .github/workflows/preview.yml is merged
into main. Configure these in the documentation repository under
Settings → Secrets and variables → Actions:
| Setting | Type | Value |
|---|---|---|
VERCEL_TOKEN |
Secret | A Vercel access token scoped to the Zoo team, owned by an account authorized to deploy to website |
VERCEL_ORG_ID |
Variable | Zoo's Vercel team ID (team_...) |
VERCEL_PROJECT_ID |
Variable | The existing website project's ID (prj_...) |
GH_ORG_APP_ID |
Secret | Existing GitHub App ID, also used by the website notification workflow |
GH_ORG_APP_PRIVATE_KEY |
Secret | Existing GitHub App private key |
Create the Vercel token in your Vercel account's token settings, select the Zoo
team scope, and choose an expiration date. Store its value only as the Actions
secret, and rotate it before it expires or if its owner's access changes. A
team-scoped token can grant more than preview-only access; the workflow always
requests the Preview target. Find the team and project IDs in Vercel's general
settings or the website's linked .vercel/project.json file. Select the existing
website project, which must already have a production deployment.
The GitHub App only needs Contents: read on KittyCAD/website for this
workflow. It checks out the website and its existing submodules, replaces the
documentation checkout with the selected commit, and stages a source snapshot
outside Git. Git metadata, local .env files, credentials, and generated caches
are excluded; symlinks outside the source snapshot are rejected. No website
branches or commits are created. DOCS_PREVIEW_GIT_AUTHOR is no longer used,
and no GitHub service account is needed.
The pinned Vercel CLI uploads the snapshot directly and waits for Vercel to build it using the website project's existing Preview settings. The deployment token is available only to the upload step; it is not forwarded to the remote build. Documentation install/build scripts run on Vercel and still have access to the project's Preview environment variables. Only default Preview variables apply: this upload has no website Git branch association for branch-specific variables or domains. No source archives are uploaded to public GitHub artifacts.
Deployment retention follows the Vercel project's settings. The job has a 30-minute timeout; canceling it does not necessarily cancel a build already submitted to Vercel. This workflow does not merge changes or deploy to production.