Extended Markdown and MDX Features#

This post demonstrates how the extended Markdown and MDX features from our current setup behave inside a real blog article. All of the examples below are wired through:

remark-directive
remark-directive-sugar
rehype-callouts
remark-imgattr
remark-math
remark-cdn

Callouts#

Callouts use the VitePress-style syntax and are rendered by rehype-callouts:

NOTE

Highlights information that readers should take into account, even when skimming.

You can customize the callout title.

Optional information to help a reader be more successful.

This is a collapsible callout, initially closed.

Crucial information necessary for readers to succeed.

This is a collapsible callout, initially open.

Critical content demanding immediate attention.

Badges and Styled Links#

The :badge and :link directives come from remark-directive-sugar:

Status: ACTIVE
Repository: Astro

Corrected link directive:

Typed content collections:
remark-directive-sugar

You can also attach custom URLs:

Documentation: docs.astro.build
Search: MDN JavaScript

Image Figure Directive and CDN Images#

You can combine :::image-figure with remark-cdn by pointing images to the CDN keys.

The manifest contains an entry for images/0321_good.png, so we can safely reference:

Example image from CDN — Example figcaption with a CDN image.

For more control, you can also use the <Figure> MDX component directly:

Figure 1: Braintrust logo served via the CDN and rewritten by remark-cdn. - Provided by Braintrust

Both approaches will be rewritten at build time to hashed asset URLs using the manifest.

Inline Math and Display Math#

Math is handled by remark-math and rehype-katex. Inline math:

Inline example: $E = mc^2$ appears within the sentence.

Display math:

\int_{0}^{1} x^2 \, dx = \frac{1}{3}

Putting It All Together#

The combination of:

Astro content collections
MDX with directives and custom components
remark-cdn for asset rewriting
rehype-callouts for callouts

creates a powerful but maintainable writing environment.

For a more traditional article combining code, images, tables, and sidenotes, see the earlier sample post.