Comfy-Org/docs

What is Comfy‑Org/docs?

This repository holds the official documentation site for ComfyUI, a visual node‑based interface for building AI image‑generation pipelines (e.g., Stable Diffusion). The docs are built with Mintlify, a static‑site generator that renders MDX files into a multilingual website (https://docs.comfy.org/).

Core purpose

• Store the source Markdown/MDX files that make up the user‑facing docs.
• Provide scripts to preview changes locally (npm i && npm run dev).
• Automate translation of the English docs into several languages (Chinese, Japanese, Korean, etc.) using an OpenAI‑compatible translation model.
• Keep the documentation for built‑in nodes in sync with the separate Comfy-Org/embedded-docs repo.
• Generate API reference pages from OpenAPI specifications.

Key features & workflows

Feature	How it works	Why it matters
Local preview	npm run dev starts a dev server that renders the MDX files.	Lets contributors see changes instantly before merging.
Automated i18n	npm run translate calls a translation API (OpenAI‑compatible) and writes translated MDX under language folders. Hashes in front‑matter track whether a file is up‑to‑date.	Keeps the docs in sync across languages without manual translation effort.
Glossary & term consistency	A three‑layer system (preserve_terms, glossary/frontend, glossary/overrides) ensures technical terms stay consistent across translations.	Prevents confusing or contradictory terminology in multilingual docs.
API reference generation	npx @mintlify/scraping@latest openapi-file <path> converts an OpenAPI spec into MDX endpoint pages.	Provides up‑to‑date, searchable API docs for developers using ComfyUI’s backend services.
Redirect safety	PRs must include a redirects array in docs.json when a file is renamed; a GitHub Action fails the PR if missing.	Guarantees old links keep working after restructuring.
Sync‑owned files protection	Certain files (e.g., openapi‑v2.yaml, generated router pages) are auto‑generated each sync. A workflow blocks PRs that edit these guarded paths.	Prevents accidental overwrites of auto‑generated content.
Contribution flow	Open a PR → Vercel auto‑deploys to https://docs.comfy.org/ → reviewers merge.	Simple, fast feedback loop for documentation updates.

Who should use it?

• ComfyUI users looking for installation guides, node reference, or workflow examples.
• Developers needing the OpenAPI spec or API usage examples.
• Translators who want to add a new language (open an issue; the repo handles bulk translation automatically).
• Contributors who want to improve docs, add tutorials, or fix terminology.

How to get started

1. Clone the repo.
2. Run npm i then npm run dev to view the site locally.
3. Edit or add MDX files under the root (English) or language sub‑folders.
4. When ready, push a branch and open a PR. After merge, Vercel will publish the changes.
5. If you need a new language, open an issue; maintainers will add it to translation-config.json and run the bulk translation scripts.

---

In short: Comfy‑Org/docs is the source‑code and automation hub for the multilingual documentation of the ComfyUI AI workflow tool, providing easy local preview, automated translation, API reference generation, and safe contribution processes.