fix(tutorials): resolve rendering and consistency issues across tutorials - #327
Merged
Merged
Conversation
petermuessig
force-pushed
the
fix/tutorial-rendering-consistency
branch
from
August 12, 2026 04:59
bed3e60 to
0e3b8c4
Compare
…ials - build: copy each tutorial's top-level assets/ folder into dist/<tutorial>/assets/ so root README images (navigation, databinding) no longer 404 on GitHub Pages - navigation/odatav4/databinding: remove backticks from file-path headings that rendered as gray code spans, and shift the heading hierarchy down one level to match the walkthrough/quickstart outline (fence-aware; i18n code comments untouched) - walkthrough: replace project-structure screenshots in steps 09/26/27/28 with fenced ASCII folder trees, and delete the now-unused screenshot PNGs - quickstart: fix steps 02/03 headings to use the .ts/.js dual notation
petermuessig
force-pushed
the
fix/tutorial-rendering-consistency
branch
from
August 12, 2026 05:12
0e3b8c4 to
c170987
Compare
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
2 participants
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.
Summary
Fixes four rendering/consistency issues found while reviewing the published tutorials (GitHub Pages + github.com).
1. Root tutorial images 404 on GitHub Pages
The build script (
tools/builder/prepare-gh-pages.js) copied rootassets/and per-stepsteps/*/assets/**intodist/, but never a tutorial's top-levelassets/folder. Sodist/<tutorial>/index.mdreferencedassets/…pngthat was never published. Added a copy block (mirroring the existing root-assets logic, guarded byexistsSync).Affected: navigation ("Page flow of the final app") and databinding (root preview image) — the two tutorials with a top-level
assets/.2. Backticked file-path headings rendered as gray code spans
navigation,odatav4, anddatabindingwrapped file-path headings in backticks (e.g.## `webapp/Component.ts/.js`), which renders as a monospace/gray code span. Removed the backticks from all file-path headings, and shifted the heading hierarchy down one level so these tutorials now match thewalkthrough/quickstartoutline (## Step N→### Preview/### Coding→ file headings). The transform is fence-aware, so#-prefixed comment lines inside i18n.properties code blocks are untouched. The.ts/.jsdual-extension token and(New)/(Changed)suffixes are preserved.3. Walkthrough still used screenshots for project structure
Steps 09, 26, 27, 28 showed the folder structure as PNG screenshots. Replaced them with fenced ASCII folder trees (matching the other tutorials), derived from each step's actual
webapp/contents. Unused PNGs are removed.4. Quickstart heading missing
.ts/.jsSteps 02 and 03 had
### webapp/App.controller.js(JS-only) though the code blocks below provide both. Changed to### webapp/App.controller.ts/.js.Verification
assets/.grepconfirms no backticked path headings remain and no folder-structure screenshots remain in walkthrough.Note
The full builder (
node tools/builder, which runsui5 buildper step) was not run locally. Worth a CI/preview check before merge.