refactor(mdxish): use variable name for heading slug generation#1340
refactor(mdxish): use variable name for heading slug generation#1340eaglethrost merged 32 commits intonextfrom
Conversation
…dimas/RM-15239-parse-legacy-vars-in-mdxish
| if (node.properties.isLegacy) { | ||
| return node.properties.name as string; | ||
| } | ||
| return `{user.${node.properties.name}}`; |
There was a problem hiding this comment.
From my understanding modern {} variables are always prepended by user.
| * Uses variable names for the id if available | ||
| */ | ||
| const generateSlugForHeadings = () => (tree: Root) => { | ||
| const slugger = new GithubSlugger(); |
There was a problem hiding this comment.
Using git slugger to ensure the heading style is consistent with the git style (lowercase words combined by -). We technically can construct them ourselves without any library, but I think this abstracts them away, reduce chance of errors, and make the slug more consistent.
There was a problem hiding this comment.
I think this is fine, but am concerned around any breaking changes from the way slugs are constructed on legacy. Not in the way vars are resolved like we're discussing here but in edge case formatting.
If we ignore the var resolution question do you think this will match the way slugs are constructed on legacy?
There was a problem hiding this comment.
Yes it does, at least from my testing so far it seems to be match. I'll add more tests for this to verify
There was a problem hiding this comment.
Updated the mdxish-heading-slugs-test.ts tests to also check if it matches legacy slugs
|
Haven't QAed yet, but here's a random list of things I'd check/vaguely remember having caused issues in the past:
|
|
Also, is there a ticket for this that we can link? |
Linked the ticket! To answer your questions:
|
commit e657a21 Author: eagletrhost <dimazanugrah12@gmail.com> Date: Mon Feb 16 19:51:12 2026 +1100 refactor: clean code & comment commit c28853d Author: eagletrhost <dimazanugrah12@gmail.com> Date: Mon Feb 16 19:40:18 2026 +1100 test: fix legacy commit 7574b19 Author: eagletrhost <dimazanugrah12@gmail.com> Date: Mon Feb 16 18:36:04 2026 +1100 feat: glossary adjustments commit 6e92df0 Author: eagletrhost <dimazanugrah12@gmail.com> Date: Mon Feb 16 18:13:02 2026 +1100 feat: parse legacy vars in codes & api header block
…X-2929-mdxish-heading-stabilize-slug-generation
|
Demo & explanation of what the legacy vs mdxish slugs will look like once we stop preprocessing the variables in the frontend: https://www.loom.com/share/0a922e7cde5245c39870f70a93b2293e |
| expect(headings).toHaveLength(1); | ||
| expect(headings[0].id).toBe('hello-world-'); | ||
|
|
||
| const legacyTree = mdastV6Wrapper(md) as Root; |
There was a problem hiding this comment.
Added tests to check if it matches with legacy id / slugs
## Version 13.3.0 ### ✨ New & Improved * **mdxish:** add legacy variable tokenizer ([#1339](#1339)) ([8e8b11b](8e8b11b)) * add option to perserve variable syntax in plain text compiler ([#1345](#1345)) ([5ab350e](5ab350e)) * **mdxish:** resolve variables in code blocks ([#1350](#1350)) ([a6460f8](a6460f8)) * **mdxish:** use variable name for heading slug generation ([#1340](#1340)) ([61a97d3](61a97d3)) <!--SKIP CI-->
|
This PR was released!🚀 Changes included in v13.3.0 |
[![PR App][icn]][demo] | Fix CX-98 :-------------------:|:----------: ## 🧰 Changes Since we can now distinguish legacy variable vs mdx variable (#1340), as well as allowing wild variables in bracket notation (readmeio/readme#17315). We should add support for plain to keep original syntax as is, instead of serialising everything to {user.}. ## 🧬 QA & Testing Unit tests - [Broken on production][prod]. - [Working in this PR app][demo]. [demo]: https://markdown-pr-PR_NUMBER.herokuapp.com [prod]: https://SUBDOMAIN.readme.io [icn]: https://user-images.githubusercontent.com/886627/160426047-1bee9488-305a-4145-bb2b-09d8b757d38a.svg
🧰 Changes
Retake of #1334 because now we have legacy variable tokenizer ready and no longer need to pass in the legacy variables mapping.
Refactors the slug generation logic for headings (which will be used for anchor section links) in MDXish so that if it contains a legacy <<>> or {} variable, the generated slug will use the variable name instead of the variable value. The change is in the heading id generation, which later will be converted to slugs in
renderMdxish.We wanted to this to make the anchor slug more stable. In legacy, the variable part will actually get dropped in the slug generation, so it can unexpectedly clash with other headings & look incomplete. In mdxish, before it was resolving the variable value in the slugs, which means the slugs can change if the value change, and a hardcoded link can get outdated without the user knowing.
This is the first step in addressing this Akamai QA issue: https://linear.app/readme-io/issue/CX-2867/links-to-section-headings-that-involve-variables-personalized-docs
Note:
This change will modify the anchor slug url if it has variables in them, which would make hardcoded links not work for those cases. But given MDXish hasn't been on for a long time, hopefully there's not much customers doing that yet.
🧬 QA & Testing
opts.mdxishpart to avoid preprocessing legacy variables