Problem
There are two copies of getSourceFromFrontmatter in the repo:
Both copies should behave the same way. The docs-cli copy is used by docs edit (via scripts/docs-cli/commands/edit.js) to find a shared source file when opening a consumer page. Its bugs are latent there but still real:
Bugs in the docs-cli copy
-
Regex matches outside the frontmatter block. content.match(/^source:\s*(.+)$/m) matches ^source: anywhere in the file, so a source: key inside a fenced YAML example (for example, Docker Compose docs) gets treated as the page's shared source. docs edit will then try to open the wrong file.
-
Only normalizes paths starting with /. Frontmatter of the form source: shared/foo.md (without a leading slash) is returned verbatim as shared/foo.md, which is a relative path that doesn't resolve from the caller's cwd. docs edit either fails or opens something unexpected.
Fix
Port the fix from #7136 (commit 5241ff7a5) to the docs-cli copy:
- Restrict the regex to match only within the top-of-file frontmatter block (between
--- delimiters).
- Normalize
/shared/..., shared/..., and content/shared/... consistently.
- Return
null for unexpected shapes (absolute filesystem paths, URLs) rather than returning a misleading path.
Longer term
The two copies are drift-prone. A follow-up refactor could consolidate on a single source of truth — either re-export from one location, or move the helper to a shared module both scripts import.
Context
Flagged during review of #7136, which fixed the CI-path copy but deferred this one to keep PR scope tight.
Problem
There are two copies of
getSourceFromFrontmatterin the repo:scripts/lib/content-utils.js— fixed in feat(ci): add parse/compile code-block lint for PRs #7136scripts/docs-cli/lib/content-utils.js— still has the original bugsBoth copies should behave the same way. The docs-cli copy is used by
docs edit(viascripts/docs-cli/commands/edit.js) to find a shared source file when opening a consumer page. Its bugs are latent there but still real:Bugs in the docs-cli copy
Regex matches outside the frontmatter block.
content.match(/^source:\s*(.+)$/m)matches^source:anywhere in the file, so asource:key inside a fenced YAML example (for example, Docker Compose docs) gets treated as the page's shared source.docs editwill then try to open the wrong file.Only normalizes paths starting with
/. Frontmatter of the formsource: shared/foo.md(without a leading slash) is returned verbatim asshared/foo.md, which is a relative path that doesn't resolve from the caller's cwd.docs editeither fails or opens something unexpected.Fix
Port the fix from #7136 (commit 5241ff7a5) to the docs-cli copy:
---delimiters)./shared/...,shared/..., andcontent/shared/...consistently.nullfor unexpected shapes (absolute filesystem paths, URLs) rather than returning a misleading path.Longer term
The two copies are drift-prone. A follow-up refactor could consolidate on a single source of truth — either re-export from one location, or move the helper to a shared module both scripts import.
Context
Flagged during review of #7136, which fixed the CI-path copy but deferred this one to keep PR scope tight.