feat: note transclusion (#475)

* basic transclude

* feat: note transclusion

docs/features/wikilinks.md

@@ -13,6 +13,4 @@ This is enabled as a part of [[Obsidian compatibility]] and can be configured an
 - `[[Path to file]]`: produces a link to `Path to file.md` (or `Path-to-file.md`) with the text `Path to file`
 - `[[Path to file | Here's the title override]]`: produces a link to `Path to file.md` with the text `Here's the title override`
 - `[[Path to file#Anchor]]`: produces a link to the anchor `Anchor` in the file `Path to file.md`
-
-> [!warning]
-> Currently, Quartz does not support block references or note embed syntax.
+- `[[Path to file#^block-ref]]`: produces a link to the specific block `block-ref` in the file `Path to file.md`

docs/index.md

@@ -30,7 +30,7 @@ This will guide you through initializing your Quartz with content. Once you've d
 
 ## 🔧 Features
 
-- [[Obsidian compatibility]], [[full-text search]], [[graph view]], [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], and [many more](./features) right out of the box
+- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], and [many more](./features) right out of the box
 - Hot-reload for both configuration and content
 - Simple JSX layouts and [[creating components|page components]]
 - [[SPA Routing|Ridiculously fast page loads]] and tiny bundle sizes

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@jackyzha0/quartz",
-  "version": "4.0.10",
+  "version": "4.0.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@jackyzha0/quartz",
-      "version": "4.0.10",
+      "version": "4.0.11",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "^0.6.3",

package.json

@@ -2,7 +2,7 @@
   "name": "@jackyzha0/quartz",
   "description": "🌱 publish your digital garden and notes as a website",
   "private": true,
-  "version": "4.0.10",
+  "version": "4.0.11",
   "type": "module",
   "author": "jackyzha0 <j.zhao2k19@gmail.com>",
   "license": "MIT",

quartz/components/renderPage.tsx

@@ -4,6 +4,8 @@ import HeaderConstructor from "./Header"
 import BodyConstructor from "./Body"
 import { JSResourceToScriptElement, StaticResources } from "../util/resources"
 import { FullSlug, RelativeURL, joinSegments } from "../util/path"
+import { visit } from "unist-util-visit"
+import { Root, Element } from "hast"
 
 interface RenderComponents {
   head: QuartzComponent
@@ -53,6 +55,40 @@ export function renderPage(
   components: RenderComponents,
   pageResources: StaticResources,
 ): string {
+  // process transcludes in componentData
+  visit(componentData.tree as Root, "element", (node, _index, _parent) => {
+    if (node.tagName === "blockquote") {
+      const classNames = (node.properties?.className ?? []) as string[]
+      if (classNames.includes("transclude")) {
+        const inner = node.children[0] as Element
+        const blockSlug = inner.properties?.["data-slug"] as FullSlug
+        const blockRef = node.properties!.dataBlock as string
+
+        // TODO: avoid this expensive find operation and construct an index ahead of time
+        let blockNode = componentData.allFiles.find((f) => f.slug === blockSlug)?.blocks?.[blockRef]
+        if (blockNode) {
+          if (blockNode.tagName === "li") {
+            blockNode = {
+              type: "element",
+              tagName: "ul",
+              children: [blockNode],
+            }
+          }
+
+          node.children = [
+            blockNode,
+            {
+              type: "element",
+              tagName: "a",
+              properties: { href: inner.properties?.href, class: ["internal"] },
+              children: [{ type: "text", value: `Link to original` }],
+            },
+          ]
+        }
+      }
+    }
+  })
+
   const {
     head: Head,
     header,

quartz/plugins/transformers/links.ts

@@ -72,6 +72,7 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
                     simplifySlug(destCanonical as FullSlug),
                   ) as SimpleSlug
                   outgoing.add(simple)
+                  node.properties["data-slug"] = simple
                 }
 
                 // rewrite link internals if prettylinks is on

quartz/plugins/transformers/ofm.ts

@@ -135,6 +135,7 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
     const hast = toHast(ast, { allowDangerousHtml: true })!
     return toHtml(hast, { allowDangerousHtml: true })
   }
+
   const findAndReplace = opts.enableInHtmlEmbed
     ? (tree: Root, regex: RegExp, replace?: Replace | null | undefined) => {
         if (replace) {
@@ -238,8 +239,16 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
                     value: `<iframe src="${url}"></iframe>`,
                   }
                 } else if (ext === "") {
-                  // TODO: note embed
+                  const block = anchor.slice(1)
+                  return {
+                    type: "html",
+                    data: { hProperties: { transclude: true } },
+                    value: `<blockquote class="transclude" data-url="${url}" data-block="${block}"><a href="${
+                      url + anchor
+                    }" class="transclude-inner">Transclude of block ${block}</a></blockquote>`,
                   }
+                }
+
                 // otherwise, fall through to regular link
               }
 
@@ -422,17 +431,23 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
 
       if (opts.parseBlockReferences) {
         plugins.push(() => {
+          const inlineTagTypes = new Set(["p", "li"])
+          const blockTagTypes = new Set(["blockquote"])
           return (tree, file) => {
             file.data.blocks = {}
-            const validTagTypes = new Set(["blockquote", "p", "li"])
-            visit(tree, "element", (node, _index, _parent) => {
-              if (validTagTypes.has(node.tagName)) {
-                const last = node.children.at(-1) as Literal
-                if (last.value && typeof last.value === "string") {
-                  const matches = last.value.match(blockReferenceRegex)
+
+            visit(tree, "element", (node, index, parent) => {
+              if (blockTagTypes.has(node.tagName)) {
+                const nextChild = parent?.children.at(index! + 2) as Element
+                if (nextChild && nextChild.tagName === "p") {
+                  const text = nextChild.children.at(0) as Literal
+                  if (text && text.value && text.type === "text") {
+                    const matches = text.value.match(blockReferenceRegex)
                     if (matches && matches.length >= 1) {
-                    last.value = last.value.slice(0, -matches[0].length)
+                      parent!.children.splice(index! + 2, 1)
                       const block = matches[0].slice(1)
+
+                      if (!Object.keys(file.data.blocks!).includes(block)) {
                         node.properties = {
                           ...node.properties,
                           id: block,
@@ -441,6 +456,25 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
                       }
                     }
                   }
+                }
+              } else if (inlineTagTypes.has(node.tagName)) {
+                const last = node.children.at(-1) as Literal
+                if (last && last.value && typeof last.value === "string") {
+                  const matches = last.value.match(blockReferenceRegex)
+                  if (matches && matches.length >= 1) {
+                    last.value = last.value.slice(0, -matches[0].length)
+                    const block = matches[0].slice(1)
+
+                    if (!Object.keys(file.data.blocks!).includes(block)) {
+                      node.properties = {
+                        ...node.properties,
+                        id: block,
+                      }
+                      file.data.blocks![block] = node
+                    }
+                  }
+                }
+              }
             })
           }
         })

quartz/styles/base.scss

@@ -470,3 +470,9 @@ ol.overflow {
     background: linear-gradient(transparent 0px, var(--light));
   }
 }
+
+.transclude {
+  ul {
+    padding-left: 1rem;
+  }
+}