A starter template for building static blogs with Gatsby.js and MDX, where Markdown content can include interactive React components and still output as a fast static site.
What is Gatsby MDX Blog Starter Project?
Gatsby MDX Blog Starter Project is a boilerplate starter for creating a blog on the Gatsby.js static site generator. It accepts Markdown and MDX files as input and outputs a static website with blog post listings, category pages, and pagination. The project is maintained by Robin Wieruch and is used in production by Egghead.io, Kent C. Dodds, and Robin Wieruch's own website.
Key features
- MDX authoring — Write posts in Markdown and embed React components directly; see the
content/blog/mdx-examplefile for a working example. - Prism.js syntax highlighting — Code blocks are highlighted with Prism.js, making it suitable for technical tutorials.
- Pagination — Blog index automatically paginates posts, so readers can navigate through archives.
- Categories — Posts can be organized into categories, with generated pages per category.
- External dependencies — MDX allows importing third-party React components, such as a YouTube player embedded in a post.
- Gatsby-based — Runs on Gatsby.js and React, so you benefit from Gatsby's plugin ecosystem and static site performance.
Who is it for?
- Technical bloggers — who want to publish Markdown posts with live React examples, embedded videos, or interactive code sandboxes.
- Open-source maintainers — looking for a documented blog starter that's already used by high-traffic sites like Egghead.io.
- Frontend developers — learning Gatsby and MDX; this starter offers a complete, working reference project to extend.
- Course creators — who need to combine written lessons with media components, as demonstrated by Egghead.io's usage.
What can you do with Gatsby MDX Blog Starter Project?
- Embed media — Insert a YouTube player inside a Markdown post using MDX, without writing HTML.
- Build a code blog — Publish tutorials with highlighted code via Prism.js and categorize them by topic.
- Launch a personal site — Use the starter's pagination and category pages to grow a content archive over time.
- Create a documentation hub — Mix long-form Markdown with React components for interactive API examples.
How does the starter work?
- Clone the repository with
git clone [email protected]:rwieruch/gatsby-mdx-blog-starter-project.git, or rungatsby new my-blog [email protected]:rwieruch/gatsby-mdx-blog-starter-project.git. - Install dependencies using
npm install. - Start development with
gatsby developand visithttp://localhost:8000. - Add a new post by creating an MDX file in
content/blog; the example atcontent/blog/mdx-exampleshows the expected format.
FAQ
How do I start a new blog with this template?
Run gatsby new your-blog-name [email protected]:rwieruch/gatsby-mdx-blog-starter-project.git, then npm install and gatsby develop. Your site will be available at http://localhost:8000.
What is MDX?
MDX is a format that lets you write JSX components inside Markdown. In this starter, it means blog posts can include interactive React elements, such as a YouTube video player, in addition to standard Markdown text and code blocks.
Does the starter include everything I need for a blog?
It includes core blogging features: an MDX content folder, category support, pagination, and Prism.js syntax highlighting. You can extend it with other Gatsby plugins as your site grows.
Who uses this starter?
The project lists Egghead.io, Kent C. Dodds, and Robin Wieruch as users. This means the starter is battle-tested for developer-focused blogs and educational content.
