Welcome to the MDX Starter Template! This template combines the power of Next.js 15+, MDX, and shadcn/ui to create a modern content-focused website. Whether you're building a blog, documentation site, or portfolio, this starter provides everything you need to get up and running quickly.
The template is designed with developer experience in mind, offering a clean and intuitive structure that makes it easy to create beautiful, performant content. With built-in support for dark mode, syntax highlighting, and optimized images, you can focus on writing great content instead of configuring tooling.
Features
This starter template comes packed with modern features that make content creation a breeze. Next.js 15+ brings the latest features from the framework, including improved performance, better developer experience, and enhanced server components. The App Router provides a file-system based routing system that makes organizing your content intuitive and scalable.
MDX allows you to write content using Markdown syntax while seamlessly integrating React components. This means you can use standard Markdown for your content, but also drop in interactive components, custom styling, or complex layouts whenever you need them. It's the best of both worlds - the simplicity of Markdown with the power of React.
Shadcn UI provides beautiful and accessible components out of the box. These components are built on Radix UI primitives, ensuring they're fully accessible and follow best practices. The design system is customizable and follows modern design principles, making it easy to create a cohesive look and feel across your site.
Dark Mode support is built-in and works seamlessly with Next.js and the theme system. Users can toggle between light and dark modes, and their preference is automatically saved. The theme system is designed to work with CSS variables, making it easy to customize colors and styles.
Markdown Examples
This section demonstrates various Markdown features and how they render in the template. Each example shows how you can structure your content to create engaging, readable articles and documentation.
Text Formatting
Regular text looks like this. You can make text bold to emphasize important points or italic to add subtle emphasis. These formatting options help you create visual hierarchy and guide readers through your content.
You can also highlight code inline when you need to reference specific functions, variables, or technical terms. This is particularly useful when writing technical documentation or explaining code concepts. For longer code examples, you can create code blocks that support syntax highlighting:
function greet(name: string) { return `Hello, ${name}!`;}Lists
Lists are a great way to organize information and break up long paragraphs. They make content more scannable and easier to digest, especially when presenting multiple related items or steps in a process.
Unordered lists work well for items that don't have a specific order or sequence:
- Next.js provides the framework and routing system
- React powers the component architecture
- TypeScript adds type safety and better developer experience
- Tailwind CSS handles styling with utility classes
Ordered lists are perfect for step-by-step instructions or when the sequence matters:
- Install dependencies using your preferred package manager
- Write your content in MDX files within the content directory
- Deploy to your hosting platform of choice
Blockquotes
Blockquotes are perfect for highlighting important information, quotes, or callouts. They create visual emphasis and draw attention to key points in your content. Use them sparingly to maintain their impact.
MDX combines the simplicity of Markdown with the power of React components. This makes it an ideal choice for content creators who want the ease of writing in Markdown while having the flexibility to add interactive elements when needed.
You can use blockquotes for various purposes - highlighting key concepts, sharing quotes from other sources, or creating callout sections that stand out from the regular content flow.
Links
Links are essential for connecting your content to external resources, related articles, or documentation. They help readers dive deeper into topics and provide context for the information you're sharing.
When writing content, make sure your links are descriptive and provide value to the reader. Instead of "click here," use meaningful link text that describes what the reader will find when they click:
- Check out the GitHub repository to see the source code and contribute to the project
- Visit shadcn/ui for comprehensive component documentation and examples
- Learn more about MDX to understand how it works and explore advanced features
Good linking practices improve the user experience and help search engines understand the relationships between different pieces of content.
Images
Images are automatically enhanced with the Media component, which provides lightbox functionality out of the box. This means readers can click on any image to view it in full size within a beautiful overlay. The lightbox includes smooth animations and makes it easy to view images in detail without leaving the page.
The image component handles optimization automatically, ensuring fast loading times and good performance. Images are lazy-loaded by default, which means they only load when they're about to come into view, improving initial page load times.
You can also use images with explicit dimensions when you need more control over how they're displayed. This is useful when you want to ensure consistent sizing or when working with images that have specific aspect ratios:
For optimal performance and automatic dimension handling, you can use static imports with the Media component. This approach automatically extracts width and height from the image, preventing layout shift:
import heroImage from "@/public/image.webp";
<Media src={heroImage} alt="Hero Image" />;Static imports provide better performance and automatic aspect ratio calculation, ensuring your images display correctly without any layout shift. The component automatically extracts the image dimensions and applies the correct aspect ratio to prevent layout shift.
All images support standard Markdown syntax, making it easy to add visual content to your articles. The component handles responsive sizing automatically, so your images will look great on all devices.
YouTube Videos
Embedding YouTube videos is straightforward with the YouTube component. The component uses Next.js optimized third-party loading, which means videos load faster and don't impact your site's performance. The implementation uses lite-youtube-embed under the hood, providing a lightweight solution that only loads the full YouTube player when the user clicks play.
This approach significantly improves page load times and reduces the initial JavaScript bundle size. Videos are lazy-loaded by default, so they won't affect your site's performance until users actually interact with them.
The YouTube component accepts all standard YouTube player parameters, giving you full control over how videos are displayed and played. This makes it easy to create custom video experiences that match your content's needs.
Bookmarks
The Bookmark component automatically fetches and displays rich link previews with metadata from any URL. This creates beautiful, informative link cards that show the title, description, image, and domain of the linked content. The component fetches Open Graph and Twitter Card metadata to provide a rich preview experience.
When you add a bookmark, it automatically extracts the most relevant information from the linked page, making it easy for readers to understand what they'll find when they click through. The component includes smooth loading states and handles errors gracefully, ensuring a great user experience even if metadata isn't available.
You can use bookmarks to highlight important resources, reference articles, or create curated link collections. The component is fully responsive and includes hover effects that make it clear the card is clickable. All bookmarks open in a new tab with proper security attributes to protect your readers.