Enhanced Markdown: Powerful Content Without MDX
Enhanced Markdown Features
Welcome to Enhanced Markdown! This powerful content system uses directives to provide rich, interactive content without the complexity or compatibility issues of MDX in our Next.js 15 stack.
Why Enhanced Markdown?
Next.js 15 + React 18.3.1 Compatibility: MDX has known issues with Next.js 15 in our stack (runtime MDX via next-mdx-remote), while Enhanced Markdown works perfectly out of the box.
Enhanced Markdown leverages the unified ecosystem with remark and rehype plugins to transform directives into rich HTML components. This approach provides:
- Full Next.js 15 compatibility
- Server-side rendering with no hydration issues
- Rich content features through directives
- Excellent performance with content caching
- Clean, readable markdown syntax
Callout Examples
Pro tip: Callouts support full markdown formatting including bold, italic, and even inline code.
Be careful when using external links - they automatically get noopener and noreferrer attributes for security.
Your Enhanced Markdown setup is complete! All directives are working properly with dark mode support.
This is an error callout. Use it to highlight critical issues or warnings that need immediate attention.
Video Embeds
Embedding YouTube videos is simple and privacy-focused (uses youtube-nocookie.com):
You can also add parameters like start time:
Figure with Caption
Figure: Enhanced Markdown processing pipeline with directives
Code Blocks with Syntax Highlighting
Our Enhanced Markdown includes rehype-pretty-code with shiki for beautiful syntax highlighting:
// Enhanced Markdown processor configuration
const SITE = new URL(process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000');
const isExternal = (href?: unknown) => {
const raw = typeof href === 'string' ? href : '';
try {
const u = new URL(raw, SITE);
return u.hostname !== SITE.hostname;
} catch {
return false;
}
};
const processor = unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkEmoji, { emoticon: true })
.use(remarkSmartypants)
.use(remarkDirective)
.use(remarkContainerDirectives)
.use(remarkRehype, { allowDangerousHtml: false })
.use(rehypeSlug)
.use(rehypeCallouts)
.use(rehypeYoutube)
.use(rehypeExternalLinks, {
target: (node: any) => (isExternal(node?.properties?.href) ? '_blank' : undefined),
rel: (node: any) => (isExternal(node?.properties?.href) ? ['noopener', 'noreferrer'] : undefined),
})
.use(rehypePrettyCode, {
theme: { dark: 'github-dark', light: 'github-light' },
keepBackground: false,
defaultLang: 'plaintext',
})
.use(rehypeAutolinkHeadings, {
behavior: 'wrap',
properties: { className: ['heading-anchor'], 'aria-label': 'Link to section' },
})
.use(rehypeStringify);
// Rendering Enhanced Markdown content with proper accessibility
function BlogPost({ content }) {
return (
<article className="prose prose-custom" aria-label="Blog post content">
<div dangerouslySetInnerHTML={{ __html: content }} />
</article>
);
}
Directive Cheat Sheet
Quick reference for all available directives:
- Callout:
:::info[Optional Title]…:::- Types:
info,warning,success,error,tip
- Types:
- YouTube:
::youtube{id="VIDEO_ID" title="Video Title" start="30" controls="1"} - Figure:
:::figure
caption text ::: - Inline highlight:
:highlight[important text]
GitHub Flavored Markdown
All GFM features work seamlessly:
Task Lists
- Implement Enhanced Markdown
- Add callout directives
- Add YouTube embeds
- Configure syntax highlighting
- Add more directive types
Tables
| Feature | MDX (runtime) | Enhanced Markdown |
|---|---|---|
| Next.js 15 Support | ❌ Known issues | ✅ Perfect |
| React 18.3.1 | ❌ Conflicts | ✅ Compatible |
| Server Rendering | ⚠️ Complex | ✅ Simple |
| Performance | ⚠️ Variable | ✅ Cached |
| Learning Curve | 📈 Steep | 📊 Gentle |
Strikethrough
Runtime MDX is incompatible with our Next.js 15 stack Enhanced Markdown works perfectly!
Smart Typography
Enhanced Markdown automatically converts:
- Straight quotes to “smart quotes”
- Double dashes — to em dashes—like this
- Triple dots… to ellipsis…
- (c) to © and (tm) to ™
Emojis
You can use emoji shortcuts 😄 🚀 🎉 or emoticons 😃 ^_^
External Links
External links like Google automatically get security attributes, while internal links like Home remain standard.
Auto-linked Headings
All headings automatically get anchor links for easy navigation and sharing. Hover over any heading to see the link appear!
Performance Benefits
Caching System: Enhanced Markdown uses SHA1 content hashing for intelligent in-memory caching. Once processed, content is served from memory until it changes. Note: This cache is per-process and resets on deployment. For persistent caching, consider Next.js unstable_cache or a KV store.
The processing pipeline is optimized for performance:
- Content hash generated from markdown
- Cache lookup for instant serving
- Processing only when content changes
- Automatic cache management (100 entry limit)
Extending Enhanced Markdown
Adding new directives is straightforward:
- Create a remark plugin for AST transformation
- Create a rehype plugin for HTML processing
- Add to the processor pipeline
- Style with CSS (dark mode aware)
Example structure for a new directive:
// src/lib/remark-custom.ts
export function remarkCustomDirective() {
return (tree: Root) => {
visit(tree, 'containerDirective', (node) => {
if (node.name === 'custom') {
// Transform AST node
node.data = { ...node.data, directive: true };
}
});
};
}
Conclusion
Enhanced Markdown provides a robust, performant, and compatible content system for Next.js 15 applications. It combines the simplicity of markdown with the power of directives to create rich, interactive content without the complexity of runtime MDX.
Ready to use: Your Enhanced Markdown system is fully configured and production-ready!