How to add markdown footnote support in Astro

I wanted to use markdown footnotes in my Astro blog but the AstroPaper theme did not enable them by default. Here are the (mis)steps I followed to get it working.

GitHub Copilot (with GPT-4.1) suggested remark-footnotes which I had used in the past so I installed it with:

npm install remark-footnotes

However type errors surfaced¹ in VSCode when I installed it. I realzied this might have been caused by using npm (my default) instead of pnpm which is what my Astro theme/blog.

So I uninstalled it and then re-installed with pnpm:

npm uninstall remark-footnotes
pnpm add remark-footnotes

which is when I saw the next issue:

 WARN  deprecated remark-footnotes@5.0.0: Deprecated: use `remark-gfm`
Packages: +1

Solution

So here’s what ended up working:

1. Uninstall remark-foornotes

pnpm remove remark-footnotes

2. Install remak-gfm

pnpm add remark-gfm

3. Update astro.config.ts

Update astro.config.ts to include remark-gfm:

// astro.config.ts
import { defineConfig } from "astro/config";
import remarkGfm from "remark-gfm";
// other imports (rehype/remark you already use)

export default defineConfig({
  // existing config...
  markdown: {
    remarkPlugins: [
      // your existing remark plugins...
      remarkGfm, // footnotes, tables, strikethrough, autolinks, task lists
    ],
  },
  // rest of config...
});

Now I can write a footnote in any .md as follows:

Here is a footnote reference[^1].

[^1]: This is the footnote text.

Footnotes

VSCode is showing this potential error:

img
Type '(options?: void | Options | undefined) => void | Transformer<Root, Root>' is not assignable to type 'string | [string, any] | RemarkPlugin<any[]> | [RemarkPlugin<any[]>, any]'.
  Type '(options?: void | Options | undefined) => void | Transformer<Root, Root>' is not assignable to type 'RemarkPlugin<any[]>'.
    Type 'void | Transformer<Root, Root>' is not assignable to type 'void | Transformer<Root, Root> | undefined'.
      Type 'Transformer<Root, Root>' is not assignable to type 'void | Transformer<Root, Root> | undefined'.
        Type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/unified/index").Transformer<import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/@types/mdast/index").Root, import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/@types/mda...' is not assignable to type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/unified@11.0.5/node_modules/unified/lib/index").Transformer<import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/@types+mdast@4.0.4/node_modules/@types/mdast/index").Root, import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/@types+mdast@4.0.4...'.
          Types of parameters 'node' and 'tree' are incompatible.
            Type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/@types+mdast@4.0.4/node_modules/@types/mdast/index").Root' is not assignable to type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/@types/mdast/index").Root'.
              Types of property 'children' are incompatible.
                Type 'RootContent[]' is not assignable to type 'Content[]'.
                  Type 'RootContent' is not assignable to type 'Content'.
                    Type 'Heading' is not assignable to type 'Content'.
                      Type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/@types+mdast@4.0.4/node_modules/@types/mdast/index").Heading' is not assignable to type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/@types/mdast/index").Heading'.
                        Types of property 'children' are incompatible.
                          Type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/@types+mdast@4.0.4/node_modules/@types/mdast/index").PhrasingContent[]' is not assignable to type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/@types/mdast/index").PhrasingContent[]'.
                            Type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/@types+mdast@4.0.4/node_modules/@types/mdast/index").PhrasingContent' is not assignable to type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/@types/mdast/index").PhrasingContent'.
                              Type 'Text' is not assignable to type 'PhrasingContent'.
                                Type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/.pnpm/@types+mdast@4.0.4/node_modules/@types/mdast/index").Text' is not assignable to type 'import("/Users/hiro/git/andrewhoog-astro/node_modules/remark-footnotes/node_modules/@types/mdast/index").Text'.
                                  Types of property 'data' are incompatible.
                                    Type 'TextData | undefined' is not assignable to type 'Data | undefined'.
                                      Type 'TextData' is not assignable to type 'Data'.
                                        Index signature for type 'string' is missing in type 'TextData'.ts(2322)
(alias) function remarkFootnotes(options?: void | Options | undefined): void | Transformer<Root, Root>
import remarkFootnotes
Plugin to add support for footnotes.

@type — {import('unified').Plugin<[Options?]|void[], Root>}

↩