feat(mdx-loader): Remark plugin to report unused MDX / Markdown directives

[OzakIOne]

You get a warning?

If you get a warning while running your site, read this section to understand how to fix it.

TLDR:

• escape directives with an extra \ to make them render as plain text
• example \:myDirective

Problem

Docusaurus v3 uses the remark-directive plugin to implement Markdown Directives support.

3 sort of Markdown directives exists:

• Text Directives (:text)
• Leaf Directives (::leaf)
• Container Block Directives (:::container)

This is how Docusaurus implements admonitions such as :::note or :::danger.

These directives also allow you to extend Markdown's capabilities, enabling custom functionality by providing simple Remark plugins.

Problem: if your docs already contains text like :abc or ::xyz, you may inadvertently use a directive, and it may not render like you expect

Solution

To avoid the inadvertent usage of directive you can escape the : character by adding a backslash before it, or add a space after it

Examples:

• :text ➡️ \:text or : text
• ::leaf ➡️ \::leaf or :: leaf
• :::container ➡️ \:::container or ::: container

---

Motivation

This plugin aims to warn users of the usage of unused directives, to prevent mistakes and to be sure their documents keep rendering as before after upgrading to Docusaurus v3.

Test Plan

yarn jest unusedDirectives

Test links

Deploy preview: https://deploy-preview-9394--docusaurus-2.netlify.app

Related issues/PRs

remarkjs/remark-directive#12
https://talk.commonmark.org/t/generic-directives-plugins-syntax/444
https://github.com/remarkjs/remark-directive
https://docusaurus.io/docs/next/markdown-features/admonitions

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	65406ac
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/6537a52f6885690008e456be
😎 Deploy Preview	https://deploy-preview-9394--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟢 94	🟢 97	🟢 92	🟢 100	🟠 89	Report
/docs/installation/	🟠 80	🟢 98	🟢 92	🟢 100	🟠 89	Report
/docs/category/getting-started/	🟢 92	🟢 100	🟢 92	🟢 90	🟠 89	Report
/blog/	🟠 87	🟢 100	🟢 92	🟢 90	🟠 89	Report
/blog/preparing-your-site-for-docusaurus-v3/	🟠 77	🟢 97	🟢 92	🟢 100	🟠 89	Report
/blog/tags/release/	🟠 83	🟢 100	🟢 92	🟠 80	🟠 89	Report
/blog/tags/	🟠 88	🟢 100	🟢 92	🟢 90	🟠 89	Report

[Josh-Cena]

Note, I'm not sure if IDEs can provide navigation if the line numbers are surrounded by ANSI sequences.

[slorber]

For now we agreed navigation was not a goal because we need to use relative paths anyway otherwise CI tests would fail due to different absolute paths in snapshots.

And navigation apparently doesn't work in VSCode with relative paths.

[OzakIOne]

I've tested on VSCode and in fact there is no problem opening the file from terminal even if the path is relative or surrounded by ANSI sequences (colors in the terminal am I right?)

VSCode seems to support multiple path syntax, full path, relative with or without ./ (e.g.: ./website/README.md or website/README.md)

I've tested on WebStorm but it doesn't seem to have this feature (ctrl+click) to open file in editor (not a WebStorm user so I didn't dig too much)

[Josh-Cena]

Yes, VS Code supports opening files with paths relative to the current project. I think it even supports arbitrary paths, as long as the name is unambiguous (otherwise it shows a dropdown chooser). For example foo.tsx can open to src/components/foo.tsx.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No change detected	-	Oct 24, 2023, 11:20 AM