Support anchors and table of contents from included files #585
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
If an included snippet defines it's own headers and anchors they did not contribute to the pages anchors and headers.
-- page.md
```markdown
:::{include} _snippet/snippet.md
:::
```
This resulted in link check failures to `page.md#included-from-snippet`, as well as the headers from a snippet not appearing on the page's table of contents.
This PR also extends our testing framework by allowing to collect data from the conversion using `IConversionCollector`.
The `authoring` test framework uses the same `DocumentationGenerator` that `docs-builder` uses. The default for `IConversionCollector` is `null` in real world usage as we don't want the added memory pressure.
An upside of this is that we can now really fully test the whole HTML layout vs just the markdown HTML.
Lastly this PR includes a tiny fix to DiagnosticLinkInlineParser.cs to always report the resolved path as the full path. That way folks don't need to parse all the parent up `../` instructions themselves when dealing with this error instance.
3 tasks
Mpdreamz
changed the title
reakaleek
approved these changes
Feb 24, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
If an included snippet defines it's own headers and anchors they did not contribute to the pages anchors and headers.
-- page.md
:::{include} _snippet/snippet.md :::This resulted in link check failures to
page.md#included-from-snippet, as well as the headers from a snippet not appearing on the page's table of contents.This PR also extends our testing framework by allowing to collect data from the conversion using
IConversionCollector.The
authoringtest framework uses the sameDocumentationGeneratorthatdocs-builderuses. The default forIConversionCollectorisnullin real world usage as we don't want the added memory pressure.An upside of this is that we can now really fully test the whole HTML layout vs just the markdown HTML.
Lastly this PR includes a tiny fix to DiagnosticLinkInlineParser.cs to always report the resolved path as the full path. That way folks don't need to parse all the parent up
../instructions themselves when dealing with this error instance.