---
title: "The Ultimate MDX Showcase"
date: "2026-06-03"
excerpt: "A comprehensive demo exercising every Markdown and MDX feature supported by this blog — from typography to math, code, callouts, tables, images, and more."
tags:
- Design
- Next.js
- Math
- Code
- Web Dev
author: "Krishna"
coverImage: "/starter-showcase.svg"
---
## Introduction
Welcome to the ultimate showcase of Markdown and MDX features available on this blog. This post demonstrates the full spectrum of formatting, technical, and interactive elements at your disposal — from basic text styling to advanced math rendering and custom callout components.
Whether you're writing a tutorial, sharing code snippets, or documenting design decisions, the content pipeline supports rich, engaging technical writing. Check out the [Posts archive](/posts/) for more articles, or dive into the [MDX Documentation](https://mdxjs.com/) to learn more about the underlying technology.
This page uses **bold text**, *italic text*, ***bold and italic*** together, and ~~strikethrough~~ to show you the range of inline formatting available. You can also include inline code like `console.log('hello')` directly within a sentence.
---
## Typography and Text
### Basic Formatting
Good typography is the foundation of readable content. Markdown gives you clean semantic markup without the clutter of HTML tags. Here's how the different heading levels stack up — each one serves a distinct purpose in organizing your content for both readers and the table of contents.
#### Sub-section Heading
Sub-sections help break down larger topics into digestible pieces. They're especially useful when a single section covers multiple related concepts.
##### Minor heading
Even smaller subdivisions work seamlessly, allowing granular organization without overwhelming your document structure.
###### Smallest heading
The smallest heading level is rarely needed, but it's there when you need maximum granularity.
> This is a blockquote with multiple paragraphs. Blockquotes are perfect for highlighting important passages, citing sources, or setting aside reflective commentary.
>
> Second paragraph of the blockquote. You can include as many paragraphs as needed within a single blockquote, and each one will render with the same styling.
### Lists
Lists are essential for organizing information. Markdown supports several list types that work beautifully together.
**Ordered lists are great for step-by-step instructions:**
1. First item — start with the initial setup
2. Second item — build on the foundation
- Nested unordered item for details
- Another nested item with extra context
3. Third item — finalize and review
**Unordered lists work well for grouping related items:**
- Item one — the primary category
- Nested item A — specific detail
- Nested item B — related detail
- Item two — the secondary category
### Task Lists
Task lists combine checkboxes with content, making them perfect for progress tracking:
- [x] Build the MDX pipeline
- [x] Add code highlighting
- [x] Implement callouts
- [ ] Write comprehensive tests
- [ ] Deploy to production
## Code and Technical Content
Code blocks are one of the most powerful features of MDX. They support language-specific syntax highlighting, line numbers, title bars, and selective line highlighting.
### TypeScript Example
Here's a Next.js root layout component with highlighted lines showing the key structural elements:
```tsx title="app/layout.tsx" {1,3-5}
import { ThemeProvider } from '@/components/ThemeProvider';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
Lines 1 and 3-5 are highlighted to draw attention to the import statement and the function signature — the two most important parts for understanding this component's contract.
### Python Example
The same highlighting concept works across all supported languages:
```python title="utils.py" {2,4}
def calculate_fibonacci(n: int) -> list[int]:
"""Calculate Fibonacci sequence up to n terms."""
if n <= 0:
return []
sequence = [0, 1]
while len(sequence) < n:
sequence.append(sequence[-1] + sequence[-2])
return sequence
print(calculate_fibonacci(10))
```
Line 2 highlights the docstring, and line 4 highlights the early return — both critical for understanding the function's behavior at the boundaries.
### Bash Example
Shell scripts get the same treatment:
```bash title="deploy.sh"
#!/bin/bash
echo "Building project..."
bun run build
echo "Deployment complete!"
```
### Why Code Matters in Technical Writing
Well-formatted code blocks transform abstract explanations into concrete, actionable examples. They let readers copy, paste, and experiment immediately. Combined with syntax highlighting and line numbers, your technical content becomes both educational and practical.
## Visual Elements
### Images from Public Directory
Images help illustrate complex concepts and break up text-heavy content. Here's how they look in practice:
Both images are stored in the `public/` directory and referenced using absolute paths starting with `/`. This approach ensures they're properly bundled and available during static site generation.
## Tables
Tables are essential for presenting structured data. Markdown tables support headers, alignment, and complex formatting.
### Feature Comparison
| Feature | Basic | Advanced | Expert |
|---------|-------|----------|--------|
| Markdown | ✅ | ✅ | ✅ |
| Code Highlighting | ❌ | ✅ | ✅ |
| Math Rendering | ❌ | ❌ | ✅ |
| Custom Components | ❌ | ✅ | ✅ |
| Callouts | ❌ | ❌ | ✅ |
### Technical Specifications
| Property | Value | Type |
|----------|-------|------|
| `max-width` | `72ch` | CSS |
| `scroll-offset` | `7.5rem` | CSS |
| `line-height` | `1.75` | Tailwind |
Tables work especially well for comparing options or documenting API parameters. The GFM table syntax renders cleanly across all Markdown processors.
## Mathematics
Mathematical notation elevates technical writing, making it possible to express precise relationships and formulas inline.
### Inline Equations
You can embed equations directly within your text. The famous equation $E = mc^2$ changed physics forever. Similarly, the sum of squares formula $\sum_{i=0}^{n} i^2 = \frac{n(n+1)(2n+1)}{6}$ is useful in algorithm analysis and statistics.
### Display Equations
For more complex expressions, display equations render on their own line with centered formatting:
The quadratic formula:
$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$
Bayes' theorem:
$$P(A|B) = \frac{P(B|A) \cdot P(A)}{P(B)}$$
These equations are rendered using KaTeX, which provides fast and beautiful math typesetting for the web.
## Callouts and Admonitions
Callouts are special content blocks that draw attention to important information. They come in four distinct styles, each serving a different communicative purpose.
:::note title="About Callouts"
Callouts are special blocks that draw attention to important information. They are rendered using the `remark-directive` plugin and a custom `Callout` component.
This is a second paragraph within the note callout, demonstrating multi-paragraph support. Callouts can contain any valid Markdown content, including code blocks, lists, and links.
:::
:::tip title="Pro Tip"
You can include inline code in callouts, like `npm install package-name`, to make instructions clearer and more actionable for readers. Use tips for best practices, shortcuts, and things that will make someone's life easier.
:::
:::warning title="Heads Up"
This feature is still experimental. While it works in most cases, you may encounter edge cases with complex nested content.
Always test your content thoroughly before publishing. Warnings are for important caveats that don't necessarily stop users from proceeding, but that they should be aware of.
:::
:::danger title="Critical Warning"
⚠️ **Do not** remove the `remark-directive` plugin from the remark pipeline without also removing the callout directive transformer. Doing so will cause build errors.
Consequences of removing `remark-directive`:
- Build failures due to unrecognized directive nodes
- Broken MDX compilation
- Lost callout functionality
:::
## Collapsible Content
Collapsible sections are perfect for hiding optional details that interested readers can expand. They keep the main content clean while providing depth for those who want it.
Click to expand: Technical Implementation Details
The callout system works through a two-stage pipeline:
1. **`remark-directive`** parses `:::type` syntax and creates directive nodes in the MDX AST
2. **`callout-directive`** (custom plugin) transforms these nodes into `` JSX elements
This approach is clean because it leverages the existing MDX compilation pipeline without requiring JSX syntax in the source files.
Even deeper: AST Transformation
The transformer uses `unist-util-visit` to find `textDirective` nodes, extracts attributes, and converts them to `mdxJsxFlowElement` nodes with the appropriate props. This nested collapsible demonstrates that the feature supports unlimited nesting depth.
## Mixed Complex Content
### Combining Features
Real-world technical writing rarely uses just one feature at a time. Here's how different elements work together in practice:
1. You can have **inline code** like `useEffect()` in a list
2. Followed by a blockquote:
> "The best code is the code you don't write." — Unknown
3. And even a small table:
| Method | Purpose |
|--------|---------|
| `useState` | Local state |
| `useEffect` | Side effects |
This kind of layered content is exactly what MDX enables — combining the simplicity of Markdown with the expressiveness of JSX.
### Keyboard Shortcuts
Press Ctrl + S to save, or use Cmd + S on macOS. For navigating the table of contents, use Tab to move between links and Enter to activate.
The `` element renders keyboard keys with a distinct visual style, making shortcut documentation clear and accessible.
---
## Advanced Markdown Patterns
Beyond the basics, MDX supports several advanced patterns that enhance both the authoring experience and the final output.
### Definition Lists Through Blockquotes
While Markdown doesn't natively support definition lists, you can achieve a similar effect using blockquotes with bold terms:
> **Remark:** A plugin-based toolchain for processing Markdown with unified.
>
> **Rehype:** The HTML equivalent of Remark, operating on HTML-abstract syntax trees.
>
> **MDX:** A format that combines Markdown and JSX, enabling rich components within static content.
### Horizontal Rules as Section Dividers
Horizontal rules like the one below help visually separate major sections within long articles, giving readers breathing room between topics:
---
They're subtle but effective for maintaining readability in comprehensive documents.
## Performance Considerations
When building content-heavy sites, performance matters. Here are some best practices:
1. **Optimize images**: Use modern formats like WebP and include responsive sizes.
2. **Lazy load content**: Defer non-critical images and heavy components below the fold.
3. **Cache math rendering**: KaTeX can be expensive; consider server-side rendering for complex equations.
4. **Minimize custom components**: Each JSX component in MDX adds to the compilation overhead.
5. **Use static generation**: Pre-render content at build time for the fastest possible delivery.
## Closing Thoughts
This showcase demonstrates the full range of Markdown and MDX features available on this blog. From basic typography to advanced math rendering, from interactive code blocks to styled callouts — the content pipeline supports rich, engaging technical writing.
The combination of:
- Clean Markdown syntax for everyday writing
- Full JSX support for interactive components
- Syntax-highlighted code blocks with line numbers
- Beautiful math rendering with KaTeX
- Distinct callout styles for emphasis
- Collapsible sections for optional detail
...creates a powerful authoring platform that scales from simple blog posts to comprehensive technical documentation.
Happy writing!