Restrict docset.yml configs that define toc.yml sections to ONLY link to sub toc.yml files

[Mpdreamz]

This introduces a restriction so that if a docset.yml file links to a toc.yml file it may ONLY link to toc.yml files.

This to ensure all folders can be homed by the assembler navigation.yml.

e.g elasticsearch's docset.yml defines:

toc:
  - toc: reference
  - toc: release-notes
  - toc: extend

and the navigation.yml injects them in various places using elasticsearch://reference

There is no valid home for any files that might be placed at the root e.g: elasticsearch://
this PR prevents people from adding such file and folder references.

This also introduces dev_docs configuration for documentation sets that never intend to publish through assembler like our docs-builder docs.

Enabling this relaxes this new toc only restriction.

cc @colleenmcginnis

[Copilot]

Pull Request Overview

This PR restricts docset.yml configurations so that toc.yml sections only link to sub toc.yml files, except when in development mode.

• Added a new "dev_docs" field in the docset configuration to denote development docs.
• Updated configuration parsing in ConfigurationFile.cs to enforce that, in non-development mode, TOC entries only reference toc sections.
• Introduced a new TocReference type (extending FolderReference) and modified TableOfContentsConfiguration.cs to return TocReference objects accordingly.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
docs/_docset.yml	Adds a "dev_docs: true" flag along with explanatory comments.
src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs	Introduces the DevelopmentDocs property and enforces stricter TOC linking rules depending on mode.
src/Elastic.Markdown/IO/Configuration/ITocItem.cs	Adds a new TocReference record to represent TOC-only references.
src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs	Changes the returned reference from FolderReference to TocReference for TOC sections.

Comments suppressed due to low confidence (2)

src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs:123

• [nitpick] Consider clarifying the error message emitted on line 124 for consistency and user clarity, e.g., by capitalizing 'TOC' to 'TOC'.

if (!DevelopmentDocs && tocEntries.Length > 0 && children.Count != tocEntries.Length)

src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs:115

• Ensure that changing the returned reference from FolderReference to TocReference does not break any downstream code assumptions, as this change alters the type contract for TOC referencing.

return [new TocReference(`${parentPath}`.TrimStart(Path.DirectorySeparatorChar), folderFound, inNav, toc.TableOfContents)];