Feature Request: HTML Fragment Mode for Embedding #46
Description
Feature Request: HTML Fragment Mode for Embedding
Use Case
I'm building an automated PR review system that generates comprehensive HTML reports containing multiple file diffs. Currently, roslyn-diff generates complete HTML documents (with <html>, <head>, <body> tags), which makes embedding them into larger reports challenging.
Proposed Solution
Add a --html-mode option to output just the diff content without the HTML document wrapper:
roslyn-diff diff old.cs new.cs --html output.html --html-mode fragmentModes
1. document (default) - Current behavior
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Diff: old.cs → new.cs</title>
<style>/* styles */</style>
<script>/* scripts */</script>
</head>
<body>
<div class="diff-container">
<!-- diff content -->
</div>
</body>
</html>2. fragment (new) - Embeddable content only
<div class="roslyn-diff-container" data-old-file="old.cs" data-new-file="new.cs">
<!-- diff content, same as current body content -->
<!-- All styles scoped or included inline -->
<!-- All scripts included inline if needed -->
</div>Design Requirements
CSS Handling
Fragment mode should include styles in one of these ways:
Option A: Inline styles (safest for embedding)
<div class="roslyn-diff-container" style="...">
<div class="diff-header" style="...">
...
</div>
</div>Option B: Scoped style block (cleaner)
<style>
.roslyn-diff-container { /* scoped styles */ }
.roslyn-diff-container .diff-header { /* ... */ }
</style>
<div class="roslyn-diff-container">
...
</div>Option C: Configurable (most flexible)
--html-mode fragment --fragment-style-mode inline
--html-mode fragment --fragment-style-mode scoped
--html-mode fragment --fragment-style-mode external # Assumes parent doc has stylesJavaScript Handling
If the diff view includes interactive features:
- Inline all necessary scripts in the fragment
- Use namespaced/scoped functions to avoid conflicts
- Or make scripts optional with
--fragment-include-scripts
Data Attributes
Add metadata attributes for parent document use:
<div class="roslyn-diff-container"
data-old-file="old.cs"
data-new-file="new.cs"
data-changes-count="12"
data-breaking-public="2"
data-breaking-internal="1"
data-non-breaking="7"
data-formatting="2">Benefits
- Easy Embedding: Parent HTML can include multiple file diffs without iframe overhead
- Consistent Styling: Parent document controls overall layout while diff content remains styled
- Better UX: Smoother scrolling, unified navigation, no iframe quirks
- CI/CD Integration: Easier to build composite reports from multiple diffs
- Static Site Generation: Can be embedded in documentation generators
Example Usage
# Generate embeddable fragments for PR review
for file in changed_files; do
roslyn-diff diff \
target-branch/$file \
source-branch/$file \
--html fragments/${file}.html \
--html-mode fragment \
--fragment-style-mode scoped
done
# Combine into report
cat > report.html <<EOF
<!DOCTYPE html>
<html>
<head><title>PR Review</title></head>
<body>
<h1>PR #1234 Review</h1>
$(cat fragments/*.html)
</body>
</html>
EOFAlternative Workarounds (Current)
Currently working around this by:
- Iframe embedding - Works but has scrolling/sizing issues
- HTML parsing - Extract
<body>content and re-inject styles - Full documents - Link to separate pages instead of embedding
All have tradeoffs. Native fragment support would be cleaner.
Backward Compatibility
- Keep
documentas default mode - Only affects output when explicitly requested
- No changes to JSON/text/git output formats
Implementation Suggestions
Could be as simple as:
- Add
--html-mode {document|fragment}flag - In HTML generation, conditionally skip
<html>,<head>,<body>wrappers - Ensure styles/scripts are appropriately included for standalone rendering
- Add data attributes with summary metadata
Related Use Cases
- Multi-file PR reviews - Combine multiple semantic diffs in one report
- Documentation sites - Embed diffs in API migration guides
- CI reports - Aggregate diffs across multiple changed files
- Code review tools - Build custom UI around roslyn-diff output
This would make roslyn-diff even more useful for automated code review workflows! Let me know if you'd like me to submit a PR for this feature.