feat(plugin): citations (#984)

* feat: add rehype-citations * feat: add citations transformer plugin * feat: add rehype-rewrite * feat: add csl option and add no-popover to citation links * revert: add rehype-rewrite 04b2692 'feat: add rehype-rewrite' * feat: use existing package for html manipulation * fix: remove `console.log()`
2024-03-13 08:59:37 +01:00 · 2024-03-13 08:59:37 +01:00 · 92cc23dc45
commit 92cc23dc45
parent 097abc3cda
4 changed files with 327 additions and 0 deletions
--- a/package-lock.json
+++ b/package-lock.json
@ -38,6 +38,7 @@
        "pretty-time": "^1.1.0",
        "reading-time": "^1.5.0",
        "rehype-autolink-headings": "^7.1.0",
+        "rehype-citation": "^2.0.0",
        "rehype-katex": "^7.0.0",
        "rehype-mathjax": "^6.0.0",
        "rehype-pretty-code": "^0.13.0",
@ -98,6 +99,82 @@
        "is-potential-custom-element-name": "^1.0.1"
      }
    },
+    "node_modules/@citation-js/core": {
+      "version": "0.7.9",
+      "resolved": "https://registry.npmjs.org/@citation-js/core/-/core-0.7.9.tgz",
+      "integrity": "sha512-fSbkB32JayDChZnAYC/kB+sWHRvxxL7ibVetyBOyzOc+5aCnjb6UVsbcfhnkOIEyAMoRRvWDyFmakEoTtA5ttQ==",
+      "dependencies": {
+        "@citation-js/date": "^0.5.0",
+        "@citation-js/name": "^0.4.2",
+        "fetch-ponyfill": "^7.1.0",
+        "sync-fetch": "^0.4.1"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
+    "node_modules/@citation-js/date": {
+      "version": "0.5.1",
+      "resolved": "https://registry.npmjs.org/@citation-js/date/-/date-0.5.1.tgz",
+      "integrity": "sha512-1iDKAZ4ie48PVhovsOXQ+C6o55dWJloXqtznnnKy6CltJBQLIuLLuUqa8zlIvma0ZigjVjgDUhnVaNU1MErtZw==",
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/@citation-js/name": {
+      "version": "0.4.2",
+      "resolved": "https://registry.npmjs.org/@citation-js/name/-/name-0.4.2.tgz",
+      "integrity": "sha512-brSPsjs2fOVzSnARLKu0qncn6suWjHVQtrqSUrnqyaRH95r/Ad4wPF5EsoWr+Dx8HzkCGb/ogmoAzfCsqlTwTQ==",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/@citation-js/plugin-bibjson": {
+      "version": "0.7.9",
+      "resolved": "https://registry.npmjs.org/@citation-js/plugin-bibjson/-/plugin-bibjson-0.7.9.tgz",
+      "integrity": "sha512-YNCWIrkhqZ3cZKewHkLBixABo2PvOWnU+8dBx6KfN47ysdECR76xENe86YYpJ0ska2D5ZnTP0jKZIrUHQoxYfQ==",
+      "dependencies": {
+        "@citation-js/date": "^0.5.0",
+        "@citation-js/name": "^0.4.2"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "peerDependencies": {
+        "@citation-js/core": "^0.7.0"
+      }
+    },
+    "node_modules/@citation-js/plugin-bibtex": {
+      "version": "0.7.9",
+      "resolved": "https://registry.npmjs.org/@citation-js/plugin-bibtex/-/plugin-bibtex-0.7.9.tgz",
+      "integrity": "sha512-gIJpCd6vmmTOcRfDrSOjtoNhw2Mi94UwFxmgJ7GwkXyTYcNheW5VlMMo1tlqjakJGARQ0eOsKcI57gSPqJSS2g==",
+      "dependencies": {
+        "@citation-js/date": "^0.5.0",
+        "@citation-js/name": "^0.4.2",
+        "moo": "^0.5.1"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "peerDependencies": {
+        "@citation-js/core": "^0.7.0"
+      }
+    },
+    "node_modules/@citation-js/plugin-csl": {
+      "version": "0.7.9",
+      "resolved": "https://registry.npmjs.org/@citation-js/plugin-csl/-/plugin-csl-0.7.9.tgz",
+      "integrity": "sha512-mbD7CnUiPOuVnjeJwo+d0RGUcY0PE8n01gHyjq0qpTeS42EGmQ9+LzqfsTUVWWBndTwc6zLRuIF1qFAUHKE4oA==",
+      "dependencies": {
+        "@citation-js/date": "^0.5.0",
+        "citeproc": "^2.4.6"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "peerDependencies": {
+        "@citation-js/core": "^0.7.0"
+      }
+    },
    "node_modules/@clack/core": {
      "version": "0.3.3",
      "resolved": "https://registry.npmjs.org/@clack/core/-/core-0.3.3.tgz",
@ -1239,6 +1316,25 @@
      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
    },
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ]
+    },
    "node_modules/bidi-js": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
@ -1274,6 +1370,29 @@
        "node": ">=8"
      }
    },
+    "node_modules/buffer": {
+      "version": "5.7.1",
+      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
+      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "dependencies": {
+        "base64-js": "^1.3.1",
+        "ieee754": "^1.1.13"
+      }
+    },
    "node_modules/buffer-from": {
      "version": "1.1.2",
      "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz",
@ -1366,6 +1485,11 @@
        "fsevents": "~2.3.2"
      }
    },
+    "node_modules/citeproc": {
+      "version": "2.4.63",
+      "resolved": "https://registry.npmjs.org/citeproc/-/citeproc-2.4.63.tgz",
+      "integrity": "sha512-68F95Bp4UbgZU/DBUGQn0qV3HDZLCdI9+Bb2ByrTaNJDL5VEm9LqaiNaxljsvoaExSLEXe1/r6n2Z06SCzW3/Q=="
+    },
    "node_modules/cli-spinner": {
      "version": "0.2.10",
      "resolved": "https://registry.npmjs.org/cli-spinner/-/cli-spinner-0.2.10.tgz",
@ -1497,6 +1621,14 @@
        "node": ">= 0.6"
      }
    },
+    "node_modules/cross-fetch": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/cross-fetch/-/cross-fetch-4.0.0.tgz",
+      "integrity": "sha512-e4a5N8lVvuLgAWgnCrLr2PP0YyDOTHa9H/Rj54dirp61qXnNq46m82bRhNqIA5VccJtWBvPTFRV3TtvHUKPB1g==",
+      "dependencies": {
+        "node-fetch": "^2.6.12"
+      }
+    },
    "node_modules/cross-spawn": {
      "version": "7.0.3",
      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz",
@ -2172,6 +2304,52 @@
        "url": "https://github.com/sponsors/wooorm"
      }
    },
+    "node_modules/fetch-ponyfill": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/fetch-ponyfill/-/fetch-ponyfill-7.1.0.tgz",
+      "integrity": "sha512-FhbbL55dj/qdVO3YNK7ZEkshvj3eQ7EuIGV2I6ic/2YiocvyWv+7jg2s4AyS0wdRU75s3tA8ZxI/xPigb0v5Aw==",
+      "dependencies": {
+        "node-fetch": "~2.6.1"
+      }
+    },
+    "node_modules/fetch-ponyfill/node_modules/node-fetch": {
+      "version": "2.6.13",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.13.tgz",
+      "integrity": "sha512-StxNAxh15zr77QvvkmveSQ8uCQ4+v5FkvNTj0OESmiHu+VRi/gXArXtkWMElOsOUNLtUEvI4yS+rdtOHZTwlQA==",
+      "dependencies": {
+        "whatwg-url": "^5.0.0"
+      },
+      "engines": {
+        "node": "4.x || >=6.0.0"
+      },
+      "peerDependencies": {
+        "encoding": "^0.1.0"
+      },
+      "peerDependenciesMeta": {
+        "encoding": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fetch-ponyfill/node_modules/tr46": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
+      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="
+    },
+    "node_modules/fetch-ponyfill/node_modules/webidl-conversions": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
+      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="
+    },
+    "node_modules/fetch-ponyfill/node_modules/whatwg-url": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
+      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+      "dependencies": {
+        "tr46": "~0.0.3",
+        "webidl-conversions": "^3.0.0"
+      }
+    },
    "node_modules/fill-range": {
      "version": "7.0.1",
      "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz",
@ -2748,6 +2926,25 @@
        "node": ">=0.10.0"
      }
    },
+    "node_modules/ieee754": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
+      "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ]
+    },
    "node_modules/ignore": {
      "version": "5.2.4",
      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz",
@ -4316,6 +4513,11 @@
      "resolved": "https://registry.npmjs.org/mj-context-menu/-/mj-context-menu-0.6.1.tgz",
      "integrity": "sha512-7NO5s6n10TIV96d4g2uDpG7ZDpIhMh0QNfGdJw/W47JswFcosz457wqz/b5sAKvl12sxINGFCn80NZHKwxQEXA=="
    },
+    "node_modules/moo": {
+      "version": "0.5.2",
+      "resolved": "https://registry.npmjs.org/moo/-/moo-0.5.2.tgz",
+      "integrity": "sha512-iSAJLHYKnX41mKcJKjqvnAN9sf0LMDTXDEvFv+ffuRR9a1MIuXLjMNL6EsnDHSkKLTWNqQQ5uo61P4EbU4NU+Q=="
+    },
    "node_modules/ms": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
@ -4333,6 +4535,44 @@
        "url": "https://opencollective.com/unified"
      }
    },
+    "node_modules/node-fetch": {
+      "version": "2.7.0",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz",
+      "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==",
+      "dependencies": {
+        "whatwg-url": "^5.0.0"
+      },
+      "engines": {
+        "node": "4.x || >=6.0.0"
+      },
+      "peerDependencies": {
+        "encoding": "^0.1.0"
+      },
+      "peerDependenciesMeta": {
+        "encoding": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/node-fetch/node_modules/tr46": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
+      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="
+    },
+    "node_modules/node-fetch/node_modules/webidl-conversions": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
+      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="
+    },
+    "node_modules/node-fetch/node_modules/whatwg-url": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
+      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+      "dependencies": {
+        "tr46": "~0.0.3",
+        "webidl-conversions": "^3.0.0"
+      }
+    },
    "node_modules/normalize-path": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
@ -4598,6 +4838,27 @@
        "url": "https://opencollective.com/unified"
      }
    },
+    "node_modules/rehype-citation": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-citation/-/rehype-citation-2.0.0.tgz",
+      "integrity": "sha512-rGawTBI8SJA1Y4IRyROvpYF6oXBVNFXlJYHIJ2jJH3HgeuCbAC9AO8wE/NMPLDOPQ8+Q8QkZm93fKsnUNbvwZA==",
+      "dependencies": {
+        "@citation-js/core": "^0.7.1",
+        "@citation-js/date": "^0.5.1",
+        "@citation-js/name": "^0.4.2",
+        "@citation-js/plugin-bibjson": "^0.7.2",
+        "@citation-js/plugin-bibtex": "^0.7.2",
+        "@citation-js/plugin-csl": "^0.7.2",
+        "citeproc": "^2.4.63",
+        "cross-fetch": "^4.0.0",
+        "hast-util-from-dom": "^5.0.0",
+        "hast-util-from-parse5": "^8.0.1",
+        "js-yaml": "^4.1.0",
+        "parse5": "^7.1.2",
+        "unified": "^11.0.0",
+        "unist-util-visit": "^5.0.0"
+      }
+    },
    "node_modules/rehype-katex": {
      "version": "7.0.0",
      "resolved": "https://registry.npmjs.org/rehype-katex/-/rehype-katex-7.0.0.tgz",
@ -5537,6 +5798,18 @@
      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw=="
    },
+    "node_modules/sync-fetch": {
+      "version": "0.4.5",
+      "resolved": "https://registry.npmjs.org/sync-fetch/-/sync-fetch-0.4.5.tgz",
+      "integrity": "sha512-esiWJ7ixSKGpd9DJPBTC4ckChqdOjIwJfYhVHkcQ2Gnm41323p1TRmEI+esTQ9ppD+b5opps2OTEGTCGX5kF+g==",
+      "dependencies": {
+        "buffer": "^5.7.1",
+        "node-fetch": "^2.6.1"
+      },
+      "engines": {
+        "node": ">=14"
+      }
+    },
    "node_modules/to-regex-range": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
--- a/package.json
+++ b/package.json
@ -63,6 +63,7 @@
    "pretty-time": "^1.1.0",
    "reading-time": "^1.5.0",
    "rehype-autolink-headings": "^7.1.0",
+    "rehype-citation": "^2.0.0",
    "rehype-katex": "^7.0.0",
    "rehype-mathjax": "^6.0.0",
    "rehype-pretty-code": "^0.13.0",
--- a/quartz/plugins/transformers/citations.ts
+++ b/quartz/plugins/transformers/citations.ts
@ -0,0 +1,52 @@
+import rehypeCitation from "rehype-citation"
+import { PluggableList } from "unified"
+import { visit } from "unist-util-visit"
+import { QuartzTransformerPlugin } from "../types"
+
+export interface Options {
+  bibliographyFile: string
+  suppressBibliography: boolean
+  linkCitations: boolean
+  csl: string
+}
+
+const defaultOptions: Options = {
+  bibliographyFile: "./bibliography.bib",
+  suppressBibliography: false,
+  linkCitations: false,
+  csl: "apa",
+}
+
+export const Citations: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {
+  const opts = { ...defaultOptions, ...userOpts }
+  return {
+    name: "Citations",
+    htmlPlugins() {
+      const plugins: PluggableList = []
+
+      // Add rehype-citation to the list of plugins
+      plugins.push([
+        rehypeCitation,
+        {
+          bibliography: opts.bibliographyFile,
+          suppressBibliography: opts.suppressBibliography,
+          linkCitations: opts.linkCitations,
+        },
+      ])
+
+      // Transform the HTML of the citattions; add data-no-popover property to the citation links
+      // using https://github.com/syntax-tree/unist-util-visit as they're just anochor links
+      plugins.push(() => {
+        return (tree, _file) => {
+          visit(tree, "element", (node, index, parent) => {
+            if (node.tagName === "a" && node.properties?.href?.startsWith("#bib")) {
+              node.properties["data-no-popover"] = true
+            }
+          })
+        }
+      })
+
+      return plugins
+    },
+  }
+}
--- a/quartz/plugins/transformers/index.ts
+++ b/quartz/plugins/transformers/index.ts
@ -1,5 +1,6 @@
 export { FrontMatter } from "./frontmatter"
 export { GitHubFlavoredMarkdown } from "./gfm"
+export { Citations } from "./citations"
 export { CreatedModifiedDate } from "./lastmod"
 export { Latex } from "./latex"
 export { Description } from "./description"