Skip to main content

Learning MDX

What is MDX?​

MDX is Markdown + JS (JSX more specifically). You can learn all the details here: MDX. It has an article that will show you how to use markdown, JSX, JavaScript expressions, and import and export statements in ESM inside MDX files within Docusaurus. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast. 🚀

tip callout section

Create a Lightbulb Icon with Green Box Callout by adding the following to it's own line in your MDX file by adding ":::tip any word or nothting" to it's own line in your MDX file.

DID YOU KNOW

MDX alows you to use the power of React to create interactive blog posts.

Check out this JSX within this callout and MDX file!

This gives you the power of React and components to create interactive blog posts. All of this within the callout!

<button onClick={() => alert("button clicked!")}>Click me!</button>
warning callout option

There is also this fire icon with a red box that can be used. It's pretty cool... or should I say HOT! Ha!

Callout with a Note Icon

This is a note icon with a gray box. This is a great way to add a note to your content.

Callout with a Caution Icon

This is a caution icon with a dark orange box. This is a great way to add a caution to your content.

Callout with a Info Icon

This is a info icon with a blue box. This is a great way to add a info to your content.

Markdown features also work with MDX​

A blockquote with someemphasis.

Markdown Headings (H2)​

H1 Info

This is a Heading 1. This H1 does not rank above the meta title that is auto added to the left and right sidebar in rank 1.

H3 Info​

This is a Heading 3. This H3 creates a title and link in order of the other H1 and H2's on the right sidebar. H3 also indents it slightly. This helps from a visual and accessibility standpoing.

H4 - Does nothing except decrease to the associated css font size.​

H5 - Does nothing except decrease to the associated css font size.​
H6 - Does nothing except decrease to the associated css font size.​

H4, H5, and H6 headings do not show up in the right sidebar, but they do follow their associated styling and help with symantic markdown.

Lists​

  • Unordered
  • List
  1. Ordered
  2. List

Horizontal Line​

A horizontal line can be created by using 3 consequitive dashes. Here is an example "---". This example is above this paragraph and below it.

Code Blocks​

JS - Copy to Clipboard​

const copyToClipboard = (text) => navigator.clipboard.writeText(text);

copyToClipboard("This Sring is Copied To Clipboard.");

JS - Scroll to Page Top​

const goToTop = () => window.scrollTo(0, 0);

goToTop();

JS - Detect Dark Mode​

const isDarkMode =
  window.matchMedia &&
  window.matchMedia("(prefers-color-scheme: dark)").matches;

console.log(isDarkMode); // Result: True or False

HTML - Hello World​

<main>
  <article>Hello World</article>
</main>

CSS - Style Change​

.cssStyleChange {
  font-size: 1.5em;
}

JSX​

JSX is an extension to JavaScript that looks like HTML but makes it convenient to use components (reusable things). JSX is typically combined with a frontend framework like React, Preact, or Vue. These frameworks add support for components, which let you change repeating things like the following markup:
<Welcome name="Venus" />
<Welcome name="Mars" />

JSX is good for components. It makes repeating things more clear and allows for separation of concerns. MDX supports JSX syntax. The following looks a lot like HTML:

<h1>Heading!</h1>

<abbr title="HyperText Markup Language">HTML</abbr> is a lovely language.

<section>And here is *markdown* in **JSX**!</section>
<MyComponent id="123" />

You can also use objects with components, such as the `thisOne` component on
the `myComponents` object: <myComponents.thisOne />

<Component
  open
  x={1}
  label={"this is a string, _not_ markdown!"}
  icon={<Icon />}
/>

Details element example​

Toggle me!
This is the detailed content

Details element example with extra nested toggle​

Toggle me!
This is the detailed content

Nested toggle! Some surprise inside...
😲😲😲😲😲

JS Expressions​

MDX also supports JavaScript expressions inside curly braces:

Two 🍰 is: {Math.PI \* 2}

Expressions can contain whole JavaScript programs as long as that they're (wrapped in) an expression that evaluates to something that can be rendered. You can use an IIFE like so:

{
  (function () {
    const guess = Math.random();

    if (guess > 0.66) {
      return <span style={{ color: "tomato" }}>Look at us.</span>;
    }

    if (guess > 0.33) {
      return <span style={{ color: "violet" }}>Who would have guessed?!</span>;
    }

    return <span style={{ color: "goldenrod" }}>Not me.</span>;
  })();
}

Expressions can be empty or contain just a comment:

{
  /* A comment! */
}

Using MDX​

To learn more about using MDX, read the MDX docs. It will cover using MDX with props, components, layouts and more.