comfyui-nodes-docs-tools

Translation and doc-generation tooling for the comfyui-nodes-docs node documentation set. These scripts were extracted from that repo so the documentation plugin stays lean and the dev tooling can evolve independently.

Layout assumption

The scripts assume this repo sits next to the docs repo:

Software_Projects/
├── comfyui-nodes-docs/         # the documentation plugin (docs/*.md live here)
└── comfyui-nodes-docs-tools/   # this repo

Every script defaults docs/ to ../comfyui-nodes-docs/docs. Override with the COMFY_DOCS_DIR environment variable (or the per-script --docs-dir / --source-dir flag) if your checkout lives elsewhere.

Configuration (environment variables)

The scripts read process.env directly — there is no dotenv auto-loading, so set the variables in your shell before running. PowerShell example:

$env:OPENAI_BASE_URL = "https://your-endpoint/v1"
$env:OPENAI_API_KEY  = "your-key"
$env:OPENAI_MODEL    = "your-model"

Variable	Used by	Default
OPENAI_BASE_URL / ROUTER_BASE_URL	translation, doc-gen LLM tier	translator: none; doc-gen: http://127.0.0.1:20128/v1
OPENAI_API_KEY / ROUTER_API_KEY	translation, doc-gen LLM tier	local
OPENAI_MODEL(S) / ROUTER_MODEL(S)	translation, doc-gen LLM tier	translator: none; doc-gen: free-translation
COMFY_DOCS_DIR	all scripts	../comfyui-nodes-docs/docs
COMFY_HOST / COMFY_PORT	generate_doc_from_introspection.js	127.0.0.1 / 8188
COMFY_CUSTOM_NODES_DIR	doc-gen repo-link resolution	required for custom-node repo links
COMFY_WORKFLOWS_DIR	doc-gen --discover	required for --discover

COMFY_CUSTOM_NODES_DIR and COMFY_WORKFLOWS_DIR are genuinely machine-specific (they point into your local ComfyUI install), so they have no default and the script fails fast with guidance when a mode that needs them is used.

Scripts

npm script	File	What it does
npm run translate:docs	translate_with_router.js	Batch-translate docs/<node>.md → docs/<node>_en.md via any OpenAI-compatible endpoint. Preserves code blocks, metadata lines, and Markdown structure; resume-friendly via a .cache/ manifest, with model rotation and caching.
npm run translate:test	translate_test_run.js	Translate a small selection into _test_docs/ for a trial run.
npm run retrofit:source	retrofit_source_block.js	Rewrite the # Source code block in *_en.md docs to a GitHub repo link. Defaults to a dry-run; pass --apply to write.
npm run generate:doc	generate_doc_from_introspection.js	Generate English *_en.md docs from a running ComfyUI's /object_info. Schema-only (Tier 0) by default; --llm fills missing prose. See --help.

Examples

# Translate the next 50 missing/stale docs
npm run translate:docs -- --limit 50

# Dry-run the source-block retrofit (no files written)
npm run retrofit:source

# Generate a doc for one node into .cache/generated-docs/ (preview, never docs/)
npm run generate:doc -- KSampler