fix: stabilies heading slug generations by maximilianfalco · Pull Request #1334 · readmeio/markdown

maximilianfalco · 2026-02-11T13:31:36Z

	Fix RM-XYZ

🧰 Changes

Replaces rehype-slug with a custom slug plugin (mdxish-slug) that reconstructs {user.*} text from <variable> HAST elements when generating heading IDs, so ## Hello {user.name} produces slug hello-username instead of hello.

For legacy <<VARIABLE>> syntax (resolved before the pipeline), the consumer extracts heading texts from the raw markdown and passes them as sourceHeadingTexts, letting slugs stay stable regardless of variable values.

🧬 QA & Testing

eaglethrost · 2026-02-12T05:28:21Z

processor/transform/mdxish/mdxish-slug.ts

+    visit(tree, 'element', (node: Element) => {
+      if (isHeading(node) && !node.properties.id) {
+        const text =
+          sourceHeadingTexts && headingIndex < sourceHeadingTexts.length


Can you put a comment here explaining that sourceHeadingTexts is for legacy variables, and the other is for mdx variables 🙏

eaglethrost · 2026-02-12T05:29:38Z

processor/transform/mdxish/mdxish-slug.ts

+  return /^h[1-6]$/.test(node.tagName);
+}
+
+/** Extract text content from a HAST node, reconstructing {user.*} from <variable> elements. */


Also explain that at this point the {user.*} is converted to a variable node, and that we're try to get back the variable name from it

eaglethrost · 2026-02-12T05:30:44Z

__tests__/lib/mdxish/mdxish.test.ts

I think the tests here can be in a new file specific to test the heading id's

eaglethrost · 2026-02-12T05:36:05Z

__tests__/lib/mdxish/mdxish.test.ts

 });
+
+describe('heading slugs', () => {
+  it('should generate slugs from variable names, not resolved values', () => {


Can we also add tests where there's other {} expressions? To verify that they don't get picked up as variables & cause issues

eaglethrost · 2026-02-12T05:39:41Z

Code looks good for the approach you're trying to do! I think we should verify if we should go with this approach cause I agree needing to pass in the legacy variables list through sourceHeadingText is not ideal since we'd have to do another doc traversal, but it should work.

maximilianfalco · 2026-02-12T09:53:10Z

the current approach works but is a bit hacky imo...

legacy variables with the <<>> syntax is preresolved and expanded even BEFORE hitting the pipeline here over in the main application, meaning the mdxish pipeline doesnt have any data about what the actual heading looks like. even if the original heading was # Good<<DAYTIME>>, mdxish would only ever know # Goodafternoon assuming afternoon is the var value

hence, why we require passing the new sourceHeadingTexts argument which involves extracting headings from the original body and passing them through (this is in my own branch)

however, this is not the case for the modern variables. superhub variables with the {user.*} syntax can be resolved nicely because they are resolved WITHIN the pipeline to proper Variable MDAST nodes. meaning we can reverse engineer them back to their original state.

ideally, we could convert all legacy variables into the superhub one before entering the mdxish pipeline, so we can properly reverse engineer all variables without needing to pass the sourceHeadingTexts argument. BUT, when playing around, I saw there was some differences in the naming rules of legacy and superhub variables one of which is that legacy allows whitespace and the superhub syntax does not. we can still normalize them but it would mean changing the var names, so like this

<<with space>> -> {user.with_space}

if this renaming is acceptable, then i would generally prefer this option

cc @eaglethrost @kevinports @rafegoldberg

kevinports · 2026-02-12T17:28:52Z

legacy variables with the <<>> syntax is preresolved and expanded even BEFORE hitting the pipeline here over in the main application, meaning the mdxish pipeline doesnt have any data about what the actual heading looks like.

Absolutely not what we want. The new editor is only going to receive resolved values as text instead of the correct ast nodes.

ideally, we could convert all legacy variables into the superhub one before entering the mdxish pipeline, so we can properly reverse engineer all variables without needing to pass the sourceHeadingTexts argument.

If we're talking ideal path the <<>> syntax should have a tokenizer that creates the correct variable or glossary node within the pipeline right?

Regardless this should absolutely be happening somewhere IN the pipeline, even if you think the best approach is to move preprocessing into the pipeline but before the remark phase. Currently it looks like we do it on the application side before calling mdxish? https://github.com/readmeio/readme/blob/787c869a9836d30bcad115984d7758b8fb4dcd8b/packages/react/src/ui/RDMD/RMDXISH.tsx#L78-L82

Consumers shouldn't have to handle this.

we can still normalize them but it would mean changing the var names, so like this

<> -> {user.with_space}
if this renaming is acceptable, then i would generally prefer this option

Not the end of the world if we approached it this way BUT:

Probably worth referencing the legacy engine's parsing logic for this and careful to handle glossary: terms correctly.
Regarding how legacy vs. superhub allows whitespace -- looking at this code in the mdx pipeline, it seems like if there is whitespace in the property, it falls back to bracket syntax eg {user['with space'}}

markdown/processor/transform/readme-to-mdx.ts

Line 183 in bb37d62

const value = validIdentifier ? `user.${identifier}` : `user[${JSON.stringify(identifier)}]`;

maximilianfalco · 2026-02-12T23:15:15Z

Regarding how legacy vs. superhub allows whitespace -- looking at this code in the mdx pipeline, it seems like if there is whitespace in the property, it falls back to bracket syntax eg {user['with space'}}

I tried doing this but even in mdx, if I have a variable say like {user.with name} the page wont save correctly, is this expected?

cc @kevinports

HugoHSun · 2026-02-13T06:46:09Z

Regarding how legacy vs. superhub allows whitespace -- looking at this code in the mdx pipeline, it seems like if there is whitespace in the property, it falls back to bracket syntax eg {user['with space'}}

I tried doing this but even in mdx, if I have a variable say like {user.with name} the page wont save correctly, is this expected?

cc @kevinports

Yea it shouldn't save in MDX since anything between {} is interpreted as an JS expression. user.with name is not a valid JS expression. So for weird variable names the bracket notation is probably the way to go.

An issue currently is that the MDX editor serialises standalone bracket notation variables in a weird way, e.g. {user["name"]} turns into {user.{user["name"]}}. I'm gonna address it in #1320

eaglethrost · 2026-02-13T15:16:24Z

I think we should move this PR to #1340

[![PR App][icn]][demo] | Fix CX-2929 :-------------------:|:----------: ## 🧰 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 1. I think it's best to test this by locally linking this branch to readme 2. In the [MDXish RDMD here](https://github.com/readmeio/readme/blob/169a94b6372bd68282d78cd8ea70d9f14ce78fa3/packages/react/src/ui/RDMD/RMDXISH.tsx#L79), remove the `opts.mdxish` part to avoid preprocessing legacy variables 3. In an mdxish project in the site, create several H1-H3 headings that contain legacy <<>> and {} variables in them 4. When hovering the anchor logo next to the headings, look at the bottom left of your screen for the slug. The slug should use the variable name and not the value [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

wip: first pass

e4c9b0b

eaglethrost reviewed Feb 12, 2026

View reviewed changes

rafegoldberg mentioned this pull request Feb 12, 2026

fix: allow hyphenated variables in MDX #1320

Closed

Merge branch 'next' into falco/stabilise-heading-slugs

9382bab

eaglethrost mentioned this pull request Feb 13, 2026

refactor(mdxish): use variable name for heading slug generation #1340

Merged

eaglethrost closed this Feb 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: stabilies heading slug generations#1334

fix: stabilies heading slug generations#1334
maximilianfalco wants to merge 2 commits intonextfrom
falco/stabilise-heading-slugs

maximilianfalco commented Feb 11, 2026 •

edited

Loading

Uh oh!

eaglethrost Feb 12, 2026 •

edited

Loading

Uh oh!

eaglethrost Feb 12, 2026

Uh oh!

eaglethrost Feb 12, 2026

Uh oh!

eaglethrost Feb 12, 2026

Uh oh!

eaglethrost commented Feb 12, 2026

Uh oh!

maximilianfalco commented Feb 12, 2026 •

edited

Loading

Uh oh!

kevinports commented Feb 12, 2026 •

edited

Loading

Uh oh!

maximilianfalco commented Feb 12, 2026

Uh oh!

HugoHSun commented Feb 13, 2026

Uh oh!

eaglethrost commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

maximilianfalco commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧰 Changes

🧬 QA & Testing

Uh oh!

eaglethrost Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eaglethrost Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

eaglethrost Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

eaglethrost Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

eaglethrost commented Feb 12, 2026

Uh oh!

maximilianfalco commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kevinports commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maximilianfalco commented Feb 12, 2026

Uh oh!

HugoHSun commented Feb 13, 2026

Uh oh!

eaglethrost commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

maximilianfalco commented Feb 11, 2026 •

edited

Loading

eaglethrost Feb 12, 2026 •

edited

Loading

maximilianfalco commented Feb 12, 2026 •

edited

Loading

kevinports commented Feb 12, 2026 •

edited

Loading