feat: add support for footnotes in markdown parsing

package.json

@@ -32,6 +32,7 @@
     "remark-gfm": "^1.0.0",
     "remark-math": "^4.0.0",
     "remark-parse": "^9.0.0",
+    "remark-footnotes": "^3.0.0",
     "unified": "^9.2.1"
   },
   "devDependencies": {

src/index.ts

@@ -10,6 +10,7 @@ import {
 import type * as md from './markdown';
 import gfm from 'remark-gfm';
 import remarkMath from 'remark-math';
+import footnotes from 'remark-footnotes';
 
 /**
  * Parses Markdown content into Notion Blocks.
@@ -22,7 +23,12 @@ export function markdownToBlocks(
 
   options?: BlocksOptions,
 ): notion.Block[] {
-  const root = unified().use(markdown).use(gfm).use(remarkMath).parse(body);
+  const root = unified()
+    .use(markdown)
+    .use(gfm)
+    .use(remarkMath)
+    .use(footnotes)
+    .parse(body);
   return parseBlocks(root as unknown as md.Root, options);
 }
 
@@ -37,6 +43,6 @@ export function markdownToRichText(
   text: string,
   options?: RichTextOptions,
 ): notion.RichText[] {
-  const root = unified().use(markdown).use(gfm).parse(text);
+  const root = unified().use(markdown).use(gfm).use(footnotes).parse(text);
   return parseRichText(root as unknown as md.Root, options);
 }

src/markdown/ast.ts

@@ -23,6 +23,8 @@ import type {
   TableContent,
   Text,
   ThematicBreak,
+  FootnoteReference,
+  FootnoteDefinition,
 } from './types';
 
 export function text(value: string): Text {
@@ -191,3 +193,21 @@ export function tableCell(...children: PhrasingContent[]): RowContent {
     children: children,
   };
 }
+
+export function footnoteReference(identifier: string): FootnoteReference {
+  return {
+    type: 'footnoteReference',
+    identifier,
+  };
+}
+
+export function footnoteDefinition(
+  identifier: string,
+  ...children: FlowContent[]
+): FootnoteDefinition {
+  return {
+    type: 'footnoteDefinition',
+    identifier,
+    children,
+  };
+}

src/markdown/types.ts

@@ -154,6 +154,7 @@ export type FlowContent =
   | Image
   | ImageReference
   | ThematicBreak
+  | FootnoteDefinition
   | Content
   | Table
   | Math;
@@ -162,7 +163,11 @@ export type Content = Definition | Paragraph;
 
 export type ListContent = ListItem;
 
-export type PhrasingContent = Link | LinkReference | StaticPhrasingContent;
+export type PhrasingContent =
+  | Link
+  | LinkReference
+  | StaticPhrasingContent
+  | FootnoteReference;
 
 export type StaticPhrasingContent =
   | Image
@@ -179,3 +184,14 @@ export type StaticPhrasingContent =
 export type TableContent = TableRow;
 
 export type RowContent = TableCell;
+
+export interface FootnoteReference extends Node {
+  type: 'footnoteReference';
+  identifier: string;
+}
+
+export interface FootnoteDefinition extends Parent {
+  type: 'footnoteDefinition';
+  identifier: string;
+  children: FlowContent[];
+}

src/parser/internal.ts

@@ -56,6 +56,11 @@ function parseInline(
     case 'inlineMath':
       return [notion.richText(element.value, {...copy, type: 'equation'})];
 
+    case 'footnoteReference': {
+      const ref = element as md.FootnoteReference;
+      return [notion.richText(`[${ref.identifier}]`, copy)];
+    }
+
     default:
       return [];
   }
@@ -329,6 +334,17 @@ function parseNode(
     case 'math':
       return [parseMath(node)];
 
+    case 'footnoteDefinition': {
+      const id = node.identifier;
+      const content: notion.RichText[] = [];
+      node.children.forEach(c => {
+        if (c.type === 'paragraph')
+          c.children.forEach(ch => content.push(...parseInline(ch)));
+      });
+
+      return [notion.paragraph([notion.richText(`${id}. `), ...content])];
+    }
+
     case 'thematicBreak':
       return [notion.divider()];
 

test/integration.spec.ts

@@ -242,6 +242,25 @@ const hello = "hello";
 
       expect(actual).toStrictEqual(expected);
     });
+
+    it('should parse footnotes', () => {
+      const text = 'Here is some text.[^1]\n\n[^1]: Footnote definition.';
+
+      const actual = markdownToBlocks(text);
+
+      const expected = [
+        notion.paragraph([
+          notion.richText('Here is some text.'),
+          notion.richText('[1]'),
+        ]),
+        notion.paragraph([
+          notion.richText('1. '),
+          notion.richText('Footnote definition.'),
+        ]),
+      ];
+
+      expect(actual).toStrictEqual(expected);
+    });
   });
 
   describe('markdownToRichText', () => {

test/parser.spec.ts

@@ -454,4 +454,23 @@ describe('gfm parser', () => {
 
     expect(actual).toStrictEqual(expected);
   });
+
+  it('should parse footnotes', () => {
+    const ast = md.root(
+      md.paragraph(md.text('Hello'), md.footnoteReference('1')),
+      md.footnoteDefinition('1', md.paragraph(md.text('Footnote content'))),
+    );
+
+    const actual = parseBlocks(ast, options);
+
+    const expected = [
+      notion.paragraph([notion.richText('Hello'), notion.richText('[1]')]),
+      notion.paragraph([
+        notion.richText('1. '),
+        notion.richText('Footnote content'),
+      ]),
+    ];
+
+    expect(actual).toStrictEqual(expected);
+  });
 });