Repository navigation
Add the HTML and CSS preview block - #243
Merged
Merged
Conversation
A lesson can write a fenced `preview` block and the reader draws it as a
small browser window, with the code beside it (split) or hidden (preview).
Optional sliders and dropdowns fill {{name}} placeholders in the HTML and
CSS, so a learner can change one value and see the result and the code
change together.
The example is drawn in an iframe with sandbox="" and a default-src
'none' content policy, with links switched off. The source is refused when
it contains script tags, event attributes, embedded content, link, meta,
base, @import, javascript: addresses or web addresses. An invalid fence
fails when the course is validated.
Adds the spec and remark plugin (shared), the HtmlPreview block (web and
desktop through the shared lesson blocks), the allowlist entry, the course
source validator hook, unit tests, and a short doc.
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.
What this adds
A lesson can write a fenced
previewblock, and the reader draws it as a small browser window with real HTML and CSS. The code can sit beside it (mode: split, with a Hide code button) or be hidden (mode: preview). Optional sliders and dropdowns fill{{name}}placeholders in the code, so a learner changes one value and sees the code and the result change together.It is built for the CSS Fundamentals and HTML Foundations courses (53 examples between them, already merged in
devweekends/Edorax-coreas plain fences) and works for any course. Full syntax:docs/html-preview-block.md.How it is built
server/src/shared/html-preview/spec.ts(shared): parses the fence, checks it, fills placeholders, builds the frame document.server/src/shared/mdx/remark-html-preview.ts(shared): turns the fence into anHtmlPreviewelement. It is added toreaderRemarkPlugins, so web and desktop get it. An invalid fence throws, so it fails when the course is validated.packages/learning-ui/.../content-blocks/html-preview.tsx: the block, registered insharedLessonBlocksand the MDX allowlist.server/scripts/validate-course-source.tsruns the plugin too.pnpm sync-shared.Safety
The example is read-only author content, never learner input. The frame uses
sandbox=""(no scripts, forms, popups or same-origin access), a content policy ofdefault-src 'none'(no network, only inline styles anddata:images), and links are switched off. The source is also refused if it has script tags,on...=attributes, iframe, link, meta, base,@import,javascript:addresses or web addresses insrc,hreforurl(). The check runs when the course is parsed and again when the block is drawn; a refused example shows a plain message instead of a frame.Tests
tests/unit/shared/mdx/html-preview.test.ts(parsing, controls, forbidden content, templates, frame document, remark plugin, registration). All 356 shared unit tests pass;pnpm sync-shared:checkand the server type check are clean.tests/unit/mdx/html-preview.test.ts(sandbox attribute, policy, controls, preview-only mode, refusal) and the existing allowlist-in-step test pass.tests/unit/shared/mdx/remark-learning-log.test.ts, fails to start in a fresh checkout because the generated Prisma client file is missing. It is not touched by this change.Not done