Forem: Jashn Maloo

Making MDX blog with Nextjs - Part 2

Jashn Maloo — Mon, 19 Oct 2020 00:00:00 +0000

In the last post we finished with adding mdx files, getting slug and other details for index page and completed index page for posts.
I recommend you to get going by completing the part-1 first if you haven't done it. It's the base for what we're going to do now.

All we gotta do now is to add that dynamic page we talked in the last post. I know I'm moving directly in the building part without discussing anything right now, but it's better this way.
So let's get going.

Repo: mdx-blog-with-nextjs

Live: Next MDX Blog

1. Adding post fetching logic

Before we start making our dynamic page for posts, we've to add some logic regarding how and what are we fetching in that file. So in the end of /lib/posts.js file,
we'll be adding two functions, one for fetching slugs to attact to each page and one for all the content for each page we are fetching in the first function.

//Get slugs
// ./lib/posts.js

//...
export const getSortedPosts = () => {
  //...
};

//Get Slugs
export const getAllPostSlugs = () => {
  const fileNames = fs.readdirSync(postDirectory);

  return fileNames.map((filename) => {
    return {
      params: {
        slug: filename.replace(".mdx", "")
      }
    };
  });
};

//Get Post based on Slug
export const getPostdata = async (slug) => {
  const fullPath = path.join(postDirectory, `${slug}.mdx`);
  const postContent = fs.readFileSync(fullPath, "utf8");

  return postContent;
};

Here,

getAllPostSlugs is creating and fetching slugs from all the posts
getPostData is used to find content of the post by navigating to the file using slug it gets as parameter and returns post content.

These two functions are the master functions because using these two functions only, we'll be getting all our content and pages.

2. Making [slug].js page

Now that we've the logic to get slug and post from that slug, let's finally build the [slug].js page.

If you're familiar with dynamic routing is react, we use :id or something like that for dynamic pages, and render page by matching URL parameters with all the data available. Once data is found,
it dispatches to the page according to the page design.
Nextjs has a better way to handle this(atleast what I feel). As you know nextjs has file based routing, wouldn't it be challenging to make a different page for each posts with similar styles and components?
That's where the [dynamicPageName].js types of files come in action. Such file name tells next that the content of this file depends on the URL parameter user is visiting so next handles it that way only.

In the /blog directory make a file named [slug].js and add the following content to it -

// ./blog/[slug].js

/** @jsx jsx */
import { getAllPostSlugs, getPostdata } from "../../lib/posts";
import { Box, jsx, Text, Divider, Flex } from "theme-ui";
import matter from "gray-matter";

export default function Posts({ source, frontMatter }) {
  return (
    <Box sx={{ variant: "containers.page" }}>
      <Box sx={{ mt: "4rem" }}>
        <h1>{frontMatter.title}</h1>
        <Divider color="muted" />
        <Box>{source}</Box>
      </Box>
    </Box>
  );
}
export async function getStaticPaths() {
  const paths = getAllPostSlugs();
  return {
    paths,
    fallback: false
  };
}
export async function getStaticProps({ params }) {
  const postContent = await getPostdata(params.slug);
  const { data, content } = matter(postContent);

  return {
    props: {
      source: content,
      frontMatter: data
    }
  };
}

Isn't this mostly like the index page we built earlier? So what makes it dynamic apart from the filename?
This time we've another function provided by nextjs, getStaticPaths and the role this plays is simple but quite important.

As we know that all the posts will be created at build time, so that means our dynamic page will be statically generated, interesting right?
So getStaticPaths returns an array of all the URL paramaters possible for our dynamic page based on the data/posts we've created.
Here, it fetches all the slugs from the getAllPostSlugs function we added in ./lib/posts.js file and returns an array of it. Now all the URL parameters in thsi array are pre-rendered by nextjs.
That means Next.js will generate all the posts route in the build time only.
And fallback here is false to give 404 error for paths not returned by getStaticPaths. You can read more about it in official documentation.

For all the paths pre-rendered, URL parameter is passed into getStaticProps, which fetches post content belonging to that param, thus pre-rendering all the paths and pages with their content statically.
Here, We are collecting front-matter details in data variable and post content in content variable with gray-matter.
And as usual, all this data is passed onto the page component above.

Messy, right?

3. Adding Components to MDX

One of the main aspect differring mdx with md is using components within itself. So let's create two simple custom components.
Make a components folder in the root directory and add the following two components-

// ./components/MyButton.js

/** @jsx jsx */
import { Button, jsx } from "theme-ui";

const MyButton = ({ text, check }) => {
  return (
    <Button sx={{ width: "100%", bg: check ? "steelblue" : "coral", my: 2 }}>
      {text}
    </Button>
  );
};

export default MyButton;

// ./components/MyBackground.js

/** @jsx jsx */
import { jsx } from "theme-ui";

const MyBackground = ({ children }) => {
  return <div sx={{ bg: "cornsilk", py: 1 }}>{children}</div>;
};

export default MyBackground;

Let's add these components to our posts.

// getting-started-with-mdx.mdx

---
//...front-matter
---
import MyButton from "../components/MyButton.js"
import MyBackground from "../components/MyBackground.js";

//...rest of the content

<MyBackground>

 [MDX](https://mdxjs.com) is markdown for component era.

</MyBackground>

<MyButton text="Click"/>

// some-random-points.mdx

---
//...
---
import MyButton from "../components/MyButton.js"


//...

<MyButton check text="Click"/>

And this is how the post will look now

Unable to understand what's written in the post? Yeah, ditto!
If it would've been a markdown file, we could've used remark, remark-html or react-markdown to convert markdown to html.
But it's an mdx file and we're using components in it, how can we show our file the way it is meant to be shown?

And that's where a problem arises. Natively we can render mdx files with components easily, but first, we're rendering them through a dynamic route to save ourselves from repitition and drastic memory usage. Secondly,
we've front-matter in it, and MDX does not support rendering of front-matter natively.
So what's the solution now, we want our mdx files to show content, components and front-matter.
This is where I got lost for few days, but you don't have to.

There are two workarounds for this -

next-mdx-enhanced: It overcomes with some of the problems of @next/mdx and renders MDX files with a common layout, provides a way to get components and front-matter render in the post and few extra features that we probably don't need. But it does require little bit of extra config for a super smooth rendering experience.
next-mdx-remote: By the same developer, but ~50% faster, more flexible and easier to use. It refines some of the issues of next-mdx-enhanced. But this is what we'll be using.

Although next-mdx-remote is awesome, it does have one caveat which we'll understand once we start using it.

4. Using next-mdx-remote

Install next-mdx-remote

npm i next-mdx-remote

And now it's time to modify our champ [slug].js. We'll be adding and modifying a good amount of code, so let's just rebuild it

// ./blog/[slug].js

/** @jsx jsx */
import Head from "next/head";
import { getAllPostSlugs, getPostdata } from "../../lib/posts";
import { Box, jsx, Text } from "theme-ui";
import renderToString from "next-mdx-remote/render-to-string";
import hydrate from "next-mdx-remote/hydrate";
import matter from "gray-matter";
import MyBackground from "../../components/MyBackground";
import MyButton from "../../components/MyButton";

const components = { MyBackground, MyButton };

export default function Posts({ source, frontMatter }) {
  const content = hydrate(source, { components });
  return (
    <>
      <Head>
        <title>{frontMatter.title}</title>
      </Head>
      <Box sx={{ variant: "containers.page" }}>
        <Box sx={{ mt: "4rem", textAlign: "center" }}>
          <h1>{frontMatter.title}</h1>
          <Text
            sx={{
              width: ["80%", "50%"],

              mx: "auto"
            }}
          >
            {frontMatter.author}
            {" / "}
            <span>{frontMatter.date}</span>
          </Text>
        </Box>
        <Box sx={{ mt: "4rem" }}>
          <Box>{content}</Box>
        </Box>
      </Box>
    </>
  );
}
export async function getStaticPaths() {
  const paths = getAllPostSlugs();
  return {
    paths,
    fallback: false
  };
}
export async function getStaticProps({ params }) {
  const postContent = await getPostdata(params.slug);
  const { data, content } = matter(postContent);
  const mdxSource = await renderToString(content, {
    components,
    scope: data
  });
  return {
    props: {
      source: mdxSource,
      frontMatter: data
    }
  };
}

We added next-mdx-remote and two functions from it, renderToString and hydrate.

renderrToString runs at build time, so it's included in getStaticProps. It returns an object of MDX content with components it utilizes.
The object returned by renderToString now gets passed into hydrate along with the location of components we're using inside our MDX.This hydrate function initially renders static content and hydrate it when browser's not busy with other tasks.

If you now visit your http://localhost:3000/blog/getting-started-with-mdx route, you'll get an error

It is pointing that error is in our [slug].js file in line 52. And that's because it is the line that preapres MDX file for rendering and for determining components in it. So that means we've a problem in our MDX files? Hell Yeah.
And this is where we discuess the limitations of next-mdx-remote.

next-mdx-remote does not allow adding import inside MDX files, therefore to use components, we've to pass them in second argument in hydrate and renderToString functions and that's what we did in the code above.
So if we remove the import lines from our MDX files, and visit our post, we'll have this -

Pretty amazing, right?

Front-matter ✔️
Formatted content ✔️
Components rendering ✔️

So we've completed our blog? Kind of, but there's one problem left.
Remember how we cannot add import in MDX file while working with next-mdx-remote and that we've to import components while we're rendering it. According to the official docs of next-mdx-remote,
while adding components to hydrate function, components should be the exact same components that were passed to renderToString.
And in that case, if we've to make different pages for each post to render, what's the point of doing all this hard work? I totally get you, and so I've a workaround here, it works decently with the things we've setup in 2 lengthy posts.

Currently, we're passing the components of getting-started-with-mdx post in the hydrate function by importing them in [slug].js, now suppose you've few more components being used by several posts. So what simple step we're gonna take is,
create AllComponents.js file in components folder and add all the components in there. Once exported, AllComponents will pass required components to the posts which utilize them.

// ./components/AllComponents.js

import MyBackground from "./MyBackground";
import MyButton from "./MyButton";
//import as many components you're using collectively in all your posts

const AllComponents = {
  MyButton,
  MyBackground
  // Any other component you want
};

export default AllComponents;

And now, replace the components you added in [slug].js with AllComponents

// ./blog/[slug].js

//... Other import statements

//Replace MyButton, Mybackground import with AllComponents
import AllComponents from "../../components/AllComponents";

//Replace {MyButton, MyBackground} with AllComponents
const components = AllComponents;

//Rest of the file remains same
export default function Posts({ source, frontMatter }) {
  //...
}

Voila! our blog is ready.
You're good to go. Use n number of components in your MDX, all you gotta do is to add that component in your AllComponents file and wuhoo!, you can render n number of posts without any issue.

Optional

Apart from the whole process we just completed, if you want to provide custom styles/components to native markdown components like H1, H2, lists, link, Image, etc. You can use MDXProvider.

Working with MDXProvider

npm i @mdx-js/react

Because I'm using theme-ui, I'll be using it to provide custom styling to my markdown components.
In your components folder, add MDXCompProvider.js and add the following

// ./components/MDXProvider.js

/** @jsx jsx */
import { MDXProvider } from "@mdx-js/react";
import { Heading, Text, jsx, Box, Link, Flex } from "theme-ui";

export default function MDXCompProvider(props) {
  const state = {
    h1: (props) => <Heading as="h1" sx={{ mt: "3", mb: "2" }} {...props} />,
    h2: (props) => <Heading as="h2" sx={{ mt: "3", mb: "2" }} {...props} />,
    h3: (props) => <Heading as="h3" sx={{ mt: "3", mb: "2" }} {...props} />,
    h4: (props) => <Heading as="h4" sx={{ mt: "3", mb: "2" }} {...props} />,
    p: (props) => <Text as="p" sx={{ mb: "2", lineHeight: "2" }} {...props} />,
    a: (props) => (
      <Link as="a" sx={{ color: "secondary", fontWeight: "bold" }} {...props} />
    )
  };

  return (
    <MDXProvider components={state}>
      <Box {...props} />
    </MDXProvider>
  );
}

Here we are providing our components to be used instead of native markdown h1, h2, p, etc. You can do a lot of customizations here according to your need.

Wrapping blog with MDXProvider

Last step, We just need to wrap our Next.js blog with MDXProvider so that it can be applied automatically to our MDX files.
Open _app.js and wrap <Component {...pageProps} /> with the MDXCompProvider we just created.

// ./pages/_app.js

import "../styles/globals.css";
import { ThemeProvider } from "theme-ui";
import theme from "../theme";
import MDXProvider from "../components/MDXProvider";

function MyApp({ Component, pageProps }) {
return (
  <ThemeProvider theme={theme}>
      <MDXProvider>
        <Component {...pageProps} />
      </MDXProvider>
    </ThemeProvider>
  );
}
export default MyApp;

So we're finally done with creating our MDX blog with Next.js.

It's a lengthy process if you're new to it. Once you know the stuff, it'll be smooth af!

It's my first tutorial/technical blog, hope you like it.

Peace ✌

Making MDX blog with Next.js - Part 1

Jashn Maloo — Mon, 12 Oct 2020 00:00:00 +0000

When I thought of making a blog with Next.js, the first technology that came in my mind was MDX, because why not? With Next.js, it's a superpower with features like -

It is treated just like any other page
One can insert react based components
Can be imported as components to other files
Super fast. There's no runtime.
Being markdown based, it's simple and very flexible to use

What about SEO ?
Well, it's supported as well, add front-matter to it, parse it with gray matter or similar library and you're good to go.
(I use next-seo for SEO in Next.js apps, but it won't be covered in this series. You can watch this amazing tutorial for next-seo.)

Prerequisites

You should be well versed with basics of React. Knowledge of Next.js is a plus, but I will be discussing some foundations of Next.js.

So What's the process ?

I won't say it's super easy because I've spent days trying several ways to implement all the above discussed points. But once you know it, it's a cheesecake.
Of the problems generally faced with SEO, components, parsing, I'll be discussing them as we move forward. Rest assured, it'll be a complete tutorial for building your own MDX blog.

Considering that I'll go in as much details as I can, it will be 2 part series. First one will definitely be long, but easy. We'll do the basic setup, with theming, essential pages, functions will be created in this post,
while the next one will cover dynamic routing, handling components, front-matter in the post.

Repo: mdx-blog-nextjs

1. Initializing project

Bootstrap Next.js project with npx create-next-app and provide name to your project. In this case I'll be calling my project mdx-blog.
After it is done, cd into the project directory(our root directory).

This is how a typical Next.js folder structure looks like -

pages folder is the one where all the routes respond to in Next.js, so that's really important.

2. Adding styles & dependencies

Let's install most of the dependencies now. I'll discuss about these as we start using these. You can use yarn or npm according to your choice, I'm going with npm.

npm i theme-ui @theme-ui/presets gray-matter @next/mdx

For this project, I'm using theme-ui as my UI library and for syntax highlighting in thee blog, you can go with whatever you like, Chakra UI or Material UI or any other.
So We're installing theme-ui and its other packages with gray-matter for extracting SEO details from MDX files, next-seo for inserting meta data in our pages and @next/mdx for MDX files support in Next.js

Now let's create theme.js file in root directory to provide a theme preset and basic styles, and add the following to it -

// ./theme.js

import { roboto } from "@theme-ui/presets";

const theme = {
  ...roboto,

  containers: {
    page: {
      width: "98%",
      maxWidth: "840px",
      m: 0,
      mx: "auto",
      justifyContent: "center",
      height: "100%",
      py: "1rem",
      px: ["0.4rem", "2rem"],
    },

    postCard: {
      p: "2",
      borderRadius: "4px",
      border: "1px solid #eeeeee",
      width: "100%",
    },
  },

  text: {
    heading: {
      py: "0.4rem",
    },
  },
};

export default theme;

It contains basic styling enough to build a decent looking blog, rest we'll be doing inside our pages.

Okay, theme done. Now we goota make our _app.js file ready, it is a supereme file, just like index.js in CRA.
Many UI libraries require ThemeProvider at the global level, so let's add it in _app.js

// ./_app.js

import "../styles/globals.css";
import { ThemeProvider } from "theme-ui";
import theme from "../theme";

function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider theme={theme}>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

export default MyApp;

Once done, make Next.js config file next.config.js in the root directory. In next.config.js, add the following code

// ./next.config.js

const withMDX = require("@next/mdx")();

module.exports = withMDX({
  pageExtensions: ["js", "mdx"],
});

This config file is required to tell Next.js that we're using MDX files, so it should treat them as regular pages.
After this, you can literally start building pages in MDX in the pages folder and you'll be ablle to see them in your browser. But we're building a blog, so there are more things involved.

3. Writing first MDX file

So we're ready to make MDX pages, make a folder named posts in the root directory and make two MDX files, then add the following content

// ./posts/getting-started-with-mdx.mdx
---
title: "Getting started with MDX"
date: "2020-10-10"
author: "MDX Team"
excerpt: "Making this in MDX for simplicity and flexibility"
---

## Why MDX ?

❤️ **Powerful**: MDX blends markdown and JSX syntax to fit perfectly in
React/JSX-based projects.

💻 **Everything is a component**: Use existing components inside your
MDX and import other MDX files as plain components.

🔧 **Customizable**: Decide which component is rendered for each markdown
element (`{ h1: MyHeading }`).

📚 **Markdown-based**: The simplicity and elegance of markdown remains,
you interleave JSX only when you want to.

🔥 **Blazingly blazing fast**: MDX has no runtime, all compilation occurs
during the build stage.

[MDX](https://mdxjs.com) is markdown for component era.

// ./posts/some-random-points.mdx

---
title: "Writing random points"
date: "2020-10-09"
author: "Jashn Maloo"
excerpt: "World is random in what it does, so let's write something random"
---


## Some random points

- Isn't writing in markdown lovely?
- Aren't components so reusable?
- Why is Next.js so fantastic?
- Please give me 2021.

### Some random heading

Cool, but it's not yet ready to be shown on our site. Because it's outside our pages directory, first we'll make index page for all the posts we'll have and slug out of these file.

Make a lib folder in your root directory. A lib folder generally contains all that code that is needed to get information in pages to run properly.
In the lib folder, make a file named posts.js and add the following code to it

// ./lib/posts.js

import fs from "fs";
import path from "path";
import matter from "gray-matter";

//Finding directory named "posts" from the current working directory of Node.
const postDirectory = path.join(process.cwd(), "posts");

export const getSortedPosts = () => {
  //Reads all the files in the post directory
  const fileNames = fs.readdirSync(postDirectory);

  const allPostsData = fileNames.map((filename) => {
    const slug = filename.replace(".mdx", "");

    const fullPath = path.join(postDirectory, filename);
    //Extracts contents of the MDX file
    const fileContents = fs.readFileSync(fullPath, "utf8");
    const { data } = matter(fileContents);

    const options = { month: "long", day: "numeric", year: "numeric" };
    const formattedDate = new Date(data.date).toLocaleDateString(
      "en-IN",
      options
    );

    const frontmatter = {
      ...data,
      date: formattedDate,
    };
    return {
      slug,
      ...frontmatter,
    };
  });

  return allPostsData.sort((a, b) => {
    if (new Date(a.date) < new Date(b.date)) {
      return 1;
    } else {
      return -1;
    }
  });
};

Okay so it's a good amount of code, wait until we add more to it xD, but let's understand what happened here.

First, we fetched the directory named posts from our root. Then with the help of node's fs package we read all the contents in the posts folder.
allPostData function is doing the chunk of work here -

First we made slug for each file in posts directory
We fetched the content of each file by joining the directory and filename.
Contents from front matter is fetched in data
We changed the date format to be visible on the index page. You can totally skip this part, it's not necessary.
We updated our frontmatter and returned slug and frontmatter to allPostData function
If you want your posts to be sorted in some way in index file, that's what we're doing next. Latest to oldest here.

Woof! So much here, but it's very much same to what you can find in Next's docs or some other articles.
Now we're ready to show the posts on our index page, so let's create one.

4. Creating Index of all posts

I want my blog posts route to be /blog/post/, so make a folder named blog in the pages directory and inside that, create a index.js file. Now when we'll start
our app /blog route will point to this index file.

I'll now share the code, but beware if it's your first time working with dynamic pages in Next.js, high chances that few lines will go over your head, but it's alright, I'll describe everything that's happeneing.
So, add the below content to your ./blog/index.js/ file.

// ./blog/index.js

/** @jsx jsx */
import { jsx, Flex, Heading, Box, Text } from "theme-ui";
import Link from "next/link";
import { getSortedPosts } from "../../lib/posts";

const BlogIndex = ({ allPostsData }) => {
  return (
    <>
      <Box sx={{ variant: "containers.page" }}>
        <Heading>My Blog</Heading>
        <Flex
          sx={{
            flexWrap: "wrap",
            mt: "2rem",
            direction: "column",
          }}
        >
          {allPostsData.map(({ slug, date, title, excerpt }) => (
            <Box variant="containers.postCard" sx={{ my: "0.5rem" }} key={slug}>
              <li
                sx={{
                  display: "flex",
                  flexDirection: ["column", "row"],
                  my: "1rem",
                }}
              >
                <Box>
                  <Link key={slug} href="/blog/[slug]" as={`/blog/${slug}`}>
                    <a>
                      <Heading
                        sx={{
                          fontSize: "calc(1.6rem + 0.2vw)",
                          fontWeight: "500",
                        }}
                      >
                        {title}
                      </Heading>
                    </a>
                  </Link>

                  <Box sx={{ my: "0.5rem" }}>{excerpt}</Box>

                  <Text>{date}</Text>
                </Box>
              </li>
            </Box>
          ))}
        </Flex>
      </Box>
    </>
  );
};
export default BlogIndex;

export async function getStaticProps() {
  const allPostsData = getSortedPosts();
  return {
    props: {
      allPostsData,
    },
  };
}

So it's just the layout of the index page? How are we fetching posts here?

I've got the answers, don't worry. It's more than just the layout of index page.
First, if you're curious what are those variants or sx or that jsx I wrote on the top, they all are related to theme-ui and variants is how we connect that theme.js file we made earlier with the concerned component,
so if you're using some other UI library, you don't need to import these things.

So about fetching posts, we're importing getSortedPosts from posts.js we created in lib folder.
What this function will do is, it'll store all the posts in allPostsData, which then can be returned to the page above(BlogIndex here) just like props in a react component.

Now if you're new to Next.js, you might be asking what is this getStaticProps and what role is it playing here?
So in version 9.3, Next.js included getStaticProps and getServerSideProps for fetching data in the page without using any other library. And if you compare the names
you might get an idea of what do they do. getStaticProps fetches all the data at build time, making our website static, just like Gatsby. While getServerSideProps fetches data on runtime, just like many other server rendered websites.
Although both are SEO friendly, getStaticProps being static really adds up to the website performance. It is the one returning props to the page above.

Ah! so much of getStatic, getServerSide, right? Well, people like these.

Now I guess the last thing bothering you might be, "what's with the Link component, why it's being so weird?".
So as I said earlier, I want by posts to be on route /blog/post-name. We'll have a lot of posts as time will pass and we can't just make many such index components for each file, so we need dynamic routing here and that's how it is handled in Next.js.
First we told href that the link will be of style /blog/[slug] so it knows it's dynamic, and then we're telling as prop what the actual value is.

Now it's still not clear, don't worry, once we will make the page for showing full post, it'll be more clear.

For now, let's run our code to see how it looks. In your terminal, make sure you're in the directory of your project, the run this

npm run dev

This will start next server on post 3000. And once you go to http://localhost:3000/blog, if you see something like the image below, you're going good

And if there are some troubles, maybe just contact me and I'll try my best to make it work for you.

So that's the end of part-1 of Making MDX blog with Next.js. In the next and final part, we'll discuss some common issues of handling components, front-matter and MDX, while completing this blog.