
Sitemaps are documents that can be leveraged to help web crawlers analyze your website/blog more effectively.

They are especially useful for large sites with lots of content. [Read more about sitemaps to see if they're right for your use case](https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview)

## Sitemap Structure
Sitemaps are most commonly written in XML.

Generally they contain an `xml` tag to declare versioning and encoding, and a `urlset` to list out site URLs:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://www.noahmatsell.ca/</loc>
  </url>
  <url>
    <loc>https://www.noahmatsell.ca/blog</loc>
  </url>
</urlset>
```

Site URLs are declared using a child `url` tag. Inside each `url` tag, you need at minimum a `loc` child tag which declares the URL. Other optional child tags for a `url` entry include `lastmod`, `changefreq`, and `priority`. [Read more about these tags here.](https://www.sitemaps.org/protocol.html)

## Building Script
Adding entries to a sitemap manually is perfectly valid, but it can become tedious. Especially if you have a really large site — like a blog with many posts. Manual entry can also be error prone, and relies on you remembering to make updates every time a new page is created.

The problem of list and updating URLs for a sitemap is a great candidate for automation. The following will help you automate the process of creating a `sitemap.xml` file for your website, and populate this file with all of the URLs desired.

### 1. Create script file
Create `build-sitemap.ts` script, that we will populate in the following steps:

```ts
// build-sitemap.ts
async function generate() {
  ...
}

generate();
```

### 2. Define Your Dynamic Pages
Inside the `generate` function, we start by getting an array all posts with their slugs and publish date:
```ts
// build-sitemap.ts
...
const allPosts = getAllPosts(["slug", "publishDate"])
  .filter((post) => {
    return Boolean(post.publishDate && post.slug);
  })
  .map((post) => {
    return { ...post, slug: `blog/${post.slug}` };
  }) as PageEntry[];
...
```
This code takes advantage of my blog's `getAllPosts` function, which reads all of my `.md` files and returns the requested metadata fields (in this case `slug` and `publishDate`). You can learn more about setting this up in [my blog post here](https://www.noahmatsell.ca/blog/nextjs-convert-to-md-blog), or [jump straight to the code here](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-convert-to-md-blog/api.ts#L62).

### 3. Define Your Static Pages
Next, we can manually build a list of any other URLs we want to include:
```ts
// build-sitemap.ts
const staticPages = [{ slug: "" }, { slug: "resume" }, { slug: "blog" }];
```

Alternatively, if you can use a tool like globby to get all pages in specified folders using pattern matching
  - First install `globby` using npm or yarn
  - Then define the glob pattern to find your pages:
  ```ts
  ...
  const staticPages = await globby([
    'pages/*.tsx',
    '!pages/_*.tsx',
    '!pages/api',
    '!pages/404.tsx'
  ]);
  ...
  ```
  - This pattern will find all of your pages under the `pages` directory, except for those that have a `_` prefix, your `404` page, and you pages under the `api` route.

I personally don't use globby because I only have a few static pages that I want to include in my sitemap.

### 4. Generate XML Markup
Create a `generateSiteMap` function that will generate the XML markup for your sitemap. Provided an array of page entries, it will loop through the pages and build up a list of child `url` tags under the `urlset` tag.
```ts
// build-sitemap.ts
const ROOT_URL = "https://www.noahmatsell.ca";

interface PageEntry {
  slug: string;
  publishDate?: string;
}

function generateSiteMap(pages: PageEntry[]) {
  return `<?xml version="1.0" encoding="UTF-8"?>
   <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     ${pages
       .map(
         ({ slug, publishDate }) => `
          <url>
              <loc>${`${ROOT_URL}/${slug}`}</loc>
              ${publishDate ? `<lastmod>${publishDate}</lastmod>` : ``}
          </url>`
       )
       .join("")}
   </urlset>
 `;
}
```

Now inside of the `generate` function, I can call this function with my previously defined page arrays:
```ts
// build-sitemap.ts
...
const sitemap = generateSiteMap([...staticPages, ...allPosts]);
...
```

### 5. Format and Write File
Finally, still in the `generate` function nwe can format this file content using prettier (this is optional), and write it to our filesystem:
```ts
// build-sitemap.ts
...
const prettierConfig = await prettier.resolveConfig("./.prettierrc.js");

const formatted = prettier.format(sitemap, {
    ...prettierConfig,
    parser: "html",
  });

writeFileSync("public/sitemap.xml", formatted);
...
```

And that's it. You have a script that will dynamically create your sitemap. It will be written to the `public` folder, and become a live resource when deployed.

### [Review full code here](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-dynamic-sitemap/build-sitemap.ts)

## Triggering Sitemap Build
Now that we have our script, we can run it manually any time from the terminal. My preferred method is using `ts-node` like:
```bash
npx ts-node ./lib/build-sitemap.ts
```

However to fully automate our sitemap generation, we can create a `postbuild` script in your project's `package.json` file:
```json
"scripts": {
  "dev": "next dev",
  "build": "next build",
  "postbuild": "npx ts-node ./lib/build-sitemap.ts",
  ...
```
The beauty of `postbuild` is that it will automatically run any time your site is built for deployment. This means that the latest changes to your site will be reflected automatically in your `sitemap.xml` file.

## Wrapping Up
Give this a try on your Next.js website. Once you've written and deployed this script successfully, you can check out your sitemap live at `yourdomain.com/sitemap.xml`. Ensure that Google always has the latest version of your site by adding this sitemap via the [Google Search Console](https://search.google.com/search-console/about).

How to set up a dynamic sitemap that is created and updated automatically at build time.

Create a Dynamic Sitemap for Your Next.js Blog

My collection of interesting, useful, and trending content for software developers. The Jan 2023 Part 1 edition.

Dev Roundup, Jan 2023 Pt 1


Custom OG images make social link sharing more engaging. If you're using Next.js, setting up dynamic OG images should be a quick and familiar process. It takes advantage of api routes and Vercel Edge Functions.

Here's the high-level setup:
- Install the `@vercel/og` package
- Create a component under the api route `/api/og.tsx`
- Return an `ImageResponse` from that route
- Use this new endpoint (`/api/og`) for your blog's `og:image` meta tags

For the full setup details go here: [**Full Guide**](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation)

The rest of this guide goes over how I used this setup to generate dynamic images with titles, metadata, and images from blog posts.
## Dynamic Content in Your Images
### Unique Post data
- The dynamic data highlighted below will change for each blog post, while everything else will remain static:
  [![dynamic og image data](/blog/og-image.png)](/blog/og-image.png)

- Blog posts are created as markdown files, and each file has frontmatter data that looks like this:
  ```md
  ---
  title: 'Build a Mailchimp Subscribe Form in Next.js'
  description: 'Create and embed a simple Mailchimp subscription form on your Next.js site to build your audience list.'
  author: 'Noah Matsell'
  coverImgUrl: '/blog/cover/mailchimp.png'
  publishDate: '2023-01-04'
  date: '2022-12-28'
  tags:
    - nextjs
    - mailchimp
  categories: 
    - tutorials
  ---
  ```
### `og.tsx` API Route Component
- Start with a [basic component setup seen here](https://vercel.com/docs/concepts/functions/edge-functions/og-image-examples#)
- Inside the component, get your URL parameter data and render them in a component passed to a new ImageResponse:
```tsx
...
try {
  const { searchParams } = new URL(req.url);

  const postTitle = searchParams.get("title");
  const publishDate = searchParams.get("publishDate");
  const readTime = searchParams.get("readTime");
  const coverImgUrl = searchParams.get("coverImgUrl");

  if (!postTitle || !publishDate || !readTime || !coverImgUrl) {
    throw new Error();
  }
  // Build component response below
  return new ImageResponse(
    (
      <div>
        <p>{postTitle}</p>
        <p>{publishDate}</p>
        <p>{readTime}</p>
        <img src={coverImgUrl} />
      </div>
    ),
    {
      width: 1200,
      height: 630,
      fonts: [],
    }
  )
...
```
- The above throws an error if any of the query parameters aren't defined. In these cases, we catch the error and return a generic fallback ImageResponse instead:
```tsx
...
} catch (e) {
  // Build fallback component response below
  return new ImageResponse(
    (<div><h1>Fallback Content</h1></div>),
    {
      width: 1200,
      height: 630,
      fonts: [],
    }
  )
...
```

[See my full, non-simplified `og.tsx` here.](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-dynamic-og-images/og.tsx)

Your dynamic image is now live! Take a look at either `localhost:3000/api/og` or in production at `yourdomain.com/api/og`. Add query parameters to these URLs to test out the dynamic values passed in.
### Update Your Meta Tags
  - The meta tags in my app are contained in an SEO component, which returns a `Head` component from the `next/head` package.
  - Here the `buildOgImageUrl` utility builds the OG image URL with a hostname (based on environment) and url parameters.
  ```tsx
  ...
  const buildOgImageUrl = ({
  title = "",
  publishDate = "",
  readTime = "",
  coverImgUrl = "",
  }: {
    title?: string;
    publishDate?: string;
    readTime?: string;
    coverImgUrl?: string;
  }) => {
    const hostname =
      process.env.NODE_ENV === "development"
        ? "http://localhost:3000"
        : "https://www.noahmatsell.ca";

    const params = `title=${encodeURIComponent(
      title
    )}&publishDate=${encodeURIComponent(
      publishDate
    )}&readTime=${encodeURIComponent(
      readTime
    )}&coverImgUrl=${encodeURIComponent(
      coverImgUrl
    )}`;

    return `${hostname}/api/og?${params}`;
  };
  ...
  ```
  - Finally, inside the SEO component build the full URL and pass it to the `og:image` meta tag
  ```tsx
  ...
  const ogImgUrl = buildOgImageUrl({
    title,
    publishDate,
    readTime,
    coverImgUrl,
  });

  return (
    <Head>
      <title>{`${title} // A Dev's Blog`}</title>
      <meta name="author" content={author} />
      <meta name="description" content={description} /> 
      {/* update og:image with dynamic URL */}
      <meta name="og:image" content={ogImgUrl} />
      <meta property="og:image:type" content={ogImageType} />
      <meta property="og:image:width" content={ogImageWidth} />
      <meta property="og:image:height" content={ogImageHeight} />
    </Head>
  );
  ...
  ```

[See my full SEO.tsx file here.](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-dynamic-og-images/SEO.tsx)

## Gotchas
If you're having issues or seeing errors, check that:
- Node 16+ is installed locally
- Next version > v12.2.3 is installed
- The correct runtime config is set in the `og.tsx` file
- Valid and supported CSS is used in `og.tsx`.
  - [Only a subset of CSS is currently supported](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation#supported-features)

## Wrapping Up
That's all you need to dynamically generate OG images for your site! Once set up, you can rest assured that your links will look good when shared socially.

How I integrated the @vercel/og package into my blog to automatically build a unique OG image for every post.

Generate OG Images Dynamically for Your Blog Posts


Utterances is a free and lightweight comments widget built on GitHub issues. Embed their script on your page(s) and a comments section will automatically render itself. A big selling point for me is that there are no backend requirements. Instead, all you need is a public Github repo.

When posting comments, users need to log in via Github. This can be a barrier for more general audiences, but makes a lot of sense for a tech and developer focused blog.

## Configuring Utterances
[Utterances website](https://utteranc.es/) provides a nice tool to build your script. Go to their site, choose a few configuration options, and copy the output script.

Some of the customizations I made: 
- **`issue-term`** — choose to map your comments section to an issue named by pathname, url, page title, and more.
- **`repo`** — the repo where the Github issues for your comments will be created.
- **`theme`** — choose from 9 different themes.


## Embedding Comments Section in Next.js
Normally with Next.js I would reach for the `next/script` package to embed a script. However I was seeing a caching/dismount bug where the script/comment rendered for the first time, and would incorrectly show for all subsequent pages and posts.

To correctly embed my comments section, I created a custom component that updates and/or removes a Comments section script on render/dismount. This component is embedded in my blog post template and applied to each individual blog post on my site:

```tsx
// CommentsSection.tsx

export const CommentsSection = () => (
  <section>
    <h3 className="text-xl font-bold flex">Comments</h3>
    <div
      ref={(element) => {
        if (!element) {
          return;
        }

        const scriptElement = document.createElement("script");
        scriptElement.setAttribute("src", "https://utteranc.es/client.js");
        scriptElement.setAttribute("repo", "noahub/a-devs-blog");
        scriptElement.setAttribute("issue-term", "pathname");
        scriptElement.setAttribute("theme", "boxy-light");
        scriptElement.setAttribute("crossorigin", "anonymous");
        scriptElement.setAttribute("async", "true");
        element.replaceChildren(scriptElement);
      }}
    />
  </section>
);
```

## End Result
The comments section defined above renders in the post template for all of my blog posts. Each post will map to its own Github issue based on the pathname.

Check it out in the comments section below!



Utterances has made adding a comments section to posts on my blog an easy and painless experience.

A Free & Lightweight Comments Section for Your Blog


In this guide, I'l show you how to create a simple Mailchimp subscribe form component that will look something like this:

![A Mailchimp subscribe form](/blog/mailchimp-form.png "Mailchimp subscribe form")

Along with a [Next.js api route](https://nextjs.org/docs/api-routes/introduction), this form can be used to add subscribers to your Mailchimp audience lists. This solution will also allow you to customize success and error states.

Best of all, this component can be embedded and reused so you can collect email subscribers anywhere/everywhere throughout your app.

## 1. Get MailChimp Credentials
- Get the following credentials from Mailchimp account:
  - `API_KEY` can be found, or created, in your Mailchimp account [***Extras > API Keys***](admin.mailchimp.com/account/api/)
  - `AUDIENCE_ID` can be found from your Mailchimp audience dashboard under ***Manage Audience > Settings***, and then ***Audience Name & Defaults***. This is the audience to which all of your subscribers will be added!
  - `API_SERVER` is the specific "data center subdomain" that is used for your Mailchimp account. This can be found in a few places -- but if you have your API key from the step above, it is appeneded to the end of the key (looks like `us1`, `us18`, etc.). Other ways to find this [are listed in the docs](https://mailchimp.com/developer/marketing/docs/fundamentals/#api-structure).
- Create a `.env` file at the root of your project and create new environment variables:
  ```bash
  MAILCHIMP_API_KEY=<api-key-here>
  MAILCHIMP_API_SERVER=<api-server-here>
  MAILCHIMP_AUDIENCE_ID=<audience-id-here>
  ```

## 2. Set Up Your Form
- Create a form component `components/SubscribeForm.tsx`. This will contain the subscriber's first name and email fields, and/or any other fields you want to collect:
  ```tsx
  // SubscribeForm.tsx
  export const SubscribeForm = () => {
    return (
      <form
      onSubmit={subscribeUser}
      className="grid gap-3 grid-flow-row md:grid-flow-col md:w-fit"
      >
      <label
        className="inline-grid text-sm text-gray-600 leading-[2]"
        htmlFor="FNAME"
      >
        First Name
        <input
          className="bg-blue-50/60 px-2 border-b-2 p-1 border-gray-400 text-gray-900 text-xl rounded-none min-w-[240px] leading-10 focus:outline-none focus:border-blueAccent"
          id="FNAME"
          type="text"
          name="name"
          required
        />
      </label>

      <label
        className="inline-grid text-sm text-gray-600 leading-[2]"
        htmlFor="EMAIL"
      >
        Email
        <input
          className="bg-blue-50/60 px-2 border-b-2 p-1 border-gray-400 text-gray-900 text-xl rounded-none min-w-[240px] leading-10 focus:outline-none focus:border-blueAccent"
          id="EMAIL"
          type="email"
          name="email"
          required
        />
      </label>
      <Button
        variant="secondary"
        type="submit"
        className="md:leading-[0.95rem] mt-4 md:mt-0"
      >
        Subscribe
      </Button>
      </form>
    );
  }
  ```
- Add types based on the fields in your newly created form. **Important**: the `email` and `name` entries in the `FormElements` interface correspond with the input `name` attributes from the form above:
  ```ts
  // SubscribeForm.tsx
  interface FormElements extends HTMLFormControlsCollection {
    email: HTMLInputElement;
    name: HTMLInputElement;
  }

  interface SubscribeFormElement extends HTMLFormElement {
    readonly elements: FormElements;
  }
  ```
- Add a form submission handler. The `subscribeUser` function below gets the form field values and `POST`s them to the `/api/subscribe` route, which we will create in a moment:
  ```tsx
  // SubscribeForm.tsx
  ...
  export const SubscribeForm = () => {
    const subscribeUser = async (
      e: React.SyntheticEvent<SubscribeFormElement>
    ) => {
      e.preventDefault();

      const res = await fetch("/api/subscribe", {
        body: JSON.stringify({
          email: e.currentTarget.elements.email,
          name: e.currentTarget.elements.name
        }),
        headers: {
          "Content-Type": "application/json",
        },
        method: "POST",
      });

      if (res.status === 201) {
        // Custom behaviour on success (like a success message)
        console.log("success");
      } else {
        // Custom behaviour on error (like an error message)
        console.log("error");
      }
    };
  ...
  ```
  - Optionally, replace the success and error console logs with your own custom behaviour. This could include showing a message, a banner, a toast, and much more.
  - *Note:* The form takes advantage of native HTML form validation, so this function triggers only on valid submissions.

[[Full `SubscribeForm.tsx` code]](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-mailchimp-subscribe-form/SubscribeForm.tsx)

## 3. Set Up API Route
- Install the `@mailchimp/mailchimp_marketing` module via yarn or npm.
- Create a file `pages/api/subscribe.ts`
- Set up mailchimp client:
  ```ts
  // subscribe.ts
  import type { NextApiRequest, NextApiResponse } from "next";
  const client = require("@mailchimp/mailchimp_marketing");

  client.setConfig({
    apiKey: process.env.MAILCHIMP_API_KEY,
    server: process.env.MAILCHIMP_API_SERVER,
  });
  ...
  ```
- Create the handler for this api route:
  ```ts
  ...
  export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
  ) {
    const { email, name } = req.body;

    if (!email || !name) {
      return res.status(400).json({ error: "Email and name are required" });
    }

    try {
      const response = await client.lists.addListMember(
        process.env.MAILCHIMP_AUDIENCE_ID,
        {
          email_address: email,
          merge_fields: {
            FNAME: name,
          },
          status: "subscribed",
          tags: ["portfolio"],
        }
      );

      if (response.status >= 400) {
        return res.status(400).json({
          error: `There was an error subscribing to the newsletter.`,
        });
      }

      return res.status(201).json({ error: "" });
    } catch (error) {
      return res
        .status(500)
        .json({ error: (error as Error).message || (error as Error).toString() });
    }
  }
  ```
  - This handler will create a new audience member with the submitted first name (FNAME), email address. The handler also sets the member as "subscribed" status and tagged with "portfolio"

[[Full `subscribe.ts` code]](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-mailchimp-subscribe-form/subscribe.ts)

## More
You can capture more fields and merge fields as outlined by [Mailchimp's Marketing API](https://mailchimp.com/developer/marketing/api/list-members/add-member-to-list/) and [Merge Fields docs](https://mailchimp.com/developer/marketing/docs/merge-fields/#the-basics). If you do add/change fields, be sure to make the corresponding updates in both the `SubscribeForm.tsx` and `subscribe.ts` files.

## Last Thougts
You now have a small, lightweight subscribe form component that can be embedded anywhere in your app. Add it to your "about" page, at the end of your blog posts, on your personal portfolio page, in a banner.

Create and embed a simple Mailchimp subscription form on your Next.js site to build your audience list.

Build a Mailchimp Subscribe Form in Next.js

My collection of interesting, useful, and trending content for software developers. The Dec 2022 edition.

Dev Roundup, Dec 2022

A Markdown-based blog makes writing and publishing content a breeze.

Markdown is a powerful, lightweight markup language that allows you to write structured content using plain text. With Markdown, you can easily format your text and add rich formatting to your blog posts, without the need for complex HTML tags.

If you have a Next.js site and are looking for a better way to write and manage blog content online, Markdown is a tool that merits strong consideration.

Here are the 3 steps you can take to migrate an existing Next.js website to a site that includes a Markdown blog.

## The Migration Steps

### 1. Markdown posts setup
- Create `blog` directory at the root of your project.
  - This is where you will write and store your `md` blog posts.
- Create a sample post `blog/sample.md`
    - Here's an example `.md` file with some frontmatter metadata
    ```md
      ---
      title: 'Writing Effective Readmes'
      author: 'Noah Matsell'
      description: 'How to write an effective Readme for your project repository.'
      coverImgUrl: 'images/22-09-2021.jpg'
      date: '2021-09-22'
      categories: 
        - dev tips
      ---

      # Introduction

      Text content
    ```
- In your project `types` folder, create a `blog.ts` file for your post metadata types. These will represent the frontmatter metadata parsed by your app and are useful when handling blog post data within your React components.
```ts
  // types/blog.ts
  export interface Post {
    title: string;
    description: string;
    author: string;
    coverImgUrl: string;
    date: string;
    categories: Category[];
    content: string;
    slug?: string;
  }
```

### 2. API Setup
- Install [`gray-matter`](https://github.com/jonschlinkert/gray-matter) via npm or yarn.
      - This package is used to parse your `md` blog post metadata from a string or file.
- Create a `lib/api.ts` file to handle getting posts and their contents.
    - Create a `getPostSlugs` function. This generates an array of slugs from the `md` files contained within the new `blog` folder.
    ```ts
    // lib/api.ts
    const postsDirectory = join(process.cwd(), "blog");
    
    export function getPostSlugs() {
      return fs.readdirSync(postsDirectory);
    }
    ```
    - Create a `getPostBySlug` function. This builds up, parses, and returns post data for a given slug and set of fields.
    ```ts
    // lib/api.ts
    export function getPostBySlug(slug: string, fields: (keyof Post)[] = []) {
      const realSlug = slug.replace(/\.md$/, "");
      const fullPath = join(postsDirectory, `${realSlug}.md`);
      const fileContents = fs.readFileSync(fullPath, "utf8");
      const { data, content } = matter(fileContents);

      const postData: Partial<Post> = {};

      // Ensure only the minimal needed data is exposed
      fields.forEach((field) => {
        // set slug to real slug
        if (field === "slug") {
          postData[field] = realSlug;
        }
        // set content to parsed gray matter content
        if (field === "content") {
          postData[field] = content;
        }
        // set other properties 1:1 if they exist
        if (typeof data[field] !== "undefined") {
          postData[field] = data[field];
        }
        // add [draft] tag to unpublished posts in development
        if (
          process.env.NODE_ENV === "development" &&
          field === "title" &&
          data["title"] &&
          !data["publishDate"]
        ) {
          postData[field] = data[field] + " [draft]";
        }
      });

      return postData;
    }
    ```
    - Create a `getAllPosts` function. This gets all existing posts and their post data for a given set of fields.
    ```ts
    // lib/api.ts
    export function getAllPosts(fields: (keyof Post)[] = []) {
      const slugs = getPostSlugs();

      const posts = slugs
        .map((slug) => getPostBySlug(slug, fields))
        // Sort posts by date in descending order
        .sort((post1, post2) => {
          return (post1.publishDate || "0") > (post2.publishDate || "0") ? -1 : 1;
        });

      // Filter out unpublished posts in production
      if (process.env.NODE_ENV === "production") {
        return posts.filter((post) => post.publishDate);
      }
      return posts;
    }
    ```
    [[Full api.ts code]](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-convert-to-md-blog/api.ts)
- Create a `lib/markdownToHtml.ts` file. This is needed to translate the `md` content of a post to html content.
    - Install `remark` and `remark-html` via npm or yarn.
    ```ts
    // lib/markdownToHtml.ts
    import { remark } from "remark";
    import html from "remark-html";

    export default async function markdownToHtml(markdown: string) {
      const result = await remark()
        .use(html, { sanitize: false })
        .process(markdown);
      return result.toString();
    }
    ```

### 3. Component Setup
- Under your `pages` directory, create a `blog` directory.
- Create `pages/blog/[slug].tsx`, a [dynamic route](https://nextjs.org/docs/routing/dynamic-routes) that's responsible for taking your `md` blog posts and turning them into pages!
    - Make a `Post` component, which is a React component that renders the parsed content data of a given blog post.
    ```tsx
    // pages/blog/[slug].tsx
    ...
    interface Props {
      post: PostType;
      morePosts: PostType[];
    }

    export default function Post({ post }: Props) {
      // The component that renders your a blog post.
    }
    ...
    ```
    - The post component can be composed of `Layout`, `PostHeader`, `PostBody` and/or any other presentational components you like. `Post` component.
    - Render your parsed post comment anywhere inside of the `Post` component. Or, create a child `PostBody` component:
    ```tsx
      // components/PostBody.tsx
      ...
      import markdownStyles from "../styles/markdown-styles.module.css";
      const PostBody = ({ content }: Props) => {
        return (
          <div className="max-w-2xl mx-auto">
            <div
              className={markdownStyles["markdown"]}
              dangerouslySetInnerHTML={{ __html: content }}
            />
          </div>
        );
      };
      ...
    ```
- This is where your custom styling and CSS can be applied to the rendered post content. In the example above, I've created `markdown-styles.module.css` and applied it to the rendering `div` tag.

- Make a `getStaticProps` fn
    - Exporting a function called getStaticProps will pre-render a page at build time using the props returned from the function
    ```tsx
    // pages/blog/[slug].tsx
    ...
   export async function getStaticProps({ params }: Params) {
      const post = getPostBySlug(params.slug, [
        "title",
        "date",
        "slug",
        "author",
        "content",
      ]);

      const content = await markdownToHtml(post.content || "");

      return {
        props: {
          post: {
            ...post,
            content,
          },
        },
      };
    }
    ...
    ```
    - The props object is a key-value pair, where each value is received by the page component. It should be a serializable object so that any props passed, could be serialized with JSON.stringify.

    [![getStaticProps diagram](/blog/getStaticProps.svg)](/blog/getStaticProps.svg)


- Make a `getStaticPaths` fn
    - When exporting a function called getStaticPaths from a page that uses Dynamic Routes, Next.js will statically pre-render all the paths specified by getStaticPaths.
    ```tsx
    // pages/blog/[slug].tsx
    ...
    export async function getStaticPaths() {
      const posts = getAllPosts(["slug"]);

      return {
        paths: posts.map((post) => {
          return {
            params: {
              slug: post.slug,
            },
          };
        }),
        fallback: false,
      };
    }
    ...
    ```
    - The paths key determines which paths will be pre-rendered.
    - This is ultimately how we dynamically create all of the blog post pages at build time for the posts in our `blog/` directory.

[![getStaticPaths diagram](/blog/getStaticPaths.svg)](/blog/getStaticPaths.svg)

[[Full [slug].tsx code]](https://github.com/noahub/a-devs-blog/blob/main/code-snippets/nextjs-convert-to-md-blog/%5Bslug%5D.tsx)

## Wrapping up
With these steps in place, your Next.js website will now be able to render Markdown blog content, and you can easily manage and update your blog content using the Markdown syntax.

Your final project structure should look something like this:

```bash
.
├── blog
│   ├── sample.md
│   └── writing-effective-readmes.md
├── components
│   ├── HeroPost.tsx
│   ├── Layout.tsx
│   ├── MorePosts.tsx
│   ├── PostBody.tsx
│   ├── PostHeader.tsx
│   └── PostTitle.tsx
├── lib
│   ├── api.ts
│   └── markdownToHtml.ts
├── pages
│   ├── _app.tsx
│   ├── api
│   ├── blog
│   │   ├── [slug].tsx
│   │   └── index.tsx
│   └── index.tsx
├── styles
│   ├── blog.css
│   ├── globals.css
│   └── markdown-styles.module.css
├── next.config.js
├── package.json
├── postcss.config.js
├── public
├── tailwind.config.js
├── tsconfig.json
└── types
    └── blog.ts
```

## Next steps
Here are some ideas for extending the functionality of your markdown blog in cool ways:
- Add code highlighting via Prism
- Make a blog 'homepage'
- Add a dynamic table of contents
- Add a share button using the Web Share API

A step-by-step guide to adding a markdown blog to an existing Next.js site.

A Dev's Blog

Dev Roundup, Jan 2023 Pt 1

Generate OG Images Dynamically for Your Blog Posts

A Free & Lightweight Comments Section for Your Blog

Build a Mailchimp Subscribe Form in Next.js

Dev Roundup, Dec 2022

Convert a Next.js site to a markdown blog