Next.js MDX Blog Kit is a developer-focused boilerplate for creating a static blog with Next.js and MDX, built to achieve perfect Lighthouse scores out of the box. It gives you a complete blogging system where you only have to write posts and style the blog to make it your own.
What is Next.js MDX Blog Kit?
Next.js MDX Blog Kit is an open-source starter repository from GitHub user lorenseanstewart that provides a complete blogging system on the Next.js framework. It takes markdown and MDX files as input—which can include embedded React components—and produces a statically deployable blog with SEO metadata, tag search, and offline support. The kit is designed so that the only two required tasks are writing posts and styling the blog.
What makes Next.js MDX Blog Kit stand out?
- Perfect Lighthouse scores — The kit is engineered to score 100% on Lighthouse audits, as shown in the included screenshot.
- Static website deployment — Generates static HTML that can be deployed anywhere, with easy one-command deployment via Zeit's Now platform.
- MDX support — Write posts in markdown and use React components inline, or use plain React if you prefer.
- CLI for scaffolding — A CLI tool creates new pages and posts with all required meta data, using flags like
-tfor template type,-mfor MDX, and-ffor file name. - Service worker offline caching — All pages are cached for desktop, and visited pages are cached for mobile users, enabling offline reading.
- Tag search — Posts are organized with tags, and a search page at
/search/?q=tagNamelets readers filter by tag. - Reading progress indicator — An optional progress bar on posts (via scrollProgress) can be disabled per post with a
hideProgressBarmeta property. - Code syntax highlighting — Uses
react-syntax-highlighterfor JavaScript syntax highlighting, with example components in the code-snippets folder. - Optimized images — Integrates
next-optimized-imagesto optimize image loading. - Jest testing — Unit tests are pre-configured using Jest.
Who should use Next.js MDX Blog Kit?
Next.js developers who want a pre-built blog instead of starting from scratch will find the CLI and blog engine save setup time. Technical content creators who write in markdown and need SEO-friendly publications can publish posts without touching underlying code. Developers exploring MDX and React component composition in markdown can use the included examples as a learning reference. Teams looking to ship a company blog with offline support and tag search can deploy it quickly to Now.
What can you do with Next.js MDX Blog Kit?
- Personal bloggers: Author posts in MDX and use the CLI to add them to the blog, with automatic SEO and tag pages.
- React developers: Customize the blog engine, add new layouts, and embed interactive React components directly inside markdown posts.
- Technical writers: Publish documentation as a static site with smooth-scroll navigation, reading progress, and offline access.
- Open-source maintainers: Set up a project blog with perfect Lighthouse scores and deploy it through Now in one command.
How does it work?
The kit includes a blog engine that extracts the meta object from each page and post component, constructs additional properties, and builds a sorted post list. The utils/page-list.js and utils/post-list.js files use the Babel Preval plugin to read filenames from the pages directories. Global configuration lives in /config/config.yml, where you set author, site name, navigation links, and brand colors. To create content, run blog -t post after installing the CLI with npm link, and the CLI generates the proper meta data. The kit also includes a Service Worker file (my-worker.js) with comments on caching behavior.
FAQ
How do I create a new blog post?
Use the CLI with blog -t post to generate a new post file. The -f flag lets you name the file; if omitted, the CLI creates a randomized name that you should rename. You can also create MDX posts with the -m flag.
What meta data is required for each post?
Each page or post must export a meta object with fields including title, tags, layout, publishDate, and seoDescription. Optional fields like hideProgressBar and exclude control the reading progress bar and whether the post appears on the blog list.
How do I add images to an MDX post?
Import the image at the top of your MDX file, e.g., import imageUrl from "../../public/static/images/mountains.jpg";, then use it with a normal img tag and the imported path as src.
How does offline caching work?
The service worker caches every page for desktop users, so the entire blog is available offline after first visit. For mobile users, only pages that have been visited are cached. The developer notes these observations are informal and may vary by browser and device.
Can I customize the fonts?
Add font files to /static/fonts and define @font-face rules in /styles/index.js. The included font is Abril Fatface, and the project uses font-display: auto; to balance performance and loading.
