docs(tutorials): rework TS/JS download links and add AGENTS.md#303
Merged
Conversation
Rework how JS/TS download links are structured across all step READMEs.
The old paired `<details class="ts-only|js-only" markdown="1">…</details>`
wrappers rendered as noisy collapsibles in the raw-markdown view (and to
AI tools indexing the corpus) and hid the "other language exists" signal.
Replace them with inline
`<span class="ts-only|js-only">…<span class="lang-suffix"> (TS|JS)</span></span>`:
both variants read plainly in raw markdown with distinct (TS)/(JS) labels,
while the rendered site still shows only the active language. Achieved with
no runtime JS change — the existing `.ts-only`/`.js-only` CSS hides the
inactive span and a new `.lang-suffix { display: none }` rule drops the
marker. Covers the per-step block form, the overview inline form, and the
two standalone-bundle links in navigation/odatav4 step 01.
Also add AGENTS.md (repo guide for AI agents: layout, conventions,
propagation rules, using the tutorials as a codegen source), document the
new `<span>` pattern in AGENTS.md and CONTRIBUTING.md, and refresh the
remaining README normalization plus packages/*/steps.json.
The one-off migration script lives under the gitignored `_/` folder.
The odatav4 step 03 and 05 headings read `webapp/manifest.ts/.js`on, a migration leftover where the `.js` inside `.json` was rewritten as the `.ts/.js` toggle token. Switching to TypeScript then rendered `manifest.tson`. The manifest filename is language-independent, so the headings are restored to `webapp/manifest.json`. Also harden replaceFileExtensions so the toggle only fires at a real extension boundary (`/\.ts\/\.js(?![A-Za-z0-9])/`), preventing any mis-tokenized longer extension from silently corrupting a filename.
…ink placement Add the Data Binding tutorial (packages/databinding/) as 15 runnable TypeScript steps aligned to repo conventions: ui5.tutorial.databinding namespace, OpenUI5 1.148.1, manifest v2, index-cdn.html, .ts/.js token with first-line path comments, JS twins for every TS fence, per-step Preview/Coding structure, and the <span> download-solution link form. Also normalize link placement across navigation and odatav4 so that the Live Preview link always sits in the Preview section and the download link in the Coding section (matching walkthrough/quickstart). Regenerate steps.json, extend the root README tutorial list, and update AGENTS.md to describe five tutorials.
Align all tutorials to OpenUI5: - Replace remaining "SAPUI5" wording with "OpenUI5" in navigation and odatav4 step READMEs and in navigation i18n appDescription strings. - Point doc/API links at the OpenUI5 SDK: rewrite ui5.sap.com/#/... to sdk.openui5.org/#/... and repair malformed sdk.openui5.org links that were missing the /#/ route (walkthrough step 03). - Normalize SDK topic links (full topic hashes, consistent /topic/ path). Project config was already OpenUI5-correct: every ui5.yaml uses framework OpenUI5 with OpenUI5-only libraries, and every package.json depends on @openui5/types.
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
This PR bundles three related tutorial-authoring changes on top of
main(after #295 landed): a rework of the JS/TS download links, a new Data Binding tutorial, a manifest-corruption fix in the TS/JS toggle, plus a repo-wideAGENTS.mdguide and Preview/Coding link normalization. ~285 files.1. Rework TS/JS download links
Each download link was wrapped in a paired
<details class="ts-only|js-only" markdown="1">…</details>. On the rendered site one is hidden; but in the raw-markdown view (GitHub blob, editors, AI tools indexing the corpus) both render as noisy collapsibles labelled identically (📥 Download Solution), with the language distinguishable only by the URL suffix.Replace the wrappers with inline spans:
… (TS)and… (JS).ts-only/.js-onlyCSS already hides the inactive span; a new.lang-suffix { display: none }rule drops the(TS)/(JS)marker on the rendered side.<details class="ts-only">blocks used for language-only prose are intentionally left untouched.2. New Data Binding tutorial
Add
packages/databinding/as 15 runnable TypeScript steps aligned to repo conventions:ui5.tutorial.databindingnamespace, OpenUI5 1.148.1, manifest v2,index-cdn.html,.ts/.jstoggle token with first-line path comments, JS twins for every TS fence, per-step Preview/Coding structure, and the new<span>download-solution link form. Registered in the rootREADME.mdtutorial list and regeneratedsteps.json.3. Fix manifest.json corruption on TS/JS switch
The odatav4 step 03 and 05 headings read
webapp/manifest.ts/.json — a migration leftover where the.jsinside.jsonwas rewritten as the.ts/.jstoggle token, so switching to TypeScript renderedmanifest.tson. The manifest filename is language-independent, so the headings are restored towebapp/manifest.json. Also hardenreplaceFileExtensions(assets/js/custom.js) so the toggle only fires at a real extension boundary (/\.ts\/\.js(?![A-Za-z0-9])/), preventing any mis-tokenized longer extension from silently corrupting a filename.Also included
AGENTS.md— repo guide for AI agents: layout, toolchain, authoring conventions, change-propagation rules, and how to use the tutorials as a codegen source (anchor on the last step, not the first). Documents the<span>link pattern (also mirrored inCONTRIBUTING.md) and now describes five tutorials.tools/builder/prepare-gh-pages.jsnow copies each tutorial'ssteps.jsoninto the dist output.packages/*/steps.jsonfor all affected tutorials.Verification
.?splaceholder absent, spans present in spot checks.-js.zipbundles confirmed present for the standalone-bundle links.🤖 Generated with Claude Code
4. OpenUI5 alignment (wording + doc links)
Ensure every tutorial consistently presents as OpenUI5 and points documentation at the OpenUI5 SDK.
SAPUI5mentions withOpenUI5in the navigation and odatav4 step READMEs and in the navigationi18n.propertiesappDescriptionstrings.sap.*control/class names are left as-is.https://ui5.sap.com/#/…→https://sdk.openui5.org/#/…, and repaired malformedsdk.openui5.org…links in walkthrough step 03 that were missing the/#/route./topic/path style.ui5.yamlalready usesframework: OpenUI5with OpenUI5-only libraries (sap.m,sap.ui.core,sap.ui.layout,sap.f,sap.tnt), and everypackage.jsonalready depends on@openui5/types.integrate-tutorialskill — taught the port script and authoring reference to rewriteui5.sap.com/sapui5.hana.ondemand.com→sdk.openui5.orgfor OpenUI5-only tutorials, so future ports stay aligned. (The skill lives under the gitignored.claude/and is not part of this PR's file changes.)Verified with a repo-wide
grep: zero residualSAPUI5,ui5.sap.com, orsapui5.hana.ondemand.comreferences in tutorial content or project files.