Add support for reference style links

[jcalcaben]

🙋 Feature Request

Add support for reference-style links in MDX for static builds.

🤔 Expected Behavior

The following markdown:

This is an [internal reference-style link][].

[internal reference-style link]: /path/to/page/

Should be rendered as a link with the pathPrefix prepended to the destination when creating the static builds for staging and production.

😯 Current Behavior

Staging and production builds do not prepend the link destination with the site's pathPrefix.

This can be seen when building content that uses reference-style links and publish to staging.
The link paths from this content will not have the prefix prepended to the href.

💁 Possible Solution

Add the remark-inline-links plugin to the MDX plugin's options.remarkPlugins array.

   {
        resolve: `gatsby-plugin-mdx`,
        options: {
          extensions: [`.mdx`, `.md`],
          defaultLayouts: {
            default: require.resolve(`./src/components/MDXFilter/index.js`)
          },
          rehypePlugins: [require(`rehype-slug`)],
          plugins: [`gatsby-remark-copy-linked-files`, `gatsby-remark-images-remote`],
          gatsbyRemarkPlugins: [
            {
              resolve: `gatsby-remark-copy-linked-files`,
              options: {
                ignoreFileExtensions: [`png`, `jpg`, `jpeg`, `bmp`, `tiff`, `md`, `mdx`]
              }
            },
            {
              resolve: `gatsby-remark-images-remote`,
              options: {
                maxWidth: LARGE_SCREEN_WIDTH,
                linkImagesToOriginal: false,
                withWebp: { quality: 80 },
                disableBgImage: true,
                backgroundColor: 'none'
              }
            }
          ],
+        remarkPlugins: [require('remark-inline-links')],
        }
      },

This transforms reference-style links in the underlying markdown into inline links, which produce the correct links in static builds.

🔦 Context

The markdown content I am migrating into this framework almost exclusively uses reference-style links, which is valid markdown syntax.
Using this format makes authoring, reading, and reviewing the raw markdown easier.

For local development builds, this is not a problem because pathPrefix is not used, but when uploading static builds to the staging server where the content does not sit at the root, this becomes an issue.

💻 Examples

For Magento Cloud specific deployment instructions, see the [Magento Cloud deployment][] tutorial.

[magento cloud deployment]: /tutorials/production-deployment/magento-cloud/

🧢 Your Company/Team

Magento/devdocs

🎁 Tracking Ticket (optional)

[icaraps]

@jcalcaben did you try the remark-inline-links you mentioned ? Does it work ?
You can try it by checking out https://github.com/adobe/gatsby-theme-aio then cd packages/gatsby-theme-aio && yarn add remark-inline-links then add the config as you said in https://github.com/adobe/gatsby-theme-aio/blob/main/packages/gatsby-theme-aio/gatsby-config.js then at the project root yarn dev && open localhost:8000 and update an index.md file with reference-style links to check if it's working.

[jcalcaben]

@icaraps yes, this does solve the issue. I can create a PR for this change, but it may not be necessary.

I tracked down the source of the bug to Gatsby itself, reported it, and created a PR to fix it on their end.

Since my PR just got merged, we just have to wait for the next release of the gatsby-plugin-mdx package.

[icaraps]

Awesome thanks ! 👏