-
-
Notifications
You must be signed in to change notification settings - Fork 2.9k
feat!: stabilize experimental.headingIdCompat #14494
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 5 commits
ed713b6
8603c4c
c05b285
28fd7a8
327e9d8
5d5c929
f6d355b
af4cb67
da17d6b
c667712
abfd07f
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
--- | ||
'@astrojs/markdoc': minor | ||
'@astrojs/mdx': major | ||
'@astrojs/markdown-remark': major | ||
'astro': major | ||
--- | ||
|
||
Updates Markdown heading ID generation | ||
|
||
In Astro 5.x, an additional default processing step to Markdown stripped trailing hyphens from the end of IDs for section headings ending in special characters. This provided a cleaner `id` value, but could lead to incompatibilities rendering your Markdown across platforms. | ||
|
||
In Astro 5.5, the `experimental.headingIdCompat` flag was introduced to allow you to make the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm, using the popular [`github-slugger`](https://github.com/Flet/github-slugger) package. | ||
|
||
Astro 6.0 removes this experimental flag and makes this the new default behavior in Astro: trailing hyphens from the end of IDs for headings ending in special characters are no longer removed. | ||
|
||
#### What should I do? | ||
|
||
If you have manual links to headings, you may need to update the anchor link value with a new trailing hyphen. For example, the following Markdown heading: | ||
|
||
```md | ||
## `<Picture />` | ||
``` | ||
|
||
will now generate the following HTML with a trailing hyphen in the heading `id`: | ||
|
||
```html | ||
<h2 id="picture-"><code><Picture /></h2> | ||
``` | ||
|
||
and must now be linked to as: | ||
|
||
```markdown | ||
See [the Picture component](/en/guides/images/#picture-) for more details. | ||
``` | ||
|
||
If you were previously using the experimental feature to enforce trailing hyphens, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists. | ||
|
||
If you were previously using the `rehypeHeadingIds` plugin directly to enforce compatibility, remove the `headingIdCompat` option as it no longer exists: | ||
|
||
```js title="astro.config.mjs" del={8} ins={9} | ||
import { defineConfig } from 'astro/config'; | ||
import { rehypeHeadingIds } from '@astrojs/markdown-remark'; | ||
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source'; | ||
|
||
export default defineConfig({ | ||
markdown: { | ||
rehypePlugins: [ | ||
[rehypeHeadingIds, { headingIdCompat: true }], | ||
[rehypeHeadingIds], | ||
otherPluginThatReliesOnHeadingIDs, | ||
], | ||
}, | ||
}); | ||
``` | ||
florian-lefebvre marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
If you want to keep the old ID generation for backward compatibility reasons, you can create a custom rehype plugin that will generate headings IDs like Astro 5.x. This will allow you to continue to use your existing anchor links without adding trailing hyphens. | ||
florian-lefebvre marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -11,23 +11,17 @@ function getSlug( | |
attributes: Record<string, any>, | ||
children: RenderableTreeNode[], | ||
headingSlugger: Slugger, | ||
experimentalHeadingIdCompat: boolean, | ||
): string { | ||
if (attributes.id && typeof attributes.id === 'string') { | ||
return attributes.id; | ||
} | ||
const textContent = attributes.content ?? getTextContent(children); | ||
let slug = headingSlugger.slug(textContent); | ||
|
||
if (!experimentalHeadingIdCompat) { | ||
if (slug.endsWith('-')) slug = slug.slice(0, -1); | ||
} | ||
return slug; | ||
return headingSlugger.slug(textContent); | ||
Comment on lines
-20
to
+19
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Noting that I’m not familiar enough with the Markdoc integration to know if there’s a good way for users to modify our logic if they want backwards compatibility. We have docs on using a custom heading component, but not on how to generate your own Maybe they have to write their own If it’s super onerous, does anyone think we should offer a backwards compat option for the Markdoc integration? Or do we just embrace that it’s a breaking change and people need to update their links. Markdoc usage is fairly low and the cases where this is breaking will be relatively infrequent. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah given how low it is, I don't think it's worth investing a lof of effort in it |
||
} | ||
|
||
type HeadingIdConfig = MarkdocConfig & { | ||
ctx: { headingSlugger: Slugger; experimentalHeadingIdCompat: boolean }; | ||
}; | ||
interface HeadingIdConfig extends MarkdocConfig { | ||
ctx: { headingSlugger: Slugger }; | ||
} | ||
|
||
/* | ||
Expose standalone node for users to import in their config. | ||
|
@@ -50,12 +44,7 @@ export const heading: Schema = { | |
'Unexpected problem adding heading IDs to Markdoc file. Did you modify the `ctx.headingSlugger` property in your Markdoc config?', | ||
}); | ||
} | ||
const slug = getSlug( | ||
attributes, | ||
children, | ||
config.ctx.headingSlugger, | ||
config.ctx.experimentalHeadingIdCompat, | ||
); | ||
const slug = getSlug(attributes, children, config.ctx.headingSlugger); | ||
|
||
const render = config.nodes?.heading?.render ?? `h${level}`; | ||
|
||
|
@@ -72,12 +61,11 @@ export const heading: Schema = { | |
}; | ||
|
||
// Called internally to ensure `ctx` is generated per-file, instead of per-build. | ||
export function setupHeadingConfig(experimentalHeadingIdCompat: boolean): HeadingIdConfig { | ||
export function setupHeadingConfig(): HeadingIdConfig { | ||
const headingSlugger = new Slugger(); | ||
return { | ||
ctx: { | ||
headingSlugger, | ||
experimentalHeadingIdCompat, | ||
}, | ||
nodes: { | ||
heading, | ||
|
Uh oh!
There was an error while loading. Please reload this page.