Published 31/03/2024

Publishing using markdown with additional plugins on Next.js

In my previous post, I shared about how and why you should use markdown with your Next.js project to create a blog. In this article, I will explain how you can enhance your content creation experience using markdown on Next.js.

List of features include:

  • Customize the layout of your markdown using react components
  • Use plugins to support more features in your markdown
  • Use the frontmatter extension to add metadata to your article.

Customizing the components of your markdown article

By default, there is no styling applied to generated html code by the default markdown parser. In order to customize and add your own styles, you must first add a mdx-components.tsx at the root of your project directory. You are able to customize the html elements using custom components. Below is a sample of customized components with styling applied.

import type { MDXComponents } from 'mdx/types'

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // Allows customizing built-in components, e.g. to add styling.
    h1: ({ children }) => <h1 className="text-5xl mb-2">{children}</h1>,
    h2: ({ children }) => <h2 className="text-4xl mb-2">{children}</h2>,
    h3: ({ children }) => <h3 className="text-3xl mb-2">{children}</h3>,
    h4: ({ children }) => <h4 className="text-2xl mb-2">{children}</h4>,
    h5: ({ children }) => <h5 className="text-xl mb-2">{children}</h5>,
    h6: ({ children }) => <h6 className="text-lg mb-2">{children}</h6>,
    p: ({ children }) => <p className="text-lg mb-2">{children}</p>,
  }
}

Customizing the layout of your markdown filename

Other than customizing the base elements, we can also utilize the jsx support of mdx file. We can add a custom Layout component that will wrap the markdown content. First we need to create a mdx-layout.tsx file, you can add it to components folder. Style and create your own custom layout like you would in in a regular react component.

// mdx-layout.tsx
const MDXLayout = ({
  children,
}: {
  children: React.ReactNode
}) => {
  return (
    <CustomLayout>
      {props.children}
    </CustomLayout>
  )
}
export default MDXLayout

Add the following code to the markdown file to import the layout

import MdxLayout from '../../../components/mdx-layout'


{/* your markdown content can go here */}

export default function MDXPage(props) {
  return (<MdxLayout filenameWithoutExtension={filenameWithoutExtension} frontmatter={frontmatter}>{props.children}</MdxLayout>
  )
}

Your generated page will now have the custom layout wrapped around your markdown content.

Adding metadata and boost SEO

Add metadata to your markdown content by using frontmatter vscode togther with gray-matter plugin to read and parse the metadata. Add the metadata into your generated html page as meta tag elements to help boost your page SEO.

Install the vscode extension eliostruyf.vscode-front-matter, it is a content management system built directly onto vscode. It has a built-in dashboard to view all markdown files and manage the content and metadata of each markdown file. Use frontmatter to create new content, it will automatically add the metadata at the top of the markdown file. Below is a snippet of how the metadata of the file will look like

---
title: ''
description: ''
date: ''
preview: ''
draft: true
tags: []
categories: []
---

<!-- markdown content here -->

Install remark plugins remark-mdx-frontmatter and remark-frontmatter and add them to the plugin options in the next.config.mjs. Together two libraries will parse the frontmatter content and export the data as a frontmatter object

More documentation on Next.js frontmatter can be found here or on remark-mdx-frontmatter

Adding charts and tables into your markdown

The basic markdown does not have charts or tables. Additional plugins like remark-gfm and rehype-mermaid can be added. remark-gfm adds github flavoured markdown syntax so that we can create tables, tasklist, autolinks and footnotes.

A note[^1]

[^1]: Big note.

<!-- or -->

* [ ] uncompleted task
* [X] completed task

Mermaid is a js based diagram and charting library that can use markdown to create different diagrams like flow charts or sequence diagrams. rehype-mermaid plugin will convert the html code generated by the markdown parser and turn it into svg chart

There you have it! Four different ways to enhance your content writing experience on the frontend code editor using markdown on Next.js. Some simple and easy steps to get your content creation journey on the way.

Tag
markdownnext.jsrehyperemarkfrontmatter
Categories
Technology
contact: work[at]jianhowe.com