How to integrate Markdown in Remix.run

MDX routes modules

The easiest way to integrating Markdown into Remix is probably to use MDX route modules

---
title: Remix Markdown
---

# A routes module using MDX

If you’re using Vite, we need to add MDX Rollup plugin. Please follow guide here

Markdown from Remote Server (Github)

Fetching markdown content

This way, we are able to review new blog posts without re-deploy

Github provides a solution to retrieve data through REST API

1
export const fetchGithub = (path: string) => {
2
  const token = '<your_access_token>';
3
  const owner = '<your_github_owner>';
4
  const repo = '<your_repo>';
5

6
  const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path ?? ''}`
7

8
  const res = await fetch(url, {
9
    method: 'GET',
10
    headers: {
11
      'Accept': 'application/vnd.github.v3.raw',
12
      'User-Agent': '<your_app_name>',
13
      'X-GitHub-Api-Version': '2022-11-28',
14
      'Authorization': `Bearer ${token}`
15
    }
16
  });
17

18
  if(!res.ok || !res.body) throw res;
19

20
  return res;
21
}
22

23
export const getMarkdown = (path: string) => {
24
  const res = await fetchGithub(path);
25
  const content = await res.text();
26
  return content;
27
}
28

29
/**
30
* Get all markdown file from your repository
31
*/
32
export const getFilesMarkdown = (path: string) => {
33
  const res = await fetchGithub(path);
34
  const files = await res.json();
35

36
  return await Promise.all(
37
    files
38
      .filter(file => file.path.endsWith('.md'))
39
      .map(async file => getMarkdown(file.path))
40

41
  )
42
}

How to parse front-matter

Installation front-matter

npm i front-matter

import fm from 'front-matter';

export const getMarkdown = (path: string) => {
  const res = await fetchGithub(path);
  const content = await res.text();
  return content;
  return { attributes, body } = fm(content);
}

Transforming Markdown to HTML

npm i react-markdown

import type { LoaderFunctionArgs } from '@remix-run/cloudflare';
import { useLoaderData } from '@remix-run/react';
import { getMarkdown } from '~/github.server';
import ReactMarkdown from 'react-markdown';

export const loader = ({ params }: LoaderFunctionArgs) => {
  const { slug } = params;
  if(!slug) throw new Error('Page not found.');
  const post = await getMarkdown(`${slug}.md`);
  if(!post) throw new Error('Page not found.');
  return post;
}

export default function BlogDetail() {
  const { attributes, body } = useLoaderData();

  return (
    <article>
      <h1>{attributes.title}</h1>
      <ReactMarkdown>{body}</ReactMarkdown>
    </article>
  )
}

Custom React Markdown

Simply follow the official guide to custom React Markdown

npm i remark-gfm rehype-raw

import rehypeRaw from "rehype-raw";
import remarkGfm from "remark-gfm";

...
export default function BlogDetail() {
  const { attributes, body } = useLoaderData();

  return (
    <article>
      <h1>{attributes.title}</h1>
      <ReactMarkdown>{body}</ReactMarkdown>
      <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeRaw]}>{body}</ReactMarkdown>
    </article>
  )
}
...

Syntax Highlighting

npm i shiki

import CodeBlock from '~/components/code-block';

...
export default function BlogDetail() {
  const { attributes, body } = useLoaderData();

  return (
    <article>
      <h1>{attributes.title}</h1>
      <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeRaw]}>{body}</ReactMarkdown>
      <ReactMarkdown
        remarkPlugins={[remarkGfm]}
        rehypePlugins={[rehypeRaw]}
        components={{
          pre: CodeBlock
        }}
      >{body}</ReactMarkdown>
    </article>
  )
}
...

1
import { useEffect, useState, ReactElement } from 'react';
2
import { codeToHtml } from 'shiki';
3

4
export default function CodeBlock({ children, className }: { children?: any; className?: any }) {
5
  const childrenArray = Children.toArray(children);
6
  const codeElement = childrenArray[0] as ReactElement;
7
  const className = codeElement?.props?.className || '';
8
  const code = codeElement.props.children[0] || '';
9
  const lang = className?.replace(/language-/, '');
10
  const [highlightedCode, setHighlightedCode] = useState<string>();
11
  useEffect(() => {
12
    if (!code) return;
13

14
    codeToHtml(
15
      code, {
16
        lang,
17
        theme: 'catppuccin-mocha'
18
      }
19
    ).then(setHighlightedCode);
20
  }, [code, lang]);
21

22
  if (!code) return null;
23

24
  return (
25
    <pre className="bg-slate-800 text-slate-400 p-4 rounded overflow-x-auto">
26
      {highlightedCode
27
        ? (<code dangerouslySetInnerHTML={{ __html: highlightedCode }} />)
28
        : (<code>{code}</code>)
29
      }
30
    </pre>
31
  );
32
}

Shiki Highlighting + Cloudflare Worker bundle small

A Worker can be up to 10 MB in size after compression on the Workers Paid plan, and up to 1 MB on the Workers Free plan

But if using Shiki the build folder size also increase from ~1MB to ~10MB, you could not deployed that current release to Worker if you’re using Free Plan

✘ [ERROR] Failed to publish your Function. Got error: Your Functions script is over the 1 MiB size limit (workers.api.error.script_too_large)

To resolve it, we should load the Shiki Script from esm.sh, which helps reduce the build folder size because of skipping Shiki.

1
import { codeToHtml } from 'shiki';
2

3
export default function CodeBlock({ code, lang = 'typescript' }: { code?: string, lang?: string }) {
4
  ...
5
  useEffect(() => {
6
    if(!code) return;
7

8
    codeToHtml(
9
      code, {
10
        lang,
11
        theme: 'catppuccin-mocha'
12
      }
13
    ).then(setHighlightedCode);
14
    // @ts-expect-error: load shiki from esm.sh to avoid large worker bundle
15
    import('https://esm.sh/shiki@1.23.1').then(async ({ codeToHtml }) => {
16
      setHighlightCode(await codeToHtml(code, {
17
        lang,
18
        theme: 'catppuccin-mocha', // theme shiki
19
      }))
20
    })
21
  }, [])
22
  ...
23
}

Fetching multiple Markdown Files

Usually, you want to display a list of all your content to users as well. GitHub offers an API endpoint to get all files within a directory. From there, we can fetch each file content and parse the frontmatter. This should give us all the information required to render a list of contents.

/**
* Get all markdown file from your repository
*/
export const getFilesMarkdown = (path: string) => {
  const res = await fetchGithub(path);
  const files = await res.json();

  return await Promise.all(
    files
      .filter(file => file.path.endsWith('.md'))
      .map(async file => getMarkdown(file.path))

  )
}

Caching Response Github

GitHub throttles the number of requests you can make to their API. To avoid this, we can cache the responses from GitHub. If you’re using Cloudflare Worker, you can use KV Namespaces to cache its