fix: dedent <code> blocks in <example> elements before markdown rendering - #28
Merged
Merged
Conversation
…ring .Trim() on raw <code> element content only stripped the leading newline and first line's indentation as one contiguous block, leaving all subsequent lines carrying their original XML indentation (typically 16 spaces). This caused multi-line code blocks to render with line 1 flush-left and all remaining lines over-indented. Add DedentCode() helper that computes the minimum leading-whitespace across all non-blank lines, strips that prefix uniformly from every line, and removes leading/trailing blank lines. Replace both .Trim() calls on code content with DedentCode(): - el.Value.Trim() (no-<code>-children fallback path) - codeElement.Value.Trim() (mixed-content loop) Add five regression tests covering: uniform indent, mixed indent with preserved relative indentation, single-line code, blank lines in the middle, and the no-code-children fallback path. Update design and verification docs for XmlDocReader to describe the dedent algorithm and the new acceptance criteria. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves how XmlDocReader.GetExampleParts normalizes XML doc <example> content by dedenting multi-line <code> blocks before Markdown rendering, preventing over-indented lines caused by XML formatting whitespace.
Changes:
- Replace
.Trim()usage on extracted<code>text with a newDedentCode()helper for consistent multi-line dedentation. - Add regression tests covering uniform/mixed indentation, single-line code, blank lines, and the no-
<code>fallback path. - Update design/verification documentation and extend cspell dictionary for the new terminology.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
src/ApiMark.DotNet/XmlDocReader.cs |
Introduces DedentCode() and applies it to <code> blocks and the no-<code> fallback path in GetExampleParts. |
test/ApiMark.DotNet.Tests/XmlDocReaderTests.cs |
Adds 5 regression tests validating dedentation behavior and edge cases. |
docs/design/api-mark-dot-net/xml-doc-reader.md |
Documents the dedentation algorithm and where it is applied. |
docs/verification/api-mark-dot-net/xml-doc-reader.md |
Expands acceptance criteria and test scenarios for dedentation behavior. |
.cspell.yaml |
Adds “dedentation” and “dedented” to the project dictionary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
After stripping the common indent, lines that originally carried only indentation (more spaces than minIndent) could be left as whitespace- only strings rather than truly empty lines. This introduced trailing spaces into fenced code block output, contradicting the comment that blank lines are preserved as empty. Add a second .Select() pass that maps any whitespace-only line to string.Empty after the prefix-strip step. Add regression test: BlankLineWithExtraIndent_NormalizesToEmptyLine. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Jun 19, 2026
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
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.
.Trim() on raw
element content only stripped the leading newline and first line's indentation as one contiguous block, leaving all subsequent lines carrying their original XML indentation (typically 16 spaces). This caused multi-line code blocks to render with line 1 flush-left and all remaining lines over-indented.Add DedentCode() helper that computes the minimum leading-whitespace across all non-blank lines, strips that prefix uniformly from every line, and removes leading/trailing blank lines. Replace both .Trim() calls on code content with DedentCode():
-children fallback path)Add five regression tests covering: uniform indent, mixed indent with preserved relative indentation, single-line code, blank lines in the middle, and the no-code-children fallback path.
Update design and verification docs for XmlDocReader to describe the dedent algorithm and the new acceptance criteria.