An article header
\nSome content
\n![](\"https://cdn.jsdelivr.net/gh/jackyzha0/jackyzha0/sponsorkit/sponsors.svg\")
\n \n\n \n \n \n
Some content
\nMy favourite number is {opts.favouriteNumber}
\n }\n\n return YourComponent\n}) satisfies QuartzComponentConstructor\n```\n\n### Props\n\nThe Quartz component itself (lines 11-17 highlighted above) looks like a React component. It takes in properties (sometimes called [props](https://react.dev/learn/passing-props-to-a-component)) and returns JSX.\n\nAll Quartz components accept the same set of props:\n\n```tsx title=\"quartz/components/types.ts\"\n// simplified for sake of demonstration\nexport type QuartzComponentProps = {\n fileData: QuartzPluginData\n cfg: GlobalConfiguration\n tree: NodeExample Component
\n }\n\n YourComponent.css = `\n p.red-text {\n color: red;\n }\n `\n\n return YourComponent\n}) satisfies QuartzComponentConstructor\n```\n\nImported styles, however, can be from SCSS files:\n\n```tsx {1-2,9} title=\"quartz/components/YourComponent.tsx\"\n// assuming your stylesheet is in quartz/components/styles/YourComponent.scss\nimport styles from \"./styles/YourComponent.scss\"\n\nexport default (() => {\n function YourComponent() {\n returnExample Component
\n }\n\n YourComponent.css = styles\n return YourComponent\n}) satisfies QuartzComponentConstructor\n```\n\n> [!warning]\n> Quartz does not use CSS modules so any styles you declare here apply _globally_. If you only want it to apply to your component, make sure you use specific class names and selectors.\n\n### Scripts and Interactivity\n\nWhat about interactivity? Suppose you want to add an-click handler for example. Like the `.css` property on the component, you can also declare `.beforeDOMLoaded` and `.afterDOMLoaded` properties that are strings that contain the script.\n\n```tsx title=\"quartz/components/YourComponent.tsx\"\nexport default (() => {\n function YourComponent() {\n return \n }\n\n YourComponent.beforeDOMLoaded = `\n console.log(\"hello from before the page loads!\")\n `\n\n YourComponent.afterDOMLoaded = `\n document.getElementById('btn').onclick = () => {\n alert('button clicked!')\n }\n `\n return YourComponent\n}) satisfies QuartzComponentConstructor\n```\n\n> [!hint]\n> For those coming from React, Quartz components are different from React components in that it only uses JSX for templating and layout. Hooks like `useEffect`, `useState`, etc. are not rendered and other properties that accept functions like `onClick` handlers will not work. Instead, do it using a regular JS script that modifies the DOM element directly.\n\nAs the names suggest, the `.beforeDOMLoaded` scripts are executed _before_ the page is done loading so it doesn't have access to any elements on the page. This is mostly used to prefetch any critical data.\n\nThe `.afterDOMLoaded` script executes once the page has been completely loaded. This is a good place to setup anything that should last for the duration of a site visit (e.g. getting something saved from local storage).\n\nIf you need to create an `afterDOMLoaded` script that depends on _page specific_ elements that may change when navigating to a new page, you can listen for the `\"nav\"` event that gets fired whenever a page loads (which may happen on navigation if [[SPA Routing]] is enabled).\n\n```ts\ndocument.addEventListener(\"nav\", () => {\n // do page specific logic here\n // e.g. attach event listeners\n const toggleSwitch = document.querySelector(\"#switch\") as HTMLInputElement\n toggleSwitch.addEventListener(\"change\", switchTheme)\n window.addCleanup(() => toggleSwitch.removeEventListener(\"change\", switchTheme))\n})\n```\n\nYou can also add the equivalent of a `beforeunload` event for [[SPA Routing]] via the `prenav` event.\n\n```ts\ndocument.addEventListener(\"prenav\", () => {\n // executed after an SPA navigation is triggered but\n // before the page is replaced\n // one usage pattern is to store things in sessionStorage\n // in the prenav and then conditionally load then in the consequent\n // nav\n})\n```\n\nIt is best practice to track any event handlers via `window.addCleanup` to prevent memory leaks.\nThis will get called on page navigation.\n\n#### Importing Code\n\nOf course, it isn't always practical (nor desired!) to write your code as a string literal in the component.\n\nQuartz supports importing component code through `.inline.ts` files.\n\n```tsx title=\"quartz/components/YourComponent.tsx\"\n// @ts-ignore: typescript doesn't know about our inline bundling system\n// so we need to silence the error\nimport script from \"./scripts/graph.inline\"\n\nexport default (() => {\n function YourComponent() {\n return \n }\n\n YourComponent.afterDOMLoaded = script\n return YourComponent\n}) satisfies QuartzComponentConstructor\n```\n\n```ts title=\"quartz/components/scripts/graph.inline.ts\"\n// any imports here are bundled for the browser\nimport * as d3 from \"d3\"\n\ndocument.getElementById(\"btn\").onclick = () => {\n alert(\"button clicked!\")\n}\n```\n\nAdditionally, like what is shown in the example above, you can import packages in `.inline.ts` files. This will be bundled by Quartz and included in the actual script.\n\n### Using a Component\n\nAfter creating your custom component, re-export it in `quartz/components/index.ts`:\n\n```ts title=\"quartz/components/index.ts\" {4,10}\nimport ArticleTitle from \"./ArticleTitle\"\nimport Content from \"./pages/Content\"\nimport Darkmode from \"./Darkmode\"\nimport YourComponent from \"./YourComponent\"\n\nexport { ArticleTitle, Content, Darkmode, YourComponent }\n```\n\nThen, you can use it like any other component in `quartz.layout.ts` via `Component.YourComponent()`. See the [[configuration#Layout|layout]] section for more details.\n\nAs Quartz components are just functions that return React components, you can compositionally use them in other Quartz components.\n\n```tsx title=\"quartz/components/AnotherComponent.tsx\"\nimport YourComponentConstructor from \"./YourComponent\"\n\nexport default (() => {\n const YourComponent = YourComponentConstructor()\n\n function AnotherComponent(props: QuartzComponentProps) {\n return (\nIt's nested!
\nCool Header!
\n}\n```\n\n> [!example]- Local fonts\n>\n> For cases where you use a local fonts under `static` folder, make sure to set the correct `@font-face` in `custom.scss`\n>\n> ```scss title=\"custom.scss\"\n> @font-face {\n> font-family: \"Newsreader\";\n> font-style: normal;\n> font-weight: normal;\n> font-display: swap;\n> src: url(\"/static/Newsreader.woff2\") format(\"woff2\");\n> }\n> ```\n>\n> Then in `quartz/util/og.tsx`, you can load the Satori fonts like so:\n>\n> ```tsx title=\"quartz/util/og.tsx\"\n> import { joinSegments, QUARTZ } from \"../path\"\n> import fs from \"fs\"\n> import path from \"path\"\n>\n> const newsreaderFontPath = joinSegments(QUARTZ, \"static\", \"Newsreader.woff2\")\n> export async function getSatoriFonts(headerFont: FontSpecification, bodyFont: FontSpecification) {\n> // ... rest of implementation remains same\n> const fonts: SatoriOptions[\"fonts\"] = [\n> ...headerFontData.map((data, idx) => ({\n> name: headerFontName,\n> data,\n> weight: headerWeights[idx],\n> style: \"normal\" as const,\n> })),\n> ...bodyFontData.map((data, idx) => ({\n> name: bodyFontName,\n> data,\n> weight: bodyWeights[idx],\n> style: \"normal\" as const,\n> })),\n> {\n> name: \"Newsreader\",\n> data: await fs.promises.readFile(path.resolve(newsreaderFontPath)),\n> weight: 400,\n> style: \"normal\" as const,\n> },\n> ]\n>\n> return fonts\n> }\n> ```\n>\n> This font then can be used with your custom structure.\n\n## Examples\n\nHere are some example image components you can use as a starting point:\n\n### Basic Example\n\nThis example will generate images that look as follows:\n\n| Light | Dark |\n| ------------------------------------------ | ----------------------------------------- |\n| ![[custom-social-image-preview-light.png]] | ![[custom-social-image-preview-dark.png]] |\n\n```tsx\nimport { SatoriOptions } from \"satori/wasm\"\nimport { GlobalConfiguration } from \"../cfg\"\nimport { SocialImageOptions, UserOpts } from \"./imageHelper\"\nimport { QuartzPluginData } from \"../plugins/vfile\"\n\nexport const customImage: SocialImageOptions[\"imageStructure\"] = (\n cfg: GlobalConfiguration,\n userOpts: UserOpts,\n title: string,\n description: string,\n fonts: SatoriOptions[\"fonts\"],\n fileData: QuartzPluginData,\n) => {\n // How many characters are allowed before switching to smaller font\n const fontBreakPoint = 22\n const useSmallerFont = title.length > fontBreakPoint\n\n const { colorScheme } = userOpts\n return (\n\n {segments}\n
\n )\n } else {\n return null\n }\n }\n\n ContentMetadata.css = style\n\n return ContentMetadata\n}) satisfies QuartzComponentConstructor\n" }, { "path": "quartz/components/Darkmode.tsx", "content": "// @ts-ignore\nimport darkmodeScript from \"./scripts/darkmode.inline\"\nimport styles from \"./styles/darkmode.scss\"\nimport { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from \"./types\"\nimport { i18n } from \"../i18n\"\nimport { classNames } from \"../util/lang\"\n\nconst Darkmode: QuartzComponent = ({ displayClass, cfg }: QuartzComponentProps) => {\n return (\n \n )\n}\n\nDarkmode.beforeDOMLoaded = darkmodeScript\nDarkmode.css = styles\n\nexport default (() => Darkmode) satisfies QuartzComponentConstructor\n" }, { "path": "quartz/components/Date.tsx", "content": "import { GlobalConfiguration } from \"../cfg\"\nimport { ValidLocale } from \"../i18n\"\nimport { QuartzPluginData } from \"../plugins/vfile\"\n\ninterface Props {\n date: Date\n locale?: ValidLocale\n}\n\nexport type ValidDateType = keyof Required\n \n {i18n(cfg.locale).components.recentNotes.seeRemainingMore({ remaining })}\n \n
\n )}\n{i18n(cfg.locale).pages.error.notFound}
\n {i18n(cfg.locale).pages.error.home}\n\n {i18n(cfg.locale).pages.folderContent.itemsUnderFolder({\n count: allPagesInFolder.length,\n })}\n
\n )}\n{content}
\n{i18n(cfg.locale).pages.tagContent.totalTags({ count: tags.length })}
\n{content}
}\n\n {i18n(cfg.locale).pages.tagContent.itemsUnderTag({ count: pages.length })}\n {pages.length > options.numPages && (\n <>\n {\" \"}\n \n {i18n(cfg.locale).pages.tagContent.showingFirst({\n count: options.numPages,\n })}\n \n \n )}\n
\n{i18n(cfg.locale).pages.tagContent.itemsUnderTag({ count: pages.length })}
\n#${tag}
#${tag}
${content}
\n `\n itemTile.addEventListener(\"click\", (event) => {\n if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return\n hideSearch()\n })\n\n const handler = (event: MouseEvent) => {\n if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return\n hideSearch()\n }\n\n async function onMouseEnter(ev: MouseEvent) {\n if (!ev.target) return\n const target = ev.target as HTMLInputElement\n await displayPreview(target)\n }\n\n itemTile.addEventListener(\"mouseenter\", onMouseEnter)\n window.addCleanup(() => itemTile.removeEventListener(\"mouseenter\", onMouseEnter))\n itemTile.addEventListener(\"click\", handler)\n window.addCleanup(() => itemTile.removeEventListener(\"click\", handler))\n\n return itemTile\n }\n\n async function displayResults(finalResults: Item[]) {\n removeAllChildren(results)\n if (finalResults.length === 0) {\n results.innerHTML = `\nTry another search term?
\n `\n } else {\n results.append(...finalResults.map(resultToHTML))\n }\n\n if (finalResults.length === 0 && preview) {\n // no results, clear previous preview\n removeAllChildren(preview)\n } else {\n // focus on first result, then also dispatch preview immediately\n const firstChild = results.firstElementChild as HTMLElement\n firstChild.classList.add(\"focus\")\n currentHover = firstChild as HTMLInputElement\n await displayPreview(firstChild)\n }\n }\n\n async function fetchContent(slug: FullSlug): PromiseTransclude of ${url}${block}`,\n }\n }\n\n // otherwise, fall through to regular link\n }\n\n // treat as broken link if slug not in ctx.allSlugs\n if (opts.disableBrokenWikilinks) {\n const slug = slugifyFilePath(fp as FilePath)\n const exists = ctx.allSlugs && ctx.allSlugs.includes(slug)\n if (!exists) {\n return {\n type: \"html\",\n value: `${alias ?? fp}`,\n }\n }\n }\n\n // internal link\n const url = fp + anchor\n\n return {\n type: \"link\",\n url,\n children: [\n {\n type: \"text\",\n value: alias ?? fp,\n },\n ],\n }\n },\n ])\n }\n\n if (opts.highlight) {\n replacements.push([\n highlightRegex,\n (_value: string, ...capture: string[]) => {\n const [inner] = capture\n return {\n type: \"html\",\n value: `${inner}`,\n }\n },\n ])\n }\n\n if (opts.parseArrows) {\n replacements.push([\n arrowRegex,\n (value: string, ..._capture: string[]) => {\n const maybeArrow = arrowMapping[value]\n if (maybeArrow === undefined) return SKIP\n return {\n type: \"html\",\n value: `${maybeArrow}`,\n }\n },\n ])\n }\n\n if (opts.parseTags) {\n replacements.push([\n tagRegex,\n (_value: string, tag: string) => {\n // Check if the tag only includes numbers and slashes\n if (/^[\\/\\d]+$/.test(tag)) {\n return false\n }\n\n tag = slugTag(tag)\n if (file.data.frontmatter) {\n const noteTags = file.data.frontmatter.tags ?? []\n file.data.frontmatter.tags = [...new Set([...noteTags, tag])]\n }\n\n return {\n type: \"link\",\n url: base + `/tags/${tag}`,\n data: {\n hProperties: {\n className: [\"tag-link\"],\n },\n },\n children: [\n {\n type: \"text\",\n value: tag,\n },\n ],\n }\n },\n ])\n }\n\n if (opts.enableInHtmlEmbed) {\n visit(tree, \"html\", (node: Html) => {\n for (const [regex, replace] of replacements) {\n if (typeof replace === \"string\") {\n node.value = node.value.replace(regex, replace)\n } else {\n node.value = node.value.replace(regex, (substring: string, ...args) => {\n const replaceValue = replace(substring, ...args)\n if (typeof replaceValue === \"string\") {\n return replaceValue\n } else if (Array.isArray(replaceValue)) {\n return replaceValue.map(mdastToHtml).join(\"\")\n } else if (typeof replaceValue === \"object\" && replaceValue !== null) {\n return mdastToHtml(replaceValue)\n } else {\n return substring\n }\n })\n }\n }\n })\n }\n mdastFindReplace(tree, replacements)\n }\n })\n\n if (opts.enableVideoEmbed) {\n plugins.push(() => {\n return (tree: Root, _file) => {\n visit(tree, \"image\", (node, index, parent) => {\n if (parent && index != undefined && videoExtensionRegex.test(node.url)) {\n const newNode: Html = {\n type: \"html\",\n value: ``,\n }\n\n parent.children.splice(index, 1, newNode)\n return SKIP\n }\n })\n }\n })\n }\n\n if (opts.callouts) {\n plugins.push(() => {\n return (tree: Root, _file) => {\n visit(tree, \"blockquote\", (node) => {\n if (node.children.length === 0) {\n return\n }\n\n // find first line and callout content\n const [firstChild, ...calloutContent] = node.children\n if (firstChild.type !== \"paragraph\" || firstChild.children[0]?.type !== \"text\") {\n return\n }\n\n const text = firstChild.children[0].value\n const restOfTitle = firstChild.children.slice(1)\n const [firstLine, ...remainingLines] = text.split(\"\\n\")\n const remainingText = remainingLines.join(\"\\n\")\n\n const match = firstLine.match(calloutRegex)\n if (match && match.input) {\n const [calloutDirective, typeString, calloutMetaData, collapseChar] = match\n const calloutType = canonicalizeCallout(typeString.toLowerCase())\n const collapse = collapseChar === \"+\" || collapseChar === \"-\"\n const defaultState = collapseChar === \"-\" ? \"collapsed\" : \"expanded\"\n const titleContent = match.input.slice(calloutDirective.length).trim()\n const useDefaultTitle = titleContent === \"\" && restOfTitle.length === 0\n const titleNode: Paragraph = {\n type: \"paragraph\",\n children: [\n {\n type: \"text\",\n value: useDefaultTitle\n ? capitalize(typeString).replace(/-/g, \" \")\n : titleContent + \" \",\n },\n ...restOfTitle,\n ],\n }\n const title = mdastToHtml(titleNode)\n\n const toggleIcon = ``\n\n const titleHtml: Html = {\n type: \"html\",\n value: `
${content.trim()}`,\n }),\n ])\n }\n\n mdastFindReplace(tree, replacements)\n }\n })\n\n return plugins\n },\n }\n}\n" }, { "path": "quartz/plugins/transformers/syntax.ts", "content": "import { QuartzTransformerPlugin } from \"../types\"\nimport rehypePrettyCode, { Options as CodeOptions, Theme as CodeTheme } from \"rehype-pretty-code\"\n\ninterface Theme extends Record