How I created a blog using Next.js and MDX

Photo by Blake Connally on Unsplash

I recently created a blog for hosting few JavaScript notes for personal use. You can view the website here.

Initially, I decided to go with Markdown, since it is simple and easy to create content without any styling as opposed to writing full-blown HTML posts.

However, I realized soon that the styling options are very limited and it’s impossible to get my post to look like I imagined.

This is how it currently looks,

the trimmed version of post page design

This design couldn’t have been made with just markdown. I started to look for other options and came across MDX. Putting simply it’s simply Markdown and JSX combined, so you can add components in your markdown file now. That looked promising.

This page has all the information to get started.

I cloned this repository and started to play with it.

The first thing I did was to update next.config.js

This started to load .mdx files from pages/ directory

All that was remaining was to create components as per my design and import them in post. Here is a sample post

This is supposed to be flexbox.mdx. Since gist doesn't preserve formatting for mdx files renamed as jsx

If you are going to use the above code, save the file as *.mdx file instead of jsx

As you can see this file has both markdown as well as jsx. I also used bootstrap for the accordion. To include the bootstrap CSS you need to import it in _app.css

The next big challenge was to deploy this site with GitHub pages. This looked easy as Next.js builds all the files in the out folder and then all we have to do is to move these files to the gh-pages branch.


As mentioned above I added these scripts to my package.json file

"build": "next build","export": "next export","next-deploy": "yarn build && yarn export",

This was working fine but after I moved the out directory contents to the gh-pages branch, the site was deployed however none of the routing or the CSS files were getting loaded correctly.

After a lot of research and trial and error found correct values for basePath and assetPrefix to be added in next.config.js

In short, since my site was hosted at, next.js was not aware of the jsnotes folder, the build was done for the site to be running at root location.

The other problem was with .nojekyll file to be pushed in out folder. This needed so that _next contents will be copied to the server. This was solved by a -d out flag for gh-pages

touch out/.nojekyll && gh-pages -d out -t true

This is my updated next.config.js and scripts section of package.json

The updated scripts section of package.json

The further improvement in the site is to use basePath and assetPrefix values conditionally using environment variables since now you have to constantly switch them while working locally or deploying.

You can view the deployed site here

Also, check my portfolio

Follow me on GitHub and Twitter




I am a Frontend Developer from Montreal, Canada. I write about everything that fascinates me.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Angular 11: PART 2 Insert external HTML in your own website — Web scraping

JavaScript Runtime For Web Developers — ECMAScript, DOM, And The BOM

JavaScript Runtime For Web

Upload files to GCP using multer , nodejs with visibility as public.

React Weekly Issue 22

// from Twitter

The 6 Pro Tips For Building Great Chrome Extensions

How Lexical Environments affect JavaScript Variables, Hoisting & Closures

React Weekly Issue 33

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Vaibhav Mande

Vaibhav Mande

I am a Frontend Developer from Montreal, Canada. I write about everything that fascinates me.

More from Medium

Nextjs 12 with Antd-Less

Next.JS : Build a SaaS using Static Site Generation (SSG) with custom domains

NEXT.JS: Build a Saas Using SSG and custom domains.

Building a modern website with Contentful and React

## Intended audience