Build fails when filename contains _snippets

[leemthompo]

Files with _snippets in the filename (e.g. top_snippets.md) cause build failures, presumably because the build logic treats any path containing _snippets as an include-only snippets directory.

Expected behavior

Only _snippets/ directories should be treated specially, not files that happen to contain _snippets in their name.

Workaround

Rename files to kebab case (e.g. top-snippets.md).

Reference

• elastic/elasticsearch@73c9d59

[reakaleek]

I guess the easiest would be to change the detection to /_snippets

[technige]

@reakaleek I assume this is on hold for now? Should we put it back in the backlog?

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

Files whose name merely contains the substring _snippets (e.g. top_snippets.md) are misclassified as include-only snippets, which fails the build instead of rendering them as pages.

Findings

• src/Elastic.Markdown/IO/MarkdownFileFactory.cs:120 — if (relativePath.Contains("_snippets")) returns a SnippetFile for any path containing the substring anywhere, so top_snippets.md (a legitimate page name) is treated as a snippet rather than as content. This is the root cause.
• src/Elastic.Markdown/IO/DocumentationFile.cs:43 — SnippetFile is a DocumentationFile but not a MarkdownFile, so MarkdownFileFactory.TryCreateDocumentationFile (MarkdownFileFactory.cs:71-77) returns null for it.
• src/Elastic.Documentation.Navigation/Isolated/Node/DocumentationSetNavigation.cs:204-206 — when that file is referenced in the TOC, navigation can't materialize a page and emits a hard error: File navigation '{relativePath}' could not be created. → the build fails. This is the symptom in the title.
• src/Elastic.Markdown/Myst/Directives/Include/IncludeBlock.cs:96 — the include side has the same substring bug: file.Directory.FullName.IndexOf("_snippets", …) matches any ancestor path containing the substring, not just real _snippets/ folders.
• Still reproduces on main (HEAD 576e12b3): line 120 above is unchanged. The maintainer-suggested fix in-thread ("change the detection to /_snippets") is not merged.

Verdict

Quick fix

This is a contained, uncontentious bug: the snippet-folder convention should be matched on a path-segment / directory boundary, not as a free substring. The change touches two files plus a test, doesn't alter rendered HTML, config schema, author syntax, or the CLI, and has obvious test coverage. Note that an open PR already implements exactly the agreed approach — see below — so the remaining work is mostly review + merge, not new code.

Proposal

Narrow the snippet detection to a directory boundary in both places:

• MarkdownFileFactory.CreateMarkDownFile (MarkdownFileFactory.cs:120): match {sep}_snippets{sep} or a leading _snippets{sep} instead of Contains("_snippets").
• IncludeBlock (IncludeBlock.cs:96): split the directory path on the separator and check for a _snippets segment rather than a substring.
• Add cases to tests/Elastic.Markdown.Tests/OutputDirectoryTests.cs covering top_snippets.md (renders as a page) vs _snippets/foo.md (treated as snippet).

PR #2743 (commit bdd40d50, 2026-02-19, head copilot/fix-build-failure-snippets) already does precisely this. It is open, not merged, reviewDecision: REVIEW_REQUIRED; build/integration checks are green but the check-labels check is failing (missing a release-drafter label). reakaleek + technige discussed whether it was on hold (last activity 2026-05-18). Picking it back up, adding the missing label, and merging would close this.

Related issues

Distinct from the snippets/includes feature cluster (#2420 cross-repo snippets, #712 cross-repo code samples, #1202 include directive — all open) — this is a narrow path-matching bug, not part of that feature work. No duplicate found.

Notes

• Suggested label additions applied by this triage: ai:quick-fix.
• The fix already exists in open PR Fix: files with _snippets in their name incorrectly treated as snippet-only files #2743; if it's truly stalled, a maintainer may prefer to re-home/rebase it rather than re-implement.