docs(tutorials): rework TS/JS download links and add AGENTS.md#303
Open
petermuessig wants to merge 1 commit into
Open
docs(tutorials): rework TS/JS download links and add AGENTS.md#303petermuessig wants to merge 1 commit into
petermuessig wants to merge 1 commit into
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.
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.
Summary
Reworks how the JS/TS download links are structured across every tutorial step README, and adds an
AGENTS.mdrepo guide. Branches off the currentmain(after #295 landed), so the diff is scoped to just this change — ~82 files.Problem
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.Change
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.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). The new<span>pattern is documented here and inCONTRIBUTING.md.packages/*/steps.json(byte-identical — the generator's class-based regex still matches the new<span>shape).Verification
.?splaceholder absent, spans present in spot checks.-js.zipbundles confirmed present for the standalone-bundle links.🤖 Generated with Claude Code