About the author

Telmo Goncalves is a software engineer with over 13 years of software development experience and an expert in React. He’s currently Engineering Team Lead at Marley Spoon.

Check out more of his work on telmo.is

When I was building my own website and blog, I chose to use Markdown in conjunction with Next.js because it’s easy, fast, and, to be honest, I enjoy writing in Markdown. In this article, I’ll walk through how I did this so you can produce a great, content-driven site of your own.

This article assumes the reader is generally unfamiliar with setting up web applications with tools like npm and the system Terminal. Several steps involve encountering errors and backtracking; this was intentional for the purposes of educating the reader on how the application is architected and the interdependencies of each component.

Those more familiar will be able to skip through some of the explanatory details for each step.

Setting up the project

First, create a folder for your project. Do this by running:

mkdir blog && cd blog

For those new to UNIX commands, this produces a new directory named ‘blog’ (mkdir blog) and navigates to it (cd blog).

Next, install the following dependencies using:

npm init -y && npm install react react-dom next --save

Running npm init will create a package.json file in our project, using -y will skip npm’s default questions. If you like to include this information, just remove it.

Since the site will use next, the scripts in package.json will need to be changed to the following:

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
}

Next, run npm run dev which should start the project on port 3000. Open your browser and navigate to http://localhost:3000.

At this point, an error may be thrown (or the build didn’t complete at all). This is because Next.js is expecting to find a pages directory. This is where you’ll create content pages.

Create the pages directory with an index.js file by running the following:

mkdir pages && touch pages/index.js

Now if you run npm run dev and open http://localhost:3000 in your browser, the following error should be shown:

The default export is not a React Component in page: "/"

This is because the index.js file exists, but it’s empty.

Adding a homepage

First, create a React component index.js at the top of the file:

import React from 'react'

function Homepage() {
  return (
    <h1>Welcome to the Homepage!</h1>
  )
}

export default Homepage

Once saved, Welcome to the Homepage! should be displayed on http://localhost:3000.

You can create many pages as you want (ie - author.js).

Do this by running:

touch pages/author.js

And adding a React component (shown using author.js):

import React from 'react'

function Author() {
  return (
    <>
      <h1>About the Author</h1>

      <p>
        I'm a full-stack engineer with 13+ years of
        experience. I started my career back in 2007
        as a designer, then quickly started coding
        as well.
      </p>
     </>
  )
}

export default Author

Save, and you’ll be able to see the content by opening http://localhost:3000/author in your browser.

Sending props

Here, we’ll dive into how getInitialProps from Next.js works. Above the export default Homepage line on the index .js homepage, add:

Homepage.getInitialProps = () => {
  return {
    blogTitle: 'Rookie for life!'
  }
}

Collective, it should look like this:

import React from 'react'

function Homepage(props) {
  return (
    <h1>Welcome to the blog: {props.blogTitle}!</h1>
  )
}

Homepage.getInitialProps = () => {
  return {
    blogTitle: 'Rookie for life!'
  }
}

export default Homepage

Props (which stands for “property”) are used for passing data from one component to another.

Here a prop is created called blogTitle and passed into the Homepage component. When you access http://localhost:3000, the content should now read: Welcome to the blog: Rookie for life!

The app is passing a prop saying what the value of blogTitle is. If you change it from Rookie for life! to Rockstar! and save, you should see the page update with the new title.

Dynamic routes

Next, let’s create blog articles using Markdown .md files and dynamically load them. Using Markdown files for the content is beneficial because it’s easier to write in them and manage the content.

That way, when a user opens a page like http://localhost:3000/blog/article-name it will render with content written in an article-name.md file.

A great feature of Next.js is that it allows developers to create dynamic files.

Create a dynamic file called [slug].js in a pages/posts/ directory:

mkdir pages/posts && touch pages/posts/[slug].js

Note that the posts directory will be inside of the pages directory.

Now create a posts template using a React component:

import React from 'react'

function PostTemplate(props) {
  return (
    <div>
      Here we'll load "{props.slug}"
    </div>
  )
}

PostTemplate.getInitialProps = async (context) => {
  const { slug } = context.query

  return { slug }
}

export default PostTemplate

This queries the URL and extracts the slug from it. slug is used because that’s the name of the file ([slug].js). If the file were named [id].js, the query would be context.query.id instead.

Now, if you access http://localhost:3000/posts/hello-world you should see: Here we’ll load “hello-world”

If you change hello-world to in the URL awesome-nextjs-blog, the page will display: Here we’ll load “awesome-nextjs-blog”

Rendering Markdown files

The content Markdown files should be stored in a separate directory so they’re easier to manage. Create a content directory and a Markdown file by running:

mkdir content && touch content/awesome-nextjs-blog.md

Upon opening the content directory, there should be a blank awesome-nextjs-blog.md file.

Open the awesome-nextjs-blog.md file and add the following:

---
title: "Build an awesome Next.js blog"
date: "2020-10-01"
---

We're building an awesome Next.js blog using Markdown.

Now open [slug].js and add the following above return { slug }:

  // Import our .md file using the `slug` from the URL
  const content = import(`../../content/${slug}.md`)

So collectively, it looks like this:

PostTemplate.getInitialProps = async (context) => {
  const { slug } = context.query

  // Import our .md file using the `slug` from the URL
  const content = import(`../../content/${slug}.md`)

  return { slug }
}

The application is now querying slug from the URL and loading an .md file with that slug.

Markdown files contain frontmatter data. This is information defined in the section divided off using the --- markers in the .md file. To parse that in some way. To parse that, use gray-matter.

This can be installed by running:

npm install gray-matter --save

Now update the [slug].js template to import matter and parse the .md content:

import React from 'react'
import matter from 'gray-matter'

function PostTemplate(props) {
  return (
    <div>
      Here we'll load "{props.slug}"
    </div>
  )
}

PostTemplate.getInitialProps = async (context) => {
  const { slug } = context.query
  
  // Import our .md file using the `slug` from the URL
  const content = await import(`../../content/${slug}.md`)
  
  // Parse .md data through `matter`
  const data = matter(content.default)
  
  // Pass data to our component props
  return { ...data }

  return { slug }
}

export default PostTemplate

If you reload the page, you should see an error: TypeError: expected input to be a string or buffer

This will need to be resolved by adding a Next.js configuration file. Do this by running:

touch next.config.js

Open the newly created next.config.js and add the following configuration:

module.exports = {
  webpack: function(config) {
    config.module.rules.push({
      test: /\.md$/,
      use: 'raw-loader',
    })
    return config
  }
}

This requires the raw-loader package, so that will need to be installed as well by running:

npm install raw-loader --save

Keep in mind that any time an update is made to the next.config.js configuration file, it’s best to restart the application.

Now reopen the post template and update the PostTemplate component to handle the frontmatter data:

function PostTemplate({ content, data }) {
  // This holds the data between `---` from the .md file
  const frontmatter = data

  return (
    <>
      <h1>{frontmatter.title}</h1>
    </>
  )
}

Then in the same component, add <p>{content}</p> for rendering the Markdown content:

function PostTemplate({ content, data }) {
  // This holds the data between `---` from the .md file
  const frontmatter = data

  return (
    <>
      <h1>{frontmatter.title}</h1>
      <p>{content}</p>
    </>
  )
}

You should now see the title: Build an awesome Next.js blog As well as: We’re building an awesome Next.js blog using Markdown

Markdown formatting

Finally, the application will need to convert the content we have written in Markdown so it renders to users in the expected format.

Add the following to awesome-nextjs-blog.md:

---
title: "Build an awesome Next.js blog"
date: "2020-10-01"
---

## Step 1

- Install dependencies
- Run locally
- Deploy to Vercel

This will display the content as plain text in the browser. To render the content written in Markdown; install react-markdown by running:

npm install react-markdown --save

Then in the [slug].js file, import ReactMarkdown and update the PostTemplate component to replace <p>{content}</p> with <ReactMarkdown source={content} />.

Collectively it should look like this:

import React from 'react'
import matter from 'gray-matter'
<ReactMarkdown source={content} />

function PostTemplate({ content, data }) {
  // This holds the data between `---` from the .md file
  const frontmatter = data

  return (
    <>
      <h1>{frontmatter.title}</h1>
      <ReactMarkdown source={content} />
    </>
  )
}

PostTemplate.getInitialProps = async (context) => {
  const { slug } = context.query
  
  // Import our .md file using the `slug` from the URL
  const content = await import(`../../content/${slug}.md`)
  
  // Parse .md data through `matter`
  const data = matter(content.default)
  
  // Pass data to our component props
  return { ...data }

  return { slug }
}

export default PostTemplate

Now you’re all set! If you’re new to Markdown, check out this handy cheat sheet which is great to reference as you’re learning the ropes.

Telmo regularly posts helpful React development tips and guides on Twitter. Be sure to follow him at @telmo