Interactive examples in the docs - #193
Conversation
Marko code fences tagged with a playground modifier now render as runnable, editable examples directly in the docs, with consecutive fences forming multi-file examples. Demonstrated throughout the Components and Reactivity tutorial.
|
PR Preview DeployedYour changes are live at markojs.com/previews/pr-193. commit 2109050 |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
WalkthroughThe Markdown pipeline now compiles learn pages, manifests, checkpoints, and grouped 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agent-feedback/bugs.md`:
- Line 5: Shorten the bugs.md heading for the let-debounce return-value issue to
a concise 1–3 word title, such as “Return Binding,” while preserving the
detailed failure description in the body.
In `@src/tags/app-playground/app-playground.marko`:
- Around line 34-44: Update the dynamic import failure handler in app-playground
to store the rejected error in component state instead of only clearing loading.
Render that error through an alert or retry affordance in the playground UI,
while preserving the successful Live assignment and loading-state behavior.
In `@src/tags/app-playground/app-playground.style.scss`:
- Around line 32-35: Update both svg rules in
src/tags/app-playground/app-playground.style.scss at lines 32-35 and 55-58,
changing the fill value from currentColor to currentcolor to satisfy the
configured Stylelint value-keyword-case rule.
In `@src/tags/app-playground/tags/open-in-playground.marko`:
- Around line 8-18: Update the hash-generation logic in the script block to
clear or disable the playground link while compression is pending, preventing
navigation with an empty hash. Add a cancellation token or revision counter so
each compress completion only updates hash if it still corresponds to the latest
input.files, and invalidate prior work when the signal aborts or a new hash
starts.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 2c56b038-486a-4bde-a1c4-1616c4c34432
📒 Files selected for processing (9)
agent-feedback/bugs.mdcspell.jsondocs/tutorial/components-and-reactivity.mdsrc/tags/app-playground/app-playground.markosrc/tags/app-playground/app-playground.style.scsssrc/tags/app-playground/tags/embed-result.markosrc/tags/app-playground/tags/open-in-playground.markosrc/tags/app-playground/tags/playground-live.markosrc/util/markodown.ts
|
|
||
| Out-of-scope defects noticed while working on something else. Format and rules: [README.md](README.md). | ||
|
|
||
| ## `<let-debounce>` return value never flows when client-rendered without server markup |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Shorten the heading.
Use a 1-3 word heading, such as ## Return Binding; retain the detailed failure description in the body. As per coding guidelines, headings must be 1-3 words maximum.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agent-feedback/bugs.md` at line 5, Shorten the bugs.md heading for the
let-debounce return-value issue to a concise 1–3 word title, such as “Return
Binding,” while preserving the detailed failure description in the body.
Source: Coding guidelines
| loading = true; | ||
| import("./tags/playground-live.marko").then( | ||
| (live) => { | ||
| deactivate?.(); | ||
| deactivate = () => (Live = null); | ||
| Live = live.default; | ||
| loading = false; | ||
| }, | ||
| () => { | ||
| loading = false; | ||
| }, |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Surface live-editor load failures.
A rejected dynamic import only clears loading; the failed action has no feedback. Store an error and render an alert or retry affordance.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/tags/app-playground/app-playground.marko` around lines 34 - 44, Update
the dynamic import failure handler in app-playground to store the rejected error
in component state instead of only clearing loading. Render that error through
an alert or retry affordance in the playground UI, while preserving the
successful Live assignment and loading-state behavior.
| svg { | ||
| height: 0.9em; | ||
| fill: currentColor; | ||
| } |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Resolve the Stylelint keyword-case errors.
currentColor is rejected by the configured value-keyword-case rule, so lint will fail.
src/tags/app-playground/app-playground.style.scss#L32-L35: changefill: currentColortofill: currentcolor.src/tags/app-playground/app-playground.style.scss#L55-L58: changefill: currentColortofill: currentcolor.
🧰 Tools
🪛 Stylelint (17.14.0)
[error] 34-34: Expected "currentColor" to be "currentcolor" (value-keyword-case)
(value-keyword-case)
📍 Affects 1 file
src/tags/app-playground/app-playground.style.scss#L32-L35(this comment)src/tags/app-playground/app-playground.style.scss#L55-L58
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/tags/app-playground/app-playground.style.scss` around lines 32 - 35,
Update both svg rules in src/tags/app-playground/app-playground.style.scss at
lines 32-35 and 55-58, changing the fill value from currentColor to currentcolor
to satisfy the configured Stylelint value-keyword-case rule.
Source: Linters/SAST tools
| let/hash="" | ||
| script -- | ||
| const timeout = setTimeout(() => { | ||
| compress(JSON.stringify(input.files)).then((h) => (hash = h)); | ||
| }, 500); | ||
| $signal.onabort = () => clearTimeout(timeout); | ||
|
|
||
| a.playground-embed-open | ||
| ,href=`${import.meta.env.BASE_URL}playground${hash && `#${hash}`}` | ||
| ,target="_blank" | ||
| ,rel="noopener" |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Prevent empty and stale playground hashes.
Before hashing completes, the link opens a blank workspace. Also, an older compress() promise can resolve after newer files and overwrite hash. Clear or disable the link while hashing and guard completions with a cancellation token or revision counter.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/tags/app-playground/tags/open-in-playground.marko` around lines 8 - 18,
Update the hash-generation logic in the script block to clear or disable the
playground link while compression is pending, preventing navigation with an
empty hash. Add a cancellation token or revision counter so each compress
completion only updates hash if it still corresponds to the latest input.files,
and invalidate prior work when the signal aborts or a new hash starts.
Lessons under learn/ are plain markdown ordered by filename prefix. They render at /learn with prose on the left and a persistent editor and preview on the right; playground fences become checkpoints that load their files into the shared workspace, with the first group loading automatically.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@learn/1-basics/1-templates.md`:
- Line 1: Add a `> [!TLDR]` callout containing 2–4 concise lesson-summary
bullets before the introduction in learn/1-basics/1-templates.md (line 1),
learn/1-basics/2-dynamic-content.md (line 1), learn/1-basics/3-state.md (line
1), and learn/1-basics/4-components.md (line 1); keep each summary specific to
its lesson.
In `@learn/1-basics/4-components.md`:
- Around line 21-25: Update the rating button markup in the component to add a
dynamic aria-label describing its rating value and an aria-pressed attribute
reflecting whether i is selected based on input.value. Preserve the existing
star rendering and valueChange behavior.
In `@src/tags/learn-checkpoint/learn-checkpoint.style.scss`:
- Around line 45-48: Update the SVG rules in
src/tags/learn-checkpoint/learn-checkpoint.style.scss lines 45-48 and
src/routes/learn/+layout.style.scss lines 50-53 to use the lowercase fill
keyword currentcolor instead of currentColor, resolving the configured Stylelint
value-keyword-case errors.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 05aea3ae-723c-4832-ae1c-82fa1f600a19
📒 Files selected for processing (15)
cspell.jsonlearn/1-basics/1-templates.mdlearn/1-basics/2-dynamic-content.mdlearn/1-basics/3-state.mdlearn/1-basics/4-components.mdpackage.jsonsrc/routes/learn/+handler.tssrc/routes/learn/+layout.markosrc/routes/learn/+layout.style.scsssrc/tags/app-playground/app-playground.style.scsssrc/tags/app-playground/tags/embed-result.style.scsssrc/tags/learn-checkpoint/learn-checkpoint.markosrc/tags/learn-checkpoint/learn-checkpoint.style.scsssrc/util/learn-files.tssrc/util/markodown.ts
| @@ -0,0 +1,36 @@ | |||
| # Templates Are HTML | |||
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add TLDR callouts to all new lessons.
Each lesson begins without the required > [!TLDR] block.
learn/1-basics/1-templates.md#L1-L1: add a 2-4 bullet TLDR before the introduction.learn/1-basics/2-dynamic-content.md#L1-L1: add a 2-4 bullet TLDR before the introduction.learn/1-basics/3-state.md#L1-L1: add a 2-4 bullet TLDR before the introduction.learn/1-basics/4-components.md#L1-L1: add a 2-4 bullet TLDR before the introduction.
As per coding guidelines, tutorial documents include a TLDR section. Based on learnings, Markdown files use the > [!TLDR] format.
📍 Affects 4 files
learn/1-basics/1-templates.md#L1-L1(this comment)learn/1-basics/2-dynamic-content.md#L1-L1learn/1-basics/3-state.md#L1-L1learn/1-basics/4-components.md#L1-L1
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@learn/1-basics/1-templates.md` at line 1, Add a `> [!TLDR]` callout
containing 2–4 concise lesson-summary bullets before the introduction in
learn/1-basics/1-templates.md (line 1), learn/1-basics/2-dynamic-content.md
(line 1), learn/1-basics/3-state.md (line 1), and learn/1-basics/4-components.md
(line 1); keep each summary specific to its lesson.
Sources: Coding guidelines, Learnings
| <button onClick() { | ||
| input.valueChange?.(i); | ||
| }> | ||
| ${i <= input.value ? "★" : "☆"} | ||
| </button> |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make the rating controls accessible.
Each button exposes only a star glyph, so assistive technology receives neither an accessible name nor the selected state. Add a dynamic aria-label and aria-pressed.
Suggested fix
<for|i| from=1 to=5>
- <button onClick() {
+ <button
+ aria-label=`Set rating to ${i} out of 5`
+ aria-pressed=(i <= input.value)
+ onClick() {
input.valueChange?.(i);
}>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <button onClick() { | |
| input.valueChange?.(i); | |
| }> | |
| ${i <= input.value ? "★" : "☆"} | |
| </button> | |
| <button | |
| aria-label=`Set rating to ${i} out of 5` | |
| aria-pressed=(i <= input.value) | |
| onClick() { | |
| input.valueChange?.(i); | |
| }> | |
| ${i <= input.value ? "★" : "☆"} | |
| </button> |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@learn/1-basics/4-components.md` around lines 21 - 25, Update the rating
button markup in the component to add a dynamic aria-label describing its rating
value and an aria-pressed attribute reflecting whether i is selected based on
input.value. Preserve the existing star rendering and valueChange behavior.
| svg { | ||
| height: 0.9em; | ||
| fill: currentColor; | ||
| } |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Resolve the Stylelint keyword-case errors.
The configured value-keyword-case rule rejects currentColor, causing lint to fail.
src/tags/learn-checkpoint/learn-checkpoint.style.scss#L45-L48: changefill: currentColortofill: currentcolor.src/routes/learn/+layout.style.scss#L50-L53: changefill: currentColortofill: currentcolor.
Proposed fix
- fill: currentColor;
+ fill: currentcolor;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| svg { | |
| height: 0.9em; | |
| fill: currentColor; | |
| } | |
| svg { | |
| height: 0.9em; | |
| fill: currentcolor; | |
| } |
🧰 Tools
🪛 Stylelint (17.14.0)
[error] 47-47: Expected "currentColor" to be "currentcolor" (value-keyword-case)
(value-keyword-case)
📍 Affects 2 files
src/tags/learn-checkpoint/learn-checkpoint.style.scss#L45-L48(this comment)src/routes/learn/+layout.style.scss#L50-L53
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/tags/learn-checkpoint/learn-checkpoint.style.scss` around lines 45 - 48,
Update the SVG rules in src/tags/learn-checkpoint/learn-checkpoint.style.scss
lines 45-48 and src/routes/learn/+layout.style.scss lines 50-53 to use the
lowercase fill keyword currentcolor instead of currentColor, resolving the
configured Stylelint value-keyword-case errors.
Source: Linters/SAST tools
1 participant
Two takes on interactive docs, both authored as plain markdown that reads normally on GitHub: examples in regular doc pages can opt into running live in place (see the Components and Reactivity tutorial), and a new guided flow at
/learnpairs each lesson with a persistent editor and preview. Try both in the preview deployment.