How to Add GitHub-Flavored Markdown Support (Tables, etc.) with MDX

Install remark-gfm and add it to your remarkPlugins array in the MDX configuration file to enable tables, task lists, strikethrough, and footnotes.

The woosal1337/blog repository is a Next.js 14 blog built with the App Router that renders MDX files as pages. By default, Next.js's built-in MDX support only parses standard Markdown syntax. This guide shows you exactly how to extend the MDX pipeline with GitHub-flavored Markdown (GFM) support using the remark-gfm plugin, based on the actual source code structure of the repository.

---

Key Files in the GFM Integration

File	Purpose
mdx-components.tsx	Custom Tailwind-styled components for rendered MDX elements including tables
lib/mdx-options.mjs	MDX compiler configuration where remarkPlugins are injected
next.config.mjs	Next.js configuration that connects MDX options to the build pipeline
package.json	Dependency declarations including remark-gfm

---

Step 1: Install the remark-gfm Package

Add the official remark plugin that parses GFM extensions into the MDX AST.

bun add remark-gfm

This single package enables tables, task lists, strikethrough, autolinks, and footnotes in your MDX content.

---

Step 2: Configure remarkPlugins in lib/mdx-options.mjs

Open lib/mdx-options.mjs and extend the exported configuration object with a remarkPlugins array containing remark-gfm.

// lib/mdx-options.mjs
import remarkGfm from "remark-gfm";

export const mdxOptions = {
  // Preserve existing rehype configuration
  rehypePlugins: [
    // existing plugins...
  ],
  remarkPlugins: [
    // Add GFM support
    remarkGfm,
  ],
};

Import the plugin using ESM syntax as shown, then include it in the array. The MDX compiler processes these plugins in order during the build.

---

Step 3: Connect MDX Options in next.config.mjs

The next.config.mjs file bridges your options to Next.js's MDX loader. Import the configuration object and pass it to the loader.

// next.config.mjs
import { mdxOptions } from "./lib/mdx-options.mjs";

const nextConfig = {
  // other Next.js configuration...
  webpack: (config, { dev, isServer }) => {
    config.module.rules.push({
      test: /\.(md|mdx)$/,
      use: [
        {
          loader: "@next/mdx",
          options: mdxOptions,
        },
      ],
    });
    return config;
  },
};

export default nextConfig;

If your project uses @next/mdx via the built-in experimental MDX support, this wiring ensures your remarkPlugins are active during compilation.

---

Step 4: Style Rendered Tables with mdx-components.tsx

The repository already includes a custom table component that receives GFM tables from the MDX compiler. Located in mdx-components.tsx, this component wraps tables with responsive overflow handling and Tailwind styling.

// mdx-components.tsx
export const mdxComponents = {
  table: ({ children, ...props }) => (
    <div className="my-8 overflow-hidden rounded-[14px] border border-line bg-transparent">
      <div className="overflow-x-auto">
        <table
          {...props}
          className={cn(
            "w-full border-collapse text-footnote [&_tbody_tr:last-child_td]:border-b-0",
            props.className
          )}
        >
          {children}
        </table>
      </div>
    </div>
  ),
  // other components...
};

When remark-gfm parses a Markdown table into a <table> element, this component renders it with horizontal scroll on mobile, consistent borders, and proper typography. No additional styling code is required.

---

Step 5: Write GitHub-Flavored Markdown in Your Posts

With the pipeline configured, use GFM features directly in any .mdx file:

## Feature Comparison

| Feature       | Supported | Notes                  |
|:--------------|:---------:|------------------------|
| Tables        | ✅        | Responsive, styled     |
| Task Lists    | ✅        | Clickable checkboxes   |
| Strikethrough | ✅        | ~~like this~~          |
| Footnotes     | ✅        | Superscript links      |

## Task List

- [x] Install `remark-gfm`
- [x] Configure `mdx-options.mjs`
- [ ] Deploy to production

The MDX compiler transforms this into structured JSX, then the custom components in mdx-components.tsx apply the visual layer.

---

Step 6: Verify in Development

Start the development server and test GFM rendering:

bun dev

Navigate to a post containing tables and verify:

• Tables display with the rounded border wrapper and horizontal scroll behavior
• Task list items render as checkboxes with proper state indicators
• Strikethrough text appears with a line through it
• Build completes without remark or MDX errors

Once verified, the configuration persists through production builds (bun run build).

---

Summary

• remark-gfm is the standard plugin for adding GitHub-flavored Markdown to MDX
• Configuration lives in lib/mdx-options.mjs via the remarkPlugins array
• next.config.mjs imports and applies these options to the MDX loader
• mdx-components.tsx provides styled components that render parsed GFM elements
• No changes to individual MDX files are needed—GFM features work immediately after configuration

---

Frequently Asked Questions

What GFM features does remark-gfm enable?

Tables, task lists (checkboxes), strikethrough, autolinks, and footnotes. The plugin parses these into standard MDX AST nodes that your components can then style.

Can I use remark-gfm with other remark plugins?

Yes. Add them to the same remarkPlugins array in lib/mdx-options.mjs. The array order determines execution sequence—place remarkGfm before any plugins that transform table or list nodes if they depend on GFM parsing.

Why are my tables not styled even with remark-gfm installed?

The plugin parses syntax into JSX elements, but visual styling requires a custom component. Ensure mdx-components.tsx exports a table component and that it's passed to the MDX provider or configured as the components map in your MDX rendering setup.

Does this work with Next.js 13 or older versions?

The file structure applies to Next.js 14 with App Router. For older versions using pages/, the configuration location differs—MDX options typically go in next.config.js directly or via @next/mdx in pages/_app.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}