Add table of contents scope management and refactor diagnostics #774
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
There was a problem hiding this comment.
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
approved these changes
Mar 19, 2025
| @@ -224,9 +230,9 @@ protected void ReadDocumentInstructions(MarkdownDocument document) | |||
|
|
|||
| var toc = GetAnchors(_set, MarkdownParser, YamlFrontMatter, document, subs, out var anchors); | |||
|
|
|||
| _tableOfContent.Clear(); | |||
| _pageTableOfContent.Clear(); | |||
There was a problem hiding this comment.
While reading some navigation UX patterns I encountered the the term "On Page Table of Contents", which I think is very clear.
There was a problem hiding this comment.
I think it removes a lot of ambiguity, since in the HTML it also says "On this page"
Mpdreamz
added a commit
that referenced
this pull request
Mar 19, 2025
* 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
Mpdreamz
added a commit
that referenced
this pull request
Mar 19, 2025
* 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 <[email protected]>
This was referenced Mar 20, 2025
This was referenced Mar 20, 2025
colleenmcginnis
added a commit
to elastic/docs-content
that referenced
this pull request
Mar 20, 2025
Moves images per elastic/docs-builder#774 in preparation for docs-assembler.
This was referenced Mar 20, 2025
florent-leborgne
pushed a commit
to elastic/docs-content
that referenced
this pull request
Mar 21, 2025
Moves images per elastic/docs-builder#774 in preparation for docs-assembler.
colleenmcginnis
added a commit
to elastic/docs-content
that referenced
this pull request
Mar 21, 2025
Moves images per elastic/docs-builder#774 in preparation for docs-assembler.
colleenmcginnis
added a commit
to elastic/docs-content
that referenced
this pull request
Mar 21, 2025
Moves images per elastic/docs-builder#774 in preparation for docs-assembler.
colleenmcginnis
added a commit
to elastic/docs-content
that referenced
this pull request
Mar 21, 2025
Moves images per elastic/docs-builder#774 in preparation for docs-assembler.
3 tasks
colleenmcginnis
added a commit
to elastic/docs-content
that referenced
this pull request
Mar 21, 2025
Moves images per elastic/docs-builder#774 in preparation for docs-assembler.
colleenmcginnis
added a commit
to elastic/ecs-dotnet
that referenced
this pull request
Mar 24, 2025
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~~
colleenmcginnis
added a commit
to elastic/docs-content
that referenced
this pull request
Mar 24, 2025
Moves images per elastic/docs-builder#774 in preparation for docs-assembler.
colleenmcginnis
added a commit
to elastic/kibana
that referenced
this pull request
Mar 25, 2025
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~~
kibanamachine
pushed a commit
to kibanamachine/kibana
that referenced
this pull request
Mar 25, 2025
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)
colleenmcginnis
added a commit
to elastic/apm-agent-dotnet
that referenced
this pull request
Mar 25, 2025
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~~
4 tasks
4 tasks
cqliu1
pushed a commit
to cqliu1/kibana
that referenced
this pull request
Mar 31, 2025
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~~
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Introduced
ITableOfContentsScopeto 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
MarkdownFileand 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