Adding a new MDX content source

Add a new MDX content source to your website

The Makerkit SaaS boilerplate offers utilities to easily parse and display content with MDX. In fact, the blog and the documentation the boilerplate offers are generated using these utilities.

It can be useful, for you, to extend your website with a new content source.

For example, this website has 4 content sources:

  1. blog posts
  2. snippets
  3. recipes
  4. documentation

In this blog post, we will add a new content source for your application using utilities already built in the app.

Content Folder

First, we need to create a folder where to place our content in. Normally, this can be within your root folder.

For example, let's add a new content source named interviews and use _interviews as folder:

- _interviews
  - interview_01.mdx
  - interview_02.mdx
  - ...

Let's assume the interview has the following interface:

export interface Interview {
  name: string;
  content: string;
  date: string;
}

This can be represented in MDX as:

---
name: "My Interview about building a SaaS with Makerkit"
publishedAt: 2022-08-28
---
Content of the MDX file

Now, let's add some logic to:

  1. Retrieve all the interview slugs, which we use to generate the static pages
  2. Read the data and the content of each interview
import { readDirectory, readFrontMatter } from '~/core/fs-utils';
import { join } from 'path';
const INTERVIEWS_DIRECTORY_NAME = '_interviews';
const interviewsDirectory =
  join(
    process.cwd(),
    INTERVIEWS_DIRECTORY_NAME
  );
export const allInterviews
  = getInterviewsSlugs();
export function getInterview(
  slug: string
) {
  const fileWithExtension = `${slug}.mdx`;
  const fullPath
    = join(interviewsDirectory, fileWithExtension);
  const file
    = readFrontMatter(fullPath);
  if (!file) {
    return;
  }
  const content = file.content;
  const data = file.data;
  return {
    ...data,
    content
  };
}
function getInterviewsSlugs() {
  return readDirectory(
    interviewsDirectory
  );
}

Generating Static pages from our content source

To generate our content source's pages, we will need to use the special getStaticPaths function that Next.js uses to generate static pages.

In our pages folder, let's create a file at pages/interviews/[interview].tsx, and let's add the content to be able to generate our pages:

tsx
function InterviewPage(
  props: React.PropsWithChildren<{
    interview: Interview;
    content: string;
}>) {
  return (
    <>
      <Head>
        <title>{props.interview.name}</title>
      </Head>
      <Layout>
        <MDXRenderer code={props.content} />
      </Layout>
    </>
  )
}
export function getStaticPaths() {
  const paths = allInterviews.map((post) => {
    const slug = post.slug;
    return {
      params: {
        slug,
      },
    };
  });
  return {
    paths,
  };
}
export async function getStaticProps(
  { params }: { params: { slug: string } }
) {
  const { props } =
    await withTranslationProps();
  const interview =
    getInterview(params.slug);
  if (!interview) {
    return {
      notFound: true,
    };
  }
  const content =
    await compileMdx(interview.content ?? '');
  return {
    props: {
      ...props,
      interview,
      content,
    },
  };
}
export default InterviewPage;

Refresh the server each time you add a new MDX file, and navigate to http://localhost:3000/interviews/interview_01.

🎉Yay, we can now read our MDX files in our Makerkit application!