Text Formatting in MDX

Text formatting is how you add emphasis, highlight code, indicate deleted content, and draw attention to specific words within your prose. MDX supports all standard Markdown formatting plus HTML-based options for subscript, superscript, highlighting, and keyboard shortcuts. Understanding when to use each type of formatting — and more importantly, when not to — makes your content more readable and professional.

Italic Text

Single asterisks or underscores for italic:

This is italic text (rendered in slanted style)

When to use italic:

• Book titles, article titles, and publication names
• Introducing new technical terms for the first time (then use regular weight after)
• Adding subtle emphasis without the weight of bold
• Foreign words or Latin phrases (e.g., *ad hoc*, *de facto*)
• Placeholder text that the reader should replace (e.g., *your-username*)

Italic is softer emphasis than bold. Think of it as whispering versus shouting. Use bold when something is critical, italic when something simply deserves a moment of attention.

Bold and Italic Combined

Triple asterisks give you both:

This is bold and italic (rendered in heavy slanted style)

This is rarely needed in practice. If you find yourself reaching for bold italic, ask whether the content needs restructuring instead. It is almost always better to restructure your sentence so that regular bold is sufficient for the emphasis you need.

Strikethrough

Double tildes create strikethrough (crossed out) text:

This text is crossed out (with a line through it)

Practical uses for strikethrough:

Strikethrough is excellent for showing changes, corrections, and deprecated information. It communicates "this was true before but is no longer the current recommendation" without removing the old information entirely.

In documentation, strikethrough is commonly used in changelogs and migration guides where you want to show what changed from the old approach to the new one.

Inline Code

Backticks wrap inline code — technical terms that should render in monospace font:

Use the console.log() function to debug your application.
Set NODE_ENV to production before deploying.
The package.json file contains your project configuration.

Inline code renders in monospace font with a subtle background, making technical terms visually distinct from prose.

Use inline code for:

• Function names: useState, fetch, addEventListener
• Variable names: isLoading, userData, config
• File names: package.json, .env, tsconfig.json
• Terminal commands: npm install, git commit
• CSS properties: display: flex, margin-top
• HTML tags: <div>, <section>, <a>
• Configuration values: true, false, null, 3000
• Keyboard keys in technical context: the Enter key, the Escape key

Do NOT use inline code for:

• Regular emphasis (use bold or italic instead)
• Brand names or product names
• Non-technical terms
• Entire phrases that are not code

Subscript and Superscript

Standard Markdown does not have subscript or superscript syntax, but since MDX supports HTML, you can use the <sub> and <sup> tags:

Water is H₂O.
The formula is E = mc².
CO₂ emissions are a major concern.
The 3rd edition is now available.

These are particularly useful in scientific and mathematical content where subscripts and superscripts appear frequently in formulas and chemical notation.

Highlighted Text

Use the <mark> tag to add a yellow highlight effect:

The key takeaway is: always validate user input (with yellow highlight)
Remember to never store passwords in plain text (with yellow highlight)

Highlighted text draws maximum attention. Use it very sparingly — once or twice per page at most — for the absolute most critical points that readers must not miss.

Keyboard Keys

The <kbd> tag renders text in a style that looks like physical keyboard keys:

Press [Ctrl] + [C] to copy text.
Use [Cmd] + [Shift] + [P] to open the command palette.
Press [Escape] to close the modal.

This is perfect for keyboard shortcut documentation, tutorial instructions, and any content where you reference physical keys the user should press.

Escaping Special Characters

What if you need to show literal asterisks, backticks, or other special characters without triggering formatting? Use a backslash:

*This is not italic*
**This is not bold**
\`This is not inline code\`
Use # at the start to show a literal hash

The backslash tells the parser "treat the next character as literal text, not as formatting syntax."

Combining Multiple Formats

You can nest formatting types within each other:

Nesting works as long as you close each format in the correct order — like HTML tags, formats must be closed in reverse order of opening.

Formatting Philosophy: Less is More

The most common mistake beginners make is over-formatting. When everything is bold, nothing stands out. When every technical-sounding word is in inline code, the visual noise makes content harder to read.

Guidelines for restraint:

1. Bold: Maximum 2-3 uses per section for truly important terms
2. Italic: Use for first introduction of terms, then stop italicizing them
3. Inline code: Only for actual code or technical identifiers
4. Strikethrough: Only for genuinely deprecated or corrected information
5. Highlight: Maximum 1-2 uses per page for critical takeaways

If you find yourself using lots of formatting, your content might need restructuring instead — better headings, shorter paragraphs, or clearer writing can replace the need for constant emphasis.

Quick Reference