[GH-ISSUE #186] Generated built-in node descriptions fall below the 40-char guideline in localized pages #23

New issue

Closed

opened 2026-10-26 22:08:08 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:08:08 +00:00

Owner

Originally created by @lin-bot23 on GitHub (Oct 17, 2026).
Original GitHub issue: https://github.com/Comfy-Org/embedded-docs/issues/186

Built-in node pages in Comfy-Org/docs are generated by docs-generation/scripts/sync_to_comfy_docs.py, which seeds every frontmatter description from the first sentence of the first overview paragraph of the localized .md:

get_description_from_content() (line ~860) returns one sentence.
build_frontmatter() (line ~1057) then hard-slices to MAX_DESCRIPTION_CHARS = 160.
_MIN_DESCRIPTION_CHARS = 40 already exists but is only used as a lower bound when trimming; nothing expands a short seed.

Comfy-Org/docs AGENTS.md asks every page for a 40-160 char description, so localized pages that inherit a short first sentence end up below the minimum. CJK carries the same scope in fewer characters, so this hits zh hardest.

Counted in Comfy-Org/docs at f3f932396 (*/built-in-nodes/*.mdx, description shorter than 40 chars):

locale	pages under 40 chars
zh	447 / 1055
ja	156 / 1055
ko	105 / 1051
en	21 / 1055

Found while reviewing Comfy-Org/docs#1984, where CodeRabbit flagged the Japanese/Korean/Chinese MOSSImageLayoutPrompt description; it was withdrawn as a page-level finding because hand edits to generated frontmatter are reverted by the next sync, and the fix belongs here.

Proposed fix

In get_description_from_content() (or at the call sites at lines ~1195 / ~1211): keep appending following sentences from the same paragraph while the result is shorter than _MIN_DESCRIPTION_CHARS and does not exceed MAX_DESCRIPTION_CHARS, using the same CJK sentence boundaries _first_sentence() already handles; fall back to the next paragraph only if the overview paragraph runs out.

Why not in the node-docs sync PR

It rewrites frontmatter on roughly 700 localized pages across every locale, i.e. it is a separate generator change + full re-sync, not part of one node sync. Opening this so the decision and the re-sync stay tracked outside docs#1984.

Originally created by @lin-bot23 on GitHub (Oct 17, 2026). Original GitHub issue: https://github.com/Comfy-Org/embedded-docs/issues/186 Built-in node pages in `Comfy-Org/docs` are generated by `docs-generation/scripts/sync_to_comfy_docs.py`, which seeds every frontmatter `description` from the **first sentence of the first overview paragraph** of the localized `.md`: - `get_description_from_content()` (line ~860) returns one sentence. - `build_frontmatter()` (line ~1057) then hard-slices to `MAX_DESCRIPTION_CHARS = 160`. - `_MIN_DESCRIPTION_CHARS = 40` already exists but is only used as a lower bound when *trimming*; nothing expands a short seed. `Comfy-Org/docs` AGENTS.md asks every page for a **40-160 char** description, so localized pages that inherit a short first sentence end up below the minimum. CJK carries the same scope in fewer characters, so this hits zh hardest. Counted in `Comfy-Org/docs` at `f3f932396` (`*/built-in-nodes/*.mdx`, `description` shorter than 40 chars): | locale | pages under 40 chars | | --- | --- | | zh | 447 / 1055 | | ja | 156 / 1055 | | ko | 105 / 1051 | | en | 21 / 1055 | Found while reviewing Comfy-Org/docs#1984, where CodeRabbit flagged the Japanese/Korean/Chinese `MOSSImageLayoutPrompt` description; it was withdrawn as a page-level finding because hand edits to generated frontmatter are reverted by the next sync, and the fix belongs here. ## Proposed fix In `get_description_from_content()` (or at the call sites at lines ~1195 / ~1211): keep appending following sentences from the same paragraph while the result is shorter than `_MIN_DESCRIPTION_CHARS` and does not exceed `MAX_DESCRIPTION_CHARS`, using the same CJK sentence boundaries `_first_sentence()` already handles; fall back to the next paragraph only if the overview paragraph runs out. ## Why not in the node-docs sync PR It rewrites frontmatter on roughly 700 localized pages across every locale, i.e. it is a separate generator change + full re-sync, not part of one node sync. Opening this so the decision and the re-sync stay tracked outside docs#1984.

bsakaguchi closed this issue

2026-10-26 22:08:08 +00:00

bsakaguchi referenced this issue

2026-10-26 22:08:23 +00:00

[PR #23] [MERGED] Update Clip Set Last Layer docs #41