Add table of contents scope management and refactor diagnostics by Mpdreamz · Pull Request #774 · elastic/docs-builder

Mpdreamz · 2025-03-19T09:19:28Z

Introduced ITableOfContentsScope to manage scope boundaries, improving link validation and table of contents processing. Updated diagnostics to emit hints for images outside the ToC scope and refactored functions for better reusability. Adjusted related tests and internal structures accordingly.

This attaches the scope (defining toc/docset.yml file)'s directory to MarkdownFile and others.

Use case for this is that we want to error when folks include content on a page that does not live in the scope directory.

Since the scope directory may be relocated by the assembler it will lead to breaks.

Implemented as a hint for now to not break anyones builds while we work to update all repositories.

cc @shainaraskas @colleenmcginnis @lcawl

Introduced `ITableOfContentsScope` to manage scope boundaries, improving link validation and table of contents processing. Updated diagnostics to emit hints for images outside the ToC scope and refactored functions for better reusability. Adjusted related tests and internal structures accordingly.

Copilot

Pull Request Overview

This PR introduces an interface to manage table of contents (ToC) scope and refactors several components to improve link processing, diagnostics, and overall code reusability.

Introduces ITableOfContentsScope and propagates it through configuration, file, and navigation objects.
Updates the link parser to emit hints for images referenced outside the ToC scope and refines diagnostic and detection rules logic.
Refactors naming and method signatures to support the new ToC scope management.

Reviewed Changes

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

Show a summary per file

File	Description
src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs	Added image scope check and updated ProcessLinkText signature for enhanced diagnostics.
docs/development/index.md	Added a sample image to validate ToC scope checking.
src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs	Implemented ITableOfContentsScope and refactored related toc configuration logic.
src/Elastic.Markdown/Diagnostics/ProcessorDiagnosticExtensions.cs	Centralized diagnostic emission by refactoring error/warning methods.
src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs	Updated to implement ITableOfContentsScope and pass scope to the toc configuration.
src/Elastic.Markdown/IO/MarkdownFile.cs	Revised ToC properties and integrated ScopeDirectory mutation.
src/Elastic.Markdown/IO/Configuration/ITocItem.cs	Modified ITocItem records to include ToC scope information.
src/Elastic.Markdown/IO/Navigation/DocumentationGroup.cs	Updated file reference handling to use the new toc scope.
src/Elastic.Markdown/Slices/HtmlWriter.cs	Adjusted ToC item retrieval to reference PageTableOfContent.
src/Elastic.Markdown/Extensions/DetectionRules/DetectionRulesReference.cs	Revised detection rule records to include the ToC scope.
src/Elastic.Markdown/Extensions/DetectionRules/DetectionRulesDocsBuilderExtension.cs	Modified instantiation of detection references to use configuration as the scope provider.

Files not reviewed (1)

tests/authoring/Directives/IncludeBlocks.fs: Language not supported

Comments suppressed due to low confidence (1)

src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs:197

Consider normalizing both 'file.Directory.FullName' and 'currentMarkdown.ScopeDirectory.FullName' (e.g., using Path.GetFullPath) to ensure consistent path comparisons across different platforms.

if (!file.Directory!.FullName.StartsWith(currentMarkdown.ScopeDirectory.FullName + Path.DirectorySeparatorChar))

reakaleek

LGTM

reakaleek · 2025-03-19T09:21:05Z

src/Elastic.Markdown/IO/MarkdownFile.cs

 		var toc = GetAnchors(_set, MarkdownParser, YamlFrontMatter, document, subs, out var anchors);

-		_tableOfContent.Clear();
+		_pageTableOfContent.Clear();


While reading some navigation UX patterns I encountered the the term "On Page Table of Contents", which I think is very clear.

I think it removes a lot of ambiguity, since in the HTML it also says "On this page"

…encing-out-of-scope

* Add table of contents scope management and refactor diagnostics Introduced `ITableOfContentsScope` to manage scope boundaries, improving link validation and table of contents processing. Updated diagnostics to emit hints for images outside the ToC scope and refactored functions for better reusability. Adjusted related tests and internal structures accordingly. * Add TODO to make this an error * post merge build fixes

* Add global navigation and improve diagnostic handling This commit introduces a GlobalNavigation feature, parsing the new `navigation.yml` file to handle global navigation references. It also replaces `BuildContext` with `DiagnosticsCollector` for diagnostics, ensuring clearer separation of concerns. Additionally, it includes new tests and updates project files for better testing and navigation handling. * Use navigation.yml to control url path prefixes for resolving * path_prefix is mandatory except for top level docs-content references * stage commit * stage commit * File copy now in a decent place * temporary home for in flux paths * fix failing test * remove not referenced test project * Restrict docset.yml configs that define toc.yml sections to ONLY link to sub toc.yml files (#767) * Restrict docset.yml configs that define toc.yml sections to ONLY link to sub toc.yml files * relax check for narrative docs too, plays by different rules * dotnet format * reference Project directly * Fix layout and horizontal scrollable tables (#772) * Fix layout and horizontal scrollable tables mend * Use spacing var * Add custom scrollbar * tweaks * Add table of contents scope management and refactor diagnostics (#774) * Add table of contents scope management and refactor diagnostics Introduced `ITableOfContentsScope` to manage scope boundaries, improving link validation and table of contents processing. Updated diagnostics to emit hints for images outside the ToC scope and refactored functions for better reusability. Adjusted related tests and internal structures accordingly. * Add TODO to make this an error * post merge build fixes * good enough state --------- Co-authored-by: Jan Calanog <jan.calanog@elastic.co>

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

Miscellaneous docs clean up including: * [x] Removing unused substitutions * [x] Moving images per elastic/docs-builder#774 * [x] ~~Clean up redirecting links~~ * [x] ~~Fix remaining asciidoc-style links~~

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

Miscellaneous docs clean up including: * [x] Removing unused substitutions * [x] Moving images per elastic/docs-builder#774 * [x] ~~Clean up redirecting links~~ * [x] ~~Clean up asciidoc-style links~~

Miscellaneous docs clean up including: * [x] Removing unused substitutions * [x] Moving images per elastic/docs-builder#774 * [x] ~~Clean up redirecting links~~ * [x] ~~Clean up asciidoc-style links~~ (cherry picked from commit 5e5aff3)

Miscellaneous docs clean up including: * [x] Removing unused substitutions * [x] Moving images per elastic/docs-builder#774 * [x] Clean up redirecting links * [x] ~~Clean up asciidoc-style links~~

Miscellaneous docs clean up including: * [x] Removing unused substitutions * [x] Moving images per elastic/docs-builder#774 * [x] ~~Clean up redirecting links~~ * [x] ~~Clean up asciidoc-style links~~

Copilot AI review requested due to automatic review settings March 19, 2025 09:19

Mpdreamz requested a review from a team as a code owner March 19, 2025 09:19

Mpdreamz added the feature label Mar 19, 2025

Mpdreamz self-assigned this Mar 19, 2025

Add TODO to make this an error

621e2a0

Copilot AI reviewed Mar 19, 2025

View reviewed changes

reakaleek approved these changes Mar 19, 2025

View reviewed changes

Mpdreamz added 2 commits March 19, 2025 10:27

Merge remote-tracking branch 'origin/main' into feature/warn-on-refer…

5bf611e

…encing-out-of-scope

post merge build fixes

c631d05

Mpdreamz merged commit de857f7 into main Mar 19, 2025
10 checks passed

Mpdreamz deleted the feature/warn-on-referencing-out-of-scope branch March 19, 2025 09:35

Mpdreamz mentioned this pull request Mar 19, 2025

feature/assembler global toc #770

Merged

colleenmcginnis pushed a commit to elastic/docs-content that referenced this pull request Mar 20, 2025

[manage data] Move images (#864)

b7d0635

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

florent-leborgne pushed a commit to elastic/docs-content that referenced this pull request Mar 21, 2025

[explore analyze] Move images (#866)

70151e9

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

colleenmcginnis pushed a commit to elastic/docs-content that referenced this pull request Mar 21, 2025

[deploy manage] Move images (#867)

568b4eb

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

colleenmcginnis pushed a commit to elastic/docs-content that referenced this pull request Mar 21, 2025

[troubleshooting] Move images (#861)

5990708

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

colleenmcginnis pushed a commit to elastic/docs-content that referenced this pull request Mar 21, 2025

[solutions] Move images (#862)

0d95022

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

mergify bot mentioned this pull request Mar 21, 2025

[9.0] [docs] Miscellaneous docs clean up (backport #17372) elastic/logstash#17383

Merged

3 tasks

colleenmcginnis pushed a commit to elastic/docs-content that referenced this pull request Mar 21, 2025

[raw migrated files] Move images (#863)

0552db8

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

colleenmcginnis pushed a commit to elastic/docs-content that referenced this pull request Mar 24, 2025

[get started] Move images (#865)

3d2815f

Moves images per elastic/docs-builder#774 in preparation for docs-assembler.

mergify bot mentioned this pull request Mar 26, 2025

[9.0](backport #43370) [docs] Miscellaneous docs clean up elastic/beats#43492

Merged

4 tasks

colleenmcginnis mentioned this pull request Mar 27, 2025

[docs] Miscellaneous docs clean up elastic/apm-agent-android#411

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add table of contents scope management and refactor diagnostics#774

Add table of contents scope management and refactor diagnostics#774
Mpdreamz merged 4 commits intomainfrom
feature/warn-on-referencing-out-of-scope

Mpdreamz commented Mar 19, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

reakaleek left a comment

Uh oh!

reakaleek Mar 19, 2025

Uh oh!

reakaleek Mar 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Mpdreamz commented Mar 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

reakaleek left a comment

Choose a reason for hiding this comment

Uh oh!

reakaleek Mar 19, 2025

Choose a reason for hiding this comment

Uh oh!

reakaleek Mar 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Mpdreamz commented Mar 19, 2025 •

edited

Loading