Create MDX Powered Blog in Next.js With One Script (10-20 seconds)

This script automates the process of setting up a mdx based blog section in a new Next.js site. It installs necessary packages, configures the project, and creates sample blog posts.

The whole process takes something around 10-20 seconds(mostly waiting for npm packages to install) and you are ready to go.

Why make this script?

Anytime I have to setup a markdown based blog in next.js, it always results in lot of plubming work.

And whenever I do, it mostly results in the following steps:

Forget how did I do it last time
Explore alternatives (contentlayer great but abandoned), nothing catches the eye.
Go to nextjs/mdx documentation
Follow the steps
Encounter lot of errors as this is a setup heavy process although not difficult.
Finally get it working
Forget how I did it this time
Repeat

Need to for automation was neigh.

Why only one script?

Anything more defeats the purpose, also a simple bash script is easy to understand and modify by anyone as per their needs.

Prerequisites

Node.js and npm installed
A Next.js project set up

You should have installed next.js like this, basically going with the defaults:

  npx create-next-app@latest mynextjs-site --use-npm                                                               ok
✔ Would you like to use TypeScript? … No
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? …  Yes
✔ Would you like to use `src/` directory? … No
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to customize the default import alias (@/*)? … No

Reasoning for above choices

This is a typical next.js setup for me because:

Like javascript over typescript
Always use tailwind css
No need for src directory.
I do use app router as it is recommended

If you have a different setup, you can always modify the script to suit your needs. It will be a simple process of changing may be js vs ts extension on files or changing the file paths.

The styling is kept at a minimum, as that is a personal choice. Modify as per your needs.

Usage

Place the create-blog.sh script in the root of your Next.js project.
Make the script executable:
```
chmod +x create-blog.sh
```
Run the script:
```
 ./create-blog.sh
```
Start the development server:
```
npm run dev
```
Visit http://localhost:3000/blog to see the sample blog posts.

How do I create a new blog post?

Create a new .mdx file in the content directory.
Add the following front matter to the file and write your blog post content:

---
title: "My New Blog Post"
description: "This is a sample blog post."
date: "2024-07-07"
category: "Personal"
---

# Sample Blog Post

Why did chicken cross the road?. I finally found the answer.

That's it! Your new blog post will be automatically added to the blog listing page. Please note slug is generated from the file name. So, saving the file as my-new-blog-post.mdx will generate a slug of my-new-blog-post.

Steps Performed by the Script

Install Necessary npm Packages
- Installs @next/mdx, @mdx-js/loader, @mdx-js/react, @types/mdx, @tailwindcss/typography, gray-matter, and next-mdx-remote.
Update tailwind.config.js
- Replaces plugins: [] with plugins: [require("@tailwindcss/typography")].
Rename next.config.js to next.config.mjs
- Renames the configuration file and updates its content to support MDX.
Create Content Directory and Sample Blog Posts
- Creates a content directory and adds sample .mdx blog posts.
Create Components Directory and mdx-layout.jsx File
- Creates a components directory and adds an MDX layout component.
Create Blog Pages
- Creates pages/blog directory and adds index.js for listing blog posts.
- Creates pages/blog/[slug] directory and adds index.js for individual blog posts.
Modify Global CSS
- Appends custom styles to app/globals.css.
Modify app/page.js
- Adds an import statement for next/link if it doesn't exist.
- Replaces a specific <p> element with a <div> element containing a link to the blog.

Visual Guide

Once you run the script and run the development server, you will see a blog link in the top left navigation bar.

On clicking the blog link, you will see the sample blog posts.

Sample Blog Post

Mobile View

Conclusion

I do believe there are/can be different ways to achieve the same thing in a more efficient manner. That's the thing with code. But this works for me and I hope it works for you too.