fix/lesson-content-styles - #118
Merged
Merged
Conversation
The lesson body looked unstyled next to the rest of the site: base.css only covered h1 to h3, p, a, img, and bare code, so everything else the Markdown produces (fenced code blocks, blockquotes, lists, tables, deep headings, horizontal rules) fell back to raw browser defaults. And since the sanitizer strips class attributes (ADR-0013), the rendered HTML can never carry BEM classes, so nothing class-based could ever reach it. The lesson template now wraps the content in a lesson-content block, and base.css styles it with element selectors scoped under that wrapper (a deliberate, documented BEM exception, the only mechanism the sanitized markup allows): code blocks become bordered cards that scroll horizontally instead of stretching the page (RGAA 10.11), inline code gets a chip, blockquotes an accent border, tables the house table look, lists and deep headings the site rhythm, with h4 to h6 joining the display typeface the global rule reserves for h1 to h3.
Pipe tables are a GFM extension, not core CommonMark, so a table typed in a lesson rendered as literal pipe-separated text; the fresh lesson-content table styles had nothing to apply to. ADR-0013 planned for exactly this: extensions join on demand, and a lesson demanded one. commonmark-ext-gfm-tables now plugs into the parser and the renderer; the sanitizer allowlist already lets table markup through, proven by the new renderer test asserting a pipe table survives rendering and sanitization as a real HTML table.
Lessons should render the alert/callout syntax GitHub and Obsidian share. ADR-0015 chooses the official commonmark-ext-gfm-alerts extension over a custom parser or a post-processing pass, accepts the commonmark 0.24.0 => 0.29.0 upgrade it forces, keeps the five GFM types on their GitHub identity while the Obsidian set joins with all aliases, ships octicons as CSS masks so no SVG crosses the sanitizer, and narrows the widened class allowlist with an exact-value second pass. Refs #116
The upcoming alerts extension (commonmark-ext-gfm-alerts) is version- locked to its same-version core, and its configuration API (custom types, custom titles, nested alerts) only exists in 0.29.0, so the whole commonmark stack moves up from 0.24.0 in one step. Changelog reviewed from 0.25.0 to 0.29.0: no API removals; the notable parser change is that GFM tables no longer require a preceding blank line. The full test suite (tables, heading demotion, render caching) stays green on the new version. Refs #116
Alert markers in lesson Markdown ("> [!note]") used to degrade into
plain blockquotes with the marker as literal text. The official
commonmark-ext-gfm-alerts extension now plugs into the parser and
renderer with every option enabled, as decided in ADR-0015.
Registered types: the five GFM types keep their GitHub identity
(IMPORTANT and CAUTION stay standalone), and the full Obsidian callout
set joins them with all aliases, 27 types in total, matched case-
insensitively. Custom titles are inline-parsed and nested alerts
render as alerts instead of degrading to literal text.
The sanitizer allowlist widens to admit class on div/p and
data-alert-type so the alert markup stays styleable, and a second
sanitization pass immediately narrows it: any class value the alert
renderer does not emit is stripped, so raw HTML in a lesson cannot
borrow site classes. Renderer tests cover default and custom titles,
aliases, nesting, and the class-spoofing case.
Refs #116
The alert markup from the previous commit carried classes with no styles behind them. The lesson-content section of base.css now styles markdown-alert blocks: an accent border and title color per type family, driven by the existing theme tokens so both themes work, and an Octicon per type (the icon set GitHub uses for alerts, matched against Obsidian's icon semantics). Icons ship as mask-image data URIs painted with currentColor, so the sanitized HTML never needs to carry SVG markup and the sanitizer allowlist stays free of SVG tags. Nested alerts inset with a margin and swap to the page background to stay visually distinct from their parent. All 27 registered type classes are covered. Fixes #116
A lesson whose Markdown starts with a level-1 heading equal to the lesson title rendered the same text twice: the page h1 (the title from the database) followed by an identical h2, the authored heading after ADR-0014's demotion. MarkdownRenderer gains a pure static, stripLeadingTitleHeading, that drops the first non-blank heading when it is a level-1 ATX heading (closing hashes tolerated) or a setext heading whose text equals the lesson title, trimmed and case-insensitive. The lesson route applies it before render() so the renderer stays cacheable by exact input and the stored Markdown is never modified. A heading with different text, or any deeper level, is kept as authored. The lesson form now hints that the page already shows the title, and ADR-0014 records the behavior as an amendment. Fixes #117
ebouchut
added
dependencies
backend
accessibility
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## dev #118 +/- ##
============================================
+ Coverage 80.33% 81.57% +1.24%
- Complexity 186 201 +15
============================================
Files 38 38
Lines 783 863 +80
Branches 42 53 +11
============================================
+ Hits 629 704 +75
- Misses 124 125 +1
- Partials 30 34 +4 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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
1 participant
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.
This PR make changes to the lessoned content and handles duplicate headings (do not generate the h1 page title when it is the same as the level-1 heading in the lesson Markdown).
It adds support for tables via a Common Markdown extension.
common-ext-gfm-alertsmaven dependency,commonmark-javato version0.29.0, which is required to use the alerts extension and related parser features.