docs: update plugin documentation

docs/advanced/making plugins.md

@@ -53,12 +53,12 @@ All transformer plugins must define at least a `name` field to register the plug
 
 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 {
@@ -84,10 +84,14 @@ export const Latex: QuartzTransformerPlugin<Options> = (opts?: Options) => {
     externalResources() {
       if (engine === "katex") {
         return {
-          css: ["https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css"],
+          css: [
+            // base css
+            "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css",
+          ],
           js: [
             {
-              src: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/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",
             },

docs/authoring content.md

@@ -38,3 +38,7 @@ Some common frontmatter fields that are natively supported by Quartz:
 
 When your Quartz is at a point you're happy with, you can save your changes to GitHub.
 First, make sure you've [[setting up your GitHub repository|already setup your GitHub repository]] and then do `npx quartz sync`.
+
+## Customization
+
+Frontmatter parsing for `title`, `tags`, `aliases` and `cssclasses` is a functionality of the [[Frontmatter]] plugin, `date` is handled by the [[CreatedModifiedDate]] plugin and `description` by the [[Description]] plugin. See the plugin pages for customization options.

docs/configuration.md

@@ -56,30 +56,48 @@ You can think of Quartz plugins as a series of transformations over content.
 
 ![[quartz transform pipeline.png]]
 
-```ts
+```ts title="quartz.config.ts"
 plugins: {
   transformers: [...],
   filters: [...],
   emitters: [...],
 }
 ```
 
-- [[making plugins#Transformers|Transformers]] **map** over content (e.g. parsing frontmatter, generating a description)
-- [[making plugins#Filters|Filters]] **filter** content (e.g. filtering out drafts)
-- [[making plugins#Emitters|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with a specific tag)
+- [[tags/plugin/transformer|Transformers]] **map** over content (e.g. parsing frontmatter, generating a description)
+- [[tags/plugin/filter|Filters]] **filter** content (e.g. filtering out drafts)
+- [[tags/plugin/emitter|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with a specific tag)
 
-By adding, removing, and reordering plugins from the `tranformers`, `filters`, and `emitters` fields, you can customize the behaviour of Quartz.
+You can customize the behaviour of Quartz by adding, removing and reordering plugins in the `transformers`, `filters` and `emitters` fields.
 
 > [!note]
-> Each node is modified by every transformer _in order_. Some transformers are position-sensitive so you may need to take special note of whether it needs come before or after any other particular plugins.
+> Each node is modified by every transformer _in order_. Some transformers are position sensitive, so you may need to pay particular attention to whether they need to come before or after certain other plugins.
 
-Additionally, plugins may also have their own configuration settings that you can pass in. For example, the [[Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose between Katex and MathJax.
+To add a plugin, you insert a line with its function call, followed by a semicolon in the appropriate category. For example, to add the [[ExplicitPublish]] plugin (a [[tags/plugin/transformer|Transformer]], you would add the following line:
 
-```ts
+```ts title="quartz.config.ts"
 transformers: [
-  Plugin.FrontMatter(), // uses default options
-  Plugin.Latex({ renderEngine: "katex" }), // specify some options
+  ...
+  Plugin.ExplicitPublish(),
+  ...
+],
+```
+
+To remove a plugin, you remove all occurrences of it in the `quartz.config.ts`.
+
+In addition, plugins may also have their own configuration settings that you can pass in. If you do not pass in a configuration, the plugin will use its default settings.
+
+For example, the [[plugins/Latex|Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose between Katex and MathJax.
+
+```ts title="quartz.config.ts"
+transformers: [
+  Plugin.FrontMatter(), // use default options
+  Plugin.Latex({ renderEngine: "katex" }), // set some custom options
 ]
 ```
 
-If you'd like to make your own plugins, read the guide on [[making plugins]] for more information.
+Some plugins are included by default in the[ `quartz.config.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz.config.ts), but there are more available.
+
+You can see a list of all plugins and their configuration options [[tags/plugin|here]].
+
+If you'd like to make your own plugins, see the [[making plugins|making custom plugins]] guide.

docs/features/Latex.md

@@ -1,6 +1,7 @@
 ---
+title: LaTeX
 tags:
-  - plugin/transformer
+  - feature/transformer
 ---
 
 Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time.
@@ -53,11 +54,6 @@ For example:
 - Incorrect: `I have $1 and you have $2` produces I have $1 and you have $2
 - Correct: `I have \$1 and you have \$2` produces I have \$1 and you have \$2
 
-## MathJax
-
-In `quartz.config.ts`, you can configure Quartz to use [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html) by replacing `Plugin.Latex({ renderEngine: 'katex' })` with `Plugin.Latex({ renderEngine: 'mathjax' })`
-
 ## Customization
 
-- Removing Latex support: remove all instances of `Plugin.Latex()` from `quartz.config.ts`.
-- Plugin: `quartz/plugins/transformers/latex.ts`
+Latex parsing is a functionality of the [[plugins/Latex|Latex]] plugin. See the plugin page for customization options.

docs/features/Mermaid diagrams.md

@@ -1,9 +1,13 @@
+---
+title: "Mermaid Diagrams"
+---
+
 Quartz supports Mermaid which allows you to add diagrams and charts to your notes. Mermaid supports a range of diagrams, such as [flow charts](https://mermaid.js.org/syntax/flowchart.html), [sequence diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html), and [timelines](https://mermaid.js.org/syntax/timeline.html). This is enabled as a part of [[Obsidian compatibility]] and can be configured and enabled/disabled from that plugin.
 
 By default, Quartz will render Mermaid diagrams to match the site theme.
 
 > [!warning]
-> Wondering why Mermaid diagrams may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is _after_ `Plugin.SyntaxHighlighting()`.
+> Wondering why Mermaid diagrams may not be showing up even if you have them enabled? You may need to reorder your plugins so that [[ObsidianFlavoredMarkdown]] is _after_ [[SyntaxHighlighting]].
 
 ## Syntax
 

docs/features/Obsidian compatibility.md

@@ -1,33 +1,17 @@
 ---
+title: "Obsidian Compatibility"
 tags:
-  - plugin/transformer
+  - feature/transformer
 ---
 
 Quartz was originally designed as a tool to publish Obsidian vaults as websites. Even as the scope of Quartz has widened over time, it hasn't lost the ability to seamlessly interoperate with Obsidian.
 
-By default, Quartz ships with `Plugin.ObsidianFlavoredMarkdown` which is a transformer plugin that adds support for [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown). This includes support for features like [[wikilinks]] and [[Mermaid diagrams]].
+By default, Quartz ships with the [[ObsidianFlavoredMarkdown]] plugin, which is a transformer plugin that adds support for [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown). This includes support for features like [[wikilinks]] and [[Mermaid diagrams]].
 
-It also ships with support for [frontmatter parsing](https://help.obsidian.md/Editing+and+formatting/Properties) with the same fields that Obsidian uses through the `Plugin.FrontMatter` transformer plugin.
+It also ships with support for [frontmatter parsing](https://help.obsidian.md/Editing+and+formatting/Properties) with the same fields that Obsidian uses through the [[Frontmatter]] transformer plugin.
 
-Finally, Quartz also provides `Plugin.CrawlLinks` which allows you to customize Quartz's link resolution behaviour to match Obsidian.
+Finally, Quartz also provides [[CrawlLinks]] plugin, which allows you to customize Quartz's link resolution behaviour to match Obsidian.
 
 ## Configuration
 
-- Frontmatter parsing:
-  - Disabling: remove all instances of `Plugin.FrontMatter()` from `quartz.config.ts`.
-  - Customize default values for frontmatter: edit `quartz/plugins/transformers/frontmatter.ts`
-- Obsidian Flavored Markdown:
-  - Disabling: remove all instances of `Plugin.ObsidianFlavoredMarkdown()` from `quartz.config.ts`
-  - Customizing features: `Plugin.ObsidianFlavoredMarkdown` has several other options to toggle on and off:
-    - `comments`: whether to enable `%%` style Obsidian comments. Defaults to `true`
-    - `highlight`: whether to enable `==` style highlights. Defaults to `true`
-    - `wikilinks`: whether to enable turning [[wikilinks]] into regular links. Defaults to `true`
-    - `callouts`: whether to enable [[callouts]]. Defaults to `true`
-    - `mermaid`: whether to enable [[Mermaid diagrams]]. Defaults to `true`
-    - `parseTags`: whether to try and parse tags in the content body. Defaults to `true`
-    - `parseArrows`: whether to try and parse arrows in the content body. Defaults to `true`.
-    - `enableInHtmlEmbed`: whether to try and parse Obsidian flavoured markdown in raw HTML. Defaults to `false`
-    - `enableYouTubeEmbed`: whether to enable embedded YouTube videos using external image Markdown syntax. Defaults to `false`
-- Link resolution behaviour:
-  - Disabling: remove all instances of `Plugin.CrawlLinks()` from `quartz.config.ts`
-  - Changing link resolution preference: set `markdownLinkResolution` to one of `absolute`, `relative` or `shortest`
+This functionality is provided by the [[ObsidianFlavoredMarkdown]], [[Frontmatter]] and [[CrawlLinks]] plugins. See the plugin pages for customization options.

docs/features/OxHugo compatibility.md

@@ -1,11 +1,12 @@
 ---
+title: "OxHugo Compatibility"
 tags:
-  - plugin/transformer
+  - feature/transformer
 ---
 
 [org-roam](https://www.orgroam.com/) is a plain-text personal knowledge management system for [emacs](https://en.wikipedia.org/wiki/Emacs). [ox-hugo](https://github.com/kaushalmodi/ox-hugo) is org exporter backend that exports `org-mode` files to [Hugo](https://gohugo.io/) compatible Markdown.
 
-Because the Markdown generated by ox-hugo is not pure Markdown but Hugo specific, we need to transform it to fit into Quartz. This is done by `Plugin.OxHugoFlavouredMarkdown`. Even though this [[making plugins|plugin]] was written with `ox-hugo` in mind, it should work for any Hugo specific Markdown.
+Because the Markdown generated by ox-hugo is not pure Markdown but Hugo specific, we need to transform it to fit into Quartz. This is done by the [[OxHugoFlavoredMarkdown]] plugin. Even though this plugin was written with `ox-hugo` in mind, it should work for any Hugo specific Markdown.
 
 ```typescript title="quartz.config.ts"
 plugins: {
@@ -25,15 +26,4 @@ Quartz by default doesn't understand `org-roam` files as they aren't Markdown. Y
 
 ## Configuration
 
-- Link resolution
-  - `wikilinks`: Whether to replace `{{ relref }}` with Quartz [[wikilinks]]
-  - `removePredefinedAnchor`: Whether to remove [pre-defined anchor set by ox-hugo](https://ox-hugo.scripter.co/doc/anchors/).
-- Image handling
-  - `replaceFigureWithMdImg`: Whether to replace `<figure/>` with `![]()`
-- Formatting
-  - `removeHugoShortcode`: Whether to remove hugo shortcode syntax (`{{}}`)
-  - `replaceOrgLatex`: Whether to replace org-mode formatting for latex fragments with what `Plugin.Latex` supports.
-
-> [!warning]
->
-> While you can use `Plugin.OxHugoFlavoredMarkdown` and `Plugin.ObsidianFlavoredMarkdown` together, it's not recommended because it might mutate the file in unexpected ways. Use with caution.
+This functionality is provided by the [[OxHugoFlavoredMarkdown]] plugin. See the plugin page for customization options.

docs/features/RSS Feed.md

@@ -2,6 +2,4 @@ Quartz creates an RSS feed for all the content on your site by generating an `in
 
 ## Configuration
 
-- Remove RSS feed: set the `enableRSS` field of `Plugin.ContentIndex` in `quartz.config.ts` to be `false`.
-- Change number of entries: set the `rssLimit` field of `Plugin.ContentIndex` to be the desired value. It defaults to latest 10 items.
-- Use rich HTML output in RSS: set `rssFullHtml` field of `Plugin.ContentIndex` to be `true`.
+This functionality is provided by the [[ContentIndex]] plugin. See the plugin page for customization options.

docs/features/callouts.md

@@ -1,7 +1,7 @@
 ---
 title: Callouts
 tags:
-  - plugin/transformer
+  - feature/transformer
 ---
 
 Quartz supports the same Admonition-callout syntax as Obsidian.
@@ -19,12 +19,13 @@ This includes
 See [documentation on supported types and syntax here](https://help.obsidian.md/Editing+and+formatting/Callouts).
 
 > [!warning]
-> Wondering why callouts may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is _after_ `Plugin.SyntaxHighlighting()`.
+> Wondering why callouts may not be showing up even if you have them enabled? You may need to reorder your plugins so that [[ObsidianFlavoredMarkdown]] is _after_ [[SyntaxHighlighting]].
 
 ## Customization
 
-- Disable callouts: simply pass `callouts: false` to the plugin: `Plugin.ObsidianFlavoredMarkdown({ callouts: false })`
-- Editing icons: `quartz/styles/callouts.scss`
+The callouts are a functionality of the [[ObsidianFlavoredMarkdown]] plugin. See the plugin page for how to enable or disable them.
+
+You can edit the icons by customizing `quartz/styles/callouts.scss`.
 
 ### Add custom callouts
 

docs/features/folder and tag listings.md

@@ -1,7 +1,7 @@
 ---
 title: Folder and Tag Listings
 tags:
-  - plugin/emitter
+  - feature/emitter
 ---
 
 Quartz creates listing pages for any folders and tags you have.
@@ -26,7 +26,4 @@ Like folder listings, you can also provide a description and title for a tag pag
 
 ## Customization
 
-The layout for both the folder and content pages can be customized. By default, they use the `defaultListPageLayout` in `quartz.layouts.ts`. If you'd like to make more involved changes to the layout and don't mind editing some [[creating components|Quartz components]], you can take a look at `quartz/components/pages/FolderContent.tsx` and `quartz/components/pages/TagContent.tsx` respectively.
-
-- Removing folder listings: remove `Plugin.FolderPage()` from `emitters` in `quartz.config.ts`
-- Removing tag listings: remove `Plugin.TagPage()` from `emitters` in `quartz.config.ts`
+The folder listings are a functionality of the [[FolderPage]] plugin, the tag listings of the [[TagPage]] plugin. See the plugin pages for customization options.

docs/features/private pages.md

@@ -1,16 +1,16 @@
 ---
 title: Private Pages
 tags:
-  - plugin/filter
+  - feature/filter
 ---
 
 There may be some notes you want to avoid publishing as a website. Quartz supports this through two mechanisms which can be used in conjunction:
 
 ## Filter Plugins
 
-[[making plugins#Filters|Filter plugins]] are plugins that filter out content based off of certain criteria. By default, Quartz uses the `Plugin.RemoveDrafts` plugin which filters out any note that has `draft: true` in the frontmatter.
+[[making plugins#Filters|Filter plugins]] are plugins that filter out content based off of certain criteria. By default, Quartz uses the [[RemoveDrafts]] plugin which filters out any note that has `draft: true` in the frontmatter.
 
-If you'd like to only publish a select number of notes, you can instead use `Plugin.ExplicitPublish` which will filter out all notes except for any that have `publish: true` in the frontmatter.
+If you'd like to only publish a select number of notes, you can instead use [[ExplicitPublish]] which will filter out all notes except for any that have `publish: true` in the frontmatter.
 
 > [!warning]
 > Regardless of the filter plugin used, **all non-markdown files will be emitted and available publically in the final build.** This includes files such as images, voice recordings, PDFs, etc. One way to prevent this and still be able to embed local images is to create a folder specifically for public media and add the following two patterns to the ignorePatterns array.

docs/features/syntax highlighting.md

@@ -1,7 +1,7 @@
 ---
 title: Syntax Highlighting
 tags:
-  - plugin/transformer
+  - feature/transformer
 ---
 
 Syntax highlighting in Quartz is completely done at build-time. This means that Quartz only ships pre-calculated CSS to highlight the right words so there is no heavy client-side bundle that does the syntax highlighting.
@@ -130,6 +130,4 @@ const [name, setName] = useState('Taylor');
 
 ## Customization
 
-- Removing syntax highlighting: delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`.
-- Style: By default, Quartz uses derivatives of the GitHub light and dark themes. You can customize the colours in the `quartz/styles/syntax.scss` file.
-- Plugin: `quartz/plugins/transformers/syntax.ts`
+Syntax highlighting is a functionality of the [[SyntaxHighlighting]] plugin. See the plugin page for customization options.

docs/features/table of contents.md

@@ -2,25 +2,16 @@
 title: "Table of Contents"
 tags:
   - component
-  - plugin/transformer
+  - feature/transformer
 ---
 
 Quartz can automatically generate a table of contents from a list of headings on each page. It will also show you your current scroll position on the site by marking headings you've scrolled through with a different colour.
 
-By default, it will show all headers from H1 (`# Title`) all the way to H3 (`### Title`) and will only show the table of contents if there is more than 1 header on the page.
+By default, it shows all headings from H1 (`# Title`) to H3 (`### Title`) and only shows the table of contents if there is more than one heading on the page.
 You can also hide the table of contents on a page by adding `enableToc: false` to the frontmatter for that page.
 
-> [!info]
-> This feature requires both `Plugin.TableOfContents` in your `quartz.config.ts` and `Component.TableOfContents` in your `quartz.layout.ts` to function correctly.
-
 ## Customization
 
-- Removing table of contents: remove all instances of `Plugin.TableOfContents()` from `quartz.config.ts`. and `Component.TableOfContents()` from `quartz.layout.ts`
-- Changing the max depth: pass in a parameter to `Plugin.TableOfContents({ maxDepth: 4 })`
-- Changing the minimum number of entries in the Table of Contents before it renders: pass in a parameter to `Plugin.TableOfContents({ minEntries: 3 })`
-- Collapse the table of content by default: pass in a parameter to `Plugin.TableOfContents({ collapseByDefault: true })`
-- Component: `quartz/components/TableOfContents.tsx`
-- Style:
-  - Modern (default): `quartz/components/styles/toc.scss`
-  - Legacy Quartz 3 style: `quartz/components/styles/legacyToc.scss`
-- Script: `quartz/components/scripts/toc.inline.ts`
+The table of contents is a functionality of the [[TableOfContents]] plugin. See the plugin page for customization options.
+
+It also needs the `TableOfContents` component. The component can be configured with the `layout` parameter, which can either be `modern` (default) or `legacy`.