Mdx: Headings should generate ids for deep-linking

Created on 11 Oct 2019 · 6Comments · Source: mdx-js/mdx

Subject of the feature

Add ids to headings for deep linking.

Problem

Most markdown implementations automatically add a slugified id to all headings (h1–h6) for deep-linking support. I would expect MDX to do the same.

Expected behavior

Markdown such as ## More information should render as <h2 id="more-information">More information</h2>. This way, links with this hash deep link to the heading (e.g. https://example.com/foo#more-information).

Alternatives

Similar behavior can be accomplished by creating custom components that add the id, but this requires additional configuration.

👀 areexternal

Source

keithjgrant

Most helpful comment

There's a rehype plugin for that! rehype-slug. Read more about plugins here: https://mdxjs.com/advanced/plugins

wooorm on 12 Oct 2019

👍3

All 6 comments

There's a rehype plugin for that! rehype-slug. Read more about plugins here: https://mdxjs.com/advanced/plugins

wooorm on 12 Oct 2019

👍3

Yeah, I think we shouldn't do this by default in MDX since it's pretty opinionated, but we should definitely document this in the guides.

johno on 12 Oct 2019

👍2

Hey

I'm exploring how to bring i18n support to https://github.com/facebook/docusaurus where MDX files will be translated (through git or a saas like Crowdin/Transifex).

Auto-generated ids might be a problem in practice, because changing the text does change the id, which may break linking from other pages. This means that a translating changing some heading would have to go through all the other docs of the site and update all the anchor links everywhere.

Having a way to choose the id would be useful.

Looks like it's possible to do as a remark plugin
https://github.com/reactjs/reactjs.org/pull/1636/files#diff-9a50f5acbfae877b9f3d761e266b0339R21

Yet just wanted to expose the i18n usecase so that you might want to include core support?
(btw I have similar usecases for tunability to provide targets to links, size to images etc... all can probably be solved with remark)

slorber on 20 Aug 2020

@keithjgrant This can be accomplished by using remark/plugins.

I accomplished it, with the following webpack setup:

const remarkSlugs = require('remark-slug');
const rehypeHtml = require('rehype-stringify');

...
  rules: [
    ...
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: '@mdx-js/loader',
            options: {
              remarkPlugins: [remarkSlugs],
              rehypePlugins: [rehypeHtml],
            },
          },
        ]
      }
  ]

tillkolter on 21 Aug 2020

👍1

@keithjgrant This can be accomplished by using remark/plugins.

I accomplished it, with the following webpack setup:

const remarkSlugs = require('remark-slug');
const rehypeHtml = require('rehype-stringify');

...
  rules: [
    ...
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: '@mdx-js/loader',
            options: {
              remarkPlugins: [remarkSlugs],
              rehypePlugins: [rehypeHtml],
            },
          },
        ]
      }
  ]

Do you have an example repo that demonstrate the use of the deep-linking? A codesandbox example? I am interesting in knowing how to do this. Thank you