| | |
|---|
| | | - `BuildCtx` is defined in `quartz/ctx.ts`. It consists of |
|---|
| | | - `argv`: The command line arguments passed to the Quartz [[build]] command |
|---|
| | | - `cfg`: The full Quartz [[configuration]] |
|---|
| | | - `allSlugs`: a list of all the valid content slugs (see [[paths]] for more information on what a `ServerSlug` is) |
|---|
| | | - `allSlugs`: a list of all the valid content slugs (see [[paths]] for more information on what a slug is) |
|---|
| | | - `StaticResources` is defined in `quartz/resources.tsx`. It consists of |
|---|
| | | - `css`: a list of URLs for stylesheets that should be loaded |
|---|
| | | - `css`: a list of CSS style definitions that should be loaded. A CSS style is described with the `CSSResource` type which is also defined in `quartz/resources.tsx`. It accepts either a source URL or the inline content of the stylesheet. |
|---|
| | | - `js`: a list of scripts that should be loaded. A script is described with the `JSResource` type which is also defined in `quartz/resources.tsx`. It allows you to define a load time (either before or after the DOM has been loaded), whether it should be a module, and either the source URL or the inline content of the script. |
|---|
| | | - `additionalHead`: a list of JSX elements or functions that return JSX elements to be added to the `<head>` tag of the page. Functions receive the page's data as an argument and can conditionally render elements. |
|---|
| | | |
|---|
| | | ## Transformers |
|---|
| | | |
|---|
| | |
|---|
| | | ```ts |
|---|
| | | export type QuartzTransformerPluginInstance = { |
|---|
| | | name: string |
|---|
| | | textTransform?: (ctx: BuildCtx, src: string | Buffer) => string | Buffer |
|---|
| | | textTransform?: (ctx: BuildCtx, src: string) => string |
|---|
| | | markdownPlugins?: (ctx: BuildCtx) => PluggableList |
|---|
| | | htmlPlugins?: (ctx: BuildCtx) => PluggableList |
|---|
| | | externalResources?: (ctx: BuildCtx) => Partial<StaticResources> |
|---|
| | |
|---|
| | | |
|---|
| | | Normally for both `remark` and `rehype`, you can find existing plugins that you can use to . If you'd like to create your own `remark` or `rehype` plugin, checkout the [guide to creating a plugin](https://unifiedjs.com/learn/guide/create-a-plugin/) using `unified` (the underlying AST parser and transformer library). |
|---|
| | | |
|---|
| | | A good example of a transformer plugin that borrows from the `remark` and `rehype` ecosystems is the [[Latex]] plugin: |
|---|
| | | A good example of a transformer plugin that borrows from the `remark` and `rehype` ecosystems is the [[plugins/Latex|Latex]] plugin: |
|---|
| | | |
|---|
| | | ```ts title="quartz/plugins/transformers/latex.ts" |
|---|
| | | import remarkMath from "remark-math" |
|---|
| | | import rehypeKatex from "rehype-katex" |
|---|
| | | import rehypeMathjax from "rehype-mathjax/svg.js" |
|---|
| | | import rehypeMathjax from "rehype-mathjax/svg" |
|---|
| | | import { QuartzTransformerPlugin } from "../types" |
|---|
| | | |
|---|
| | | interface Options { |
|---|
| | |
|---|
| | | externalResources() { |
|---|
| | | if (engine === "katex") { |
|---|
| | | return { |
|---|
| | | css: ["https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css"], |
|---|
| | | css: [ |
|---|
| | | { |
|---|
| | | // base css |
|---|
| | | content: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css", |
|---|
| | | }, |
|---|
| | | ], |
|---|
| | | js: [ |
|---|
| | | { |
|---|
| | | src: "https://cdn.jsdelivr.net/npm/katex@0.16.7/dist/contrib/copy-tex.min.js", |
|---|
| | | // fix copy behaviour: https://github.com/KaTeX/KaTeX/blob/main/contrib/copy-tex/README.md |
|---|
| | | src: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/copy-tex.min.js", |
|---|
| | | loadTime: "afterDOMReady", |
|---|
| | | contentType: "external", |
|---|
| | | }, |
|---|
| | | ], |
|---|
| | | } |
|---|
| | | } else { |
|---|
| | | return {} |
|---|
| | | } |
|---|
| | | }, |
|---|
| | | } |
|---|
| | |
|---|
| | | |
|---|
| | | export type QuartzEmitterPluginInstance = { |
|---|
| | | name: string |
|---|
| | | emit(ctx: BuildCtx, content: ProcessedContent[], resources: StaticResources): Promise<FilePath[]> |
|---|
| | | emit( |
|---|
| | | ctx: BuildCtx, |
|---|
| | | content: ProcessedContent[], |
|---|
| | | resources: StaticResources, |
|---|
| | | ): Promise<FilePath[]> | AsyncGenerator<FilePath> |
|---|
| | | partialEmit?( |
|---|
| | | ctx: BuildCtx, |
|---|
| | | content: ProcessedContent[], |
|---|
| | | resources: StaticResources, |
|---|
| | | changeEvents: ChangeEvent[], |
|---|
| | | ): Promise<FilePath[]> | AsyncGenerator<FilePath> | null |
|---|
| | | getQuartzComponents(ctx: BuildCtx): QuartzComponent[] |
|---|
| | | } |
|---|
| | | ``` |
|---|
| | | |
|---|
| | | An emitter plugin must define a `name` field, an `emit` function, and a `getQuartzComponents` function. `emit` is responsible for looking at all the parsed and filtered content and then appropriately creating files and returning a list of paths to files the plugin created. |
|---|
| | | An emitter plugin must define a `name` field, an `emit` function, and a `getQuartzComponents` function. It can optionally implement a `partialEmit` function for incremental builds. |
|---|
| | | |
|---|
| | | - `emit` is responsible for looking at all the parsed and filtered content and then appropriately creating files and returning a list of paths to files the plugin created. |
|---|
| | | - `partialEmit` is an optional function that enables incremental builds. It receives information about which files have changed (`changeEvents`) and can selectively rebuild only the necessary files. This is useful for optimizing build times in development mode. If `partialEmit` is undefined, it will default to the `emit` function. |
|---|
| | | - `getQuartzComponents` declares which Quartz components the emitter uses to construct its pages. |
|---|
| | | |
|---|
| | | Creating new files can be done via regular Node [fs module](https://nodejs.org/api/fs.html) (i.e. `fs.cp` or `fs.writeFile`) or via the `write` function in `quartz/plugins/emitters/helpers.ts` if you are creating files that contain text. `write` has the following signature: |
|---|
| | | |
|---|
| | |
|---|
| | | // the build context |
|---|
| | | ctx: BuildCtx |
|---|
| | | // the name of the file to emit (not including the file extension) |
|---|
| | | slug: ServerSlug |
|---|
| | | slug: FullSlug |
|---|
| | | // the file extension |
|---|
| | | ext: `.${string}` | "" |
|---|
| | | // the file content to add |
|---|
| | |
|---|
| | | ...defaultContentPageLayout, |
|---|
| | | pageBody: Content(), |
|---|
| | | } |
|---|
| | | const { head, header, beforeBody, pageBody, left, right, footer } = layout |
|---|
| | | const { head, header, beforeBody, pageBody, afterBody, left, right, footer } = layout |
|---|
| | | return { |
|---|
| | | name: "ContentPage", |
|---|
| | | getQuartzComponents() { |
|---|
| | | return [head, ...header, ...beforeBody, pageBody, ...left, ...right, footer] |
|---|
| | | return [head, ...header, ...beforeBody, pageBody, ...afterBody, ...left, ...right, footer] |
|---|
| | | }, |
|---|
| | | async emit(ctx, content, resources, emit): Promise<FilePath[]> { |
|---|
| | | const cfg = ctx.cfg.configuration |
|---|
| | |
|---|
| | | const allFiles = content.map((c) => c[1].data) |
|---|
| | | for (const [tree, file] of content) { |
|---|
| | | const slug = canonicalizeServer(file.data.slug!) |
|---|
| | | const externalResources = pageResources(slug, resources) |
|---|
| | | const externalResources = pageResources(slug, file.data, resources) |
|---|
| | | const componentData: QuartzComponentProps = { |
|---|
| | | fileData: file.data, |
|---|
| | | externalResources, |
|---|
| | |
|---|
| | | allFiles, |
|---|
| | | } |
|---|
| | | |
|---|
| | | const content = renderPage(slug, componentData, opts, externalResources) |
|---|
| | | const content = renderPage(cfg, slug, componentData, opts, externalResources) |
|---|
| | | const fp = await emit({ |
|---|
| | | content, |
|---|
| | | slug: file.data.slug!, |
|---|
