Summary
Syntax highlighting may fail on the first server-loaded visit to a documentation page when Prism highlighting is initialized from wwwroot/js/syntax-highlight.js. Subsequent loads (for example, opening the same page in a new private window after the first visit) can behave differently, which suggests a timing or initialization issue rather than a straightforward duplicate-highlighting guard problem.
Background
During review of PR #20, we discussed preventing the MutationObserver from re-highlighting the same code blocks because Prism.highlightElement(...) mutates DOM nodes and can trigger the observer again. However, attempts to add guards or disconnect/reconnect logic appeared to interfere with the initial highlight pass on the first server-loaded page visit.
The current behavior does not appear to cause a measurable client-side performance issue, so this was treated as non-blocking for the PR and deferred for follow-up investigation.
Requested by: @Arctis-Fireblight
Affected areas
Redot-Documentation/wwwroot/js/syntax-highlight.jsRedot-Documentation/Components/Pages/DocViewer.razorRedot-Documentation/Components/App.razor- Prism asset loading and post-render highlight timing
Investigation goals
- Reproduce the "first server-loaded visit does not highlight" behavior consistently.
- Determine whether the root cause is:
- Prism asset load timing,
- Blazor render timing,
enhancedload/DOMContentLoaded sequencing,MutationObserver rescheduling,- or interaction between these factors.
- Identify a fix that avoids repeated self-triggered highlighting without suppressing the initial successful highlight pass.
Acceptance criteria
- Syntax highlighting works on the first server-loaded visit to a page containing code blocks.
- Syntax highlighting continues to work for dynamically loaded/enhanced-navigation content.
- The highlighting flow does not repeatedly reprocess already highlighted blocks due to its own DOM mutations.
- Any observer/guard logic is documented clearly enough to explain why it does not block first-load highlighting.
Backlinks
Summary
Syntax highlighting may fail on the first server-loaded visit to a documentation page when Prism highlighting is initialized from
wwwroot/js/syntax-highlight.js. Subsequent loads (for example, opening the same page in a new private window after the first visit) can behave differently, which suggests a timing or initialization issue rather than a straightforward duplicate-highlighting guard problem.Background
During review of PR #20, we discussed preventing the
MutationObserverfrom re-highlighting the same code blocks becausePrism.highlightElement(...)mutates DOM nodes and can trigger the observer again. However, attempts to add guards or disconnect/reconnect logic appeared to interfere with the initial highlight pass on the first server-loaded page visit.The current behavior does not appear to cause a measurable client-side performance issue, so this was treated as non-blocking for the PR and deferred for follow-up investigation.
Requested by: @Arctis-Fireblight
Affected areas
Redot-Documentation/wwwroot/js/syntax-highlight.jsRedot-Documentation/Components/Pages/DocViewer.razorRedot-Documentation/Components/App.razorInvestigation goals
enhancedload/DOMContentLoaded sequencing,MutationObserverrescheduling,Acceptance criteria
Backlinks