feat(citations): prettify links

Signed-off-by: Aaron Pham <contact@aarnphm.xyz>

docs/biblography.bib

@@ -0,0 +1,17 @@
+@article{templeton2024scaling,
+  title={Scaling Monosemanticity: Extracting Interpretable Features from Claude 3 Sonnet},
+  author={Templeton, Adly and Conerly, Tom and Marcus, Jonathan and Lindsey, Jack and Bricken, Trenton and Chen, Brian and Pearce, Adam and Citro, Craig and Ameisen, Emmanuel and Jones, Andy and Cunningham, Hoagy and Turner, Nicholas L and McDougall, Callum and MacDiarmid, Monte and Freeman, C. Daniel and Sumers, Theodore R. and Rees, Edward and Batson, Joshua and Jermyn, Adam and Carter, Shan and Olah, Chris and Henighan, Tom},
+  year={2024},
+  journal={Transformer Circuits Thread},
+  url={https://transformer-circuits.pub/2024/scaling-monosemanticity/index.html}
+}
+
+@incollection{dreyfus2008why,
+  title={Why Heideggerian AI Failed and How Fixing It Would Require Making It More Heideggerian},
+  author={Dreyfus, Hubert L.},
+  booktitle={The Mechanical Mind in History},
+  pages={331--362},
+  year={2008},
+  publisher={MIT Press},
+  address={Cambridge, MA}
+}

docs/features/Citations.md

@@ -0,0 +1,27 @@
+---
+title: Citation
+tags:
+  - feature/transformer
+---
+
+Quartz uses [rehype-citation](https://github.com/timlrx/rehype-citation) to support parsing biblography file.
+
+An example of a citation as below:
+
+> [@templeton2024scaling] showed that features are generally interpretable and monosemantic, and many are safety-relevant.
+
+> [!tip]- Syntax
+>
+> See [source](https://github.com/jackyzha0/quartz/blob/v4/docs/features/Citations.md) and [biblography example](https://github.com/jackyzha0/quartz/blob/v4/docs/biblography.bib)
+
+> [!note] Behaviour of references
+>
+> By default, the references will be included at the end of the file. To control where the references to be included,uses `[^ref]`
+
+## Customization
+
+Citation parsing is a functionality of the [[plugins/Citations|Citation]] plugin. See the plugin page for customization options.
+
+## References
+
+[^ref]

docs/plugins/Citations.md

@@ -0,0 +1,24 @@
+---
+title: "Citations"
+tags:
+  - plugin/transformer
+---
+
+This plugin adds Citation support to Quartz.
+
+> [!note]
+> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
+
+This plugin accepts the following configuration options:
+
+- `bibliographyFile`: the path to the bibliography file. Defaults to `./bibliography.bib`. This is relative to git source of your vault.
+- `suppressBibliography`: whether to suppress the bibliography at the end of the document. Defaults to `false`.
+- `linkCitations`: whether to link citations to the bibliography. Defaults to `false`.
+- `csl`: the citation style to use. Defaults to `apa`.
+- `prettyLink`: whether to use pretty links for citations. Defaults to `true`.
+
+## API
+
+- Category: Transformer
+- Function name: `Plugin.Citations()`.
+- Source: [`quartz/plugins/transformers/citations.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/citations.ts).

quartz.config.ts

@@ -72,6 +72,7 @@ const config: QuartzConfig = {
       Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
       Plugin.Description(),
       Plugin.Latex({ renderEngine: "katex" }),
+      Plugin.Citations({ bibliographyFile: "./docs/biblography.bib" }),
     ],
     filters: [Plugin.RemoveDrafts()],
     emitters: [

quartz/plugins/transformers/citations.ts

@@ -2,12 +2,14 @@ import rehypeCitation from "rehype-citation"
 import { PluggableList } from "unified"
 import { visit } from "unist-util-visit"
 import { QuartzTransformerPlugin } from "../types"
+import { Element, Text, Root as HtmlRoot } from "hast"
 
 export interface Options {
   bibliographyFile: string
   suppressBibliography: boolean
   linkCitations: boolean
   csl: string
+  prettyLink?: boolean
 }
 
 const defaultOptions: Options = {
@@ -15,6 +17,73 @@ const defaultOptions: Options = {
   suppressBibliography: false,
   linkCitations: false,
   csl: "apa",
+  prettyLink: true,
+}
+
+const URL_PATTERN = /https?:\/\/[^\s<>)"]+/g
+
+function processTextNode(node: Text): (Element | Text)[] {
+  const text = node.value
+  const matches = Array.from(text.matchAll(URL_PATTERN))
+
+  if (matches.length === 0) {
+    return [node]
+  }
+
+  const result: (Element | Text)[] = []
+  let lastIndex = 0
+
+  matches.forEach((match) => {
+    const url = match[0]
+    const startIndex = match.index!
+
+    // Add text before URL if exists
+    if (startIndex > lastIndex) {
+      result.push({
+        type: "text",
+        value: text.slice(lastIndex, startIndex),
+      })
+    }
+
+    // Add anchor element for URL
+    result.push({
+      type: "element",
+      tagName: "a",
+      properties: {
+        href: url,
+        target: "_blank",
+        rel: "noopener noreferrer",
+      },
+      children: [{ type: "text", value: url }],
+    })
+    lastIndex = startIndex + url.length
+  })
+
+  // Add remaining text after last URL if exists
+  if (lastIndex < text.length) {
+    result.push({
+      type: "text",
+      value: text.slice(lastIndex),
+    })
+  }
+
+  return result
+}
+
+// Function to process a list of nodes
+function processNodes(nodes: (Element | Text)[]): (Element | Text)[] {
+  return nodes.flatMap((node) => {
+    if (node.type === "text") {
+      return processTextNode(node)
+    }
+    if (node.type === "element") {
+      return {
+        ...node,
+        children: processNodes(node.children as (Element | Text)[]),
+      }
+    }
+    return [node]
+  })
 }
 
 export const Citations: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
@@ -48,6 +117,23 @@ export const Citations: QuartzTransformerPlugin<Partial<Options>> = (userOpts) =
         }
       })
 
+      // Format external links correctly
+      if (opts.prettyLink) {
+        plugins.push(() => {
+          return (tree: HtmlRoot, _file) => {
+            visit(tree, "element", (node) => {
+              if ((node.properties?.className as string[])?.includes("references")) {
+                visit(node, "element", (entry) => {
+                  if ((entry.properties?.className as string[])?.includes("csl-entry")) {
+                    entry.children = processNodes(entry.children as (Element | Text)[])
+                  }
+                })
+              }
+            })
+          }
+        })
+      }
+
       return plugins
     },
   }