From c530dbe28f8b2e6b09890417c4a23b446ba6f701 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Sun, 18 Feb 2024 19:32:01 +0100 Subject: [PATCH 01/38] docs: first few plugins documented --- docs/configuration.md | 87 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 366430cc2f799..7b25bcd391f71 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -73,7 +73,7 @@ By adding, removing, and reordering plugins from the `tranformers`, `filters`, a > [!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. -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. +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. If you do not pass in a configuration, the plugin will use its default settings. ```ts transformers: [ @@ -83,3 +83,88 @@ transformers: [ ``` If you'd like to make your own plugins, read the guide on [[making plugins]] for more information. + +By default, Quartz is configured to use the following plugins: + +```ts +transformers: [ + Plugin.FrontMatter(...), + Plugin.CreatedModifiedDate(...), + Plugin.Latex(...), + Plugin.SyntaxHighlighting(...), + Plugin.ObsidianFlavoredMarkdown(...), + Plugin.GitHubFlavoredMarkdown(), + Plugin.TableOfContents(), + Plugin.CrawlLinks(...), + Plugin.Description(), +] + +filters: [ + Plugin.RemoveDrafts() +] + +emitters: [ + Plugin.AliasRedirects(), + Plugin.ComponentResources(...), + Plugin.ContentPage(), + Plugin.FolderPage(), + Plugin.TagPage(), + Plugin.ContentIndex(...), + Plugin.Assets(), + Plugin.Static(), + Plugin.NotFoundPage(), +] +``` + +There are a few more that you can add to the `transformers`, `filters`, and `emitters`: + +```ts +transformers: [ + Plugin.HardLineBreaks(), + Plugin.OxHugoFlavouredMarkdown(), +] + +filters: [ + Plugin.ExplicitPublish(), +] + +emitters: [ + Plugin.CNAME(), +] +``` + +### Plugin.FrontMatter + +This plugin uses [gray-matter](https://github.com/jonschlinkert/gray-matter) to parse the frontmatter of the file for the metadata fields `title`, `tags`, `aliases` and `cssclasses`. See [[authoring content#Syntax]] for a description of what Quartz does with the content of these fields. + +Options: + +- `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. +- `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. + +### Plugin.CreatedModifiedDate + +This plugin determines the created, modified, and published dates for a file using three potential data sources: front matter metadata, Git history, and the filesystem. + +If it encounters invalid date formats, it defaults to the current date. + +Options: + +- `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. + +### Plugin.Latex + +This plugin adds LaTeX rendering support. See [[Latex]] for more details. + +Options: + +- `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. + +### Plugin.SyntaxHighlighting + +This plugin adds syntax highlighting for code blocks. See [[syntax highlighting]] for more information. + +#### Options + +- `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. +- `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. \ No newline at end of file From 149c8c87bd660b66ddec214051eed74abfcaf190 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 10:46:33 +0100 Subject: [PATCH 02/38] docs: move plugin info --- docs/authoring content.md | 18 ++++++++++++++++++ docs/features/Latex.md | 7 +++++-- docs/features/syntax highlighting.md | 10 +++++++--- 3 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/authoring content.md b/docs/authoring content.md index c259e501100bf..b8c15ed048345 100644 --- a/docs/authoring content.md +++ b/docs/authoring content.md @@ -1,5 +1,7 @@ --- title: Authoring Content +tags: + - plugin/transformer --- All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've [[index#🪴 Get Started|setup Quartz]] already, this folder should already be initialized. Any Markdown in this folder will get processed by Quartz. @@ -34,7 +36,23 @@ Some common frontmatter fields that are natively supported by Quartz: - `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz. - `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format. +The frontmatter is parsed using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. ## Syncing your Content 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. The plugin is defined in `quartz/plugins/transformers/frontmatter.ts`. + +- This plugin (`Plugin.SyntaxHighlighting()`) should not be removed from `quartz.config.ts`, otherwise Quartz will break. +- To customize frontmatter parsing, use the configuration options of the plugin: + - `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. + - `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. + +Frontmatter parsing for `date` is a functionality of the `CreatedModifiedDate` plugin. The plugin is defined in `quartz/plugins/transformers/lastmod.ts`. + +- To remove dates from all pages, delete all usages of `Plugin.CreatedModifiedDate()` from `quartz.config.ts`. +- To customize date parsing, use the configuration options of the plugin: + - `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. \ No newline at end of file diff --git a/docs/features/Latex.md b/docs/features/Latex.md index 3c8f6ff1fde5a..a0a2c24125e51 100644 --- a/docs/features/Latex.md +++ b/docs/features/Latex.md @@ -59,5 +59,8 @@ In `quartz.config.ts`, you can configure Quartz to use [MathJax SVG rendering](h ## Customization -- Removing Latex support: remove all instances of `Plugin.Latex()` from `quartz.config.ts`. -- Plugin: `quartz/plugins/transformers/latex.ts` +Syntax highlighting is a functionality of the `Latex` plugin. The plugin is defined in `quartz/plugins/transformers/latex.ts`. + +- To remove Latex support, delete all usages of `Plugin.Latex()` from `quartz.config.ts`. +- To customize Latex support, use the configuration options of the plugin: + - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. diff --git a/docs/features/syntax highlighting.md b/docs/features/syntax highlighting.md index 68436c2da599b..1f85ce4e1483d 100644 --- a/docs/features/syntax highlighting.md +++ b/docs/features/syntax highlighting.md @@ -130,6 +130,10 @@ 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. The plugin is defined in `quartz/plugins/transformers/syntax.ts`. + +- To remove syntax highlighting, delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`. +- To customize syntax highlighting, use the configuration options of the plugin: + - `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. + - `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. +- In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. From ff4986689cfa3b79a278ce1cf267320ba0d79122 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 11:18:46 +0100 Subject: [PATCH 03/38] docs: move plugin docs to tag based system --- docs/advanced/making plugins.md | 2 +- docs/authoring content.md | 15 +---- docs/configuration.md | 89 +--------------------------- docs/features/Latex.md | 8 +-- docs/features/syntax highlighting.md | 10 +--- docs/index.md | 2 +- docs/plugins/CreatedModifiedDate.md | 17 ++++++ docs/plugins/Frontmatter.md | 14 +++++ docs/plugins/Latex.md | 13 ++++ docs/plugins/SyntaxHighlighting.md | 15 +++++ docs/plugins/index.md | 3 + docs/tags/plugin.md | 3 + 12 files changed, 73 insertions(+), 118 deletions(-) create mode 100644 docs/plugins/CreatedModifiedDate.md create mode 100644 docs/plugins/Frontmatter.md create mode 100644 docs/plugins/Latex.md create mode 100644 docs/plugins/SyntaxHighlighting.md create mode 100644 docs/plugins/index.md create mode 100644 docs/tags/plugin.md diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md index 565f5bdba9752..7504de06ee2c8 100644 --- a/docs/advanced/making plugins.md +++ b/docs/advanced/making plugins.md @@ -53,7 +53,7 @@ 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" diff --git a/docs/authoring content.md b/docs/authoring content.md index b8c15ed048345..e652f1f8c085c 100644 --- a/docs/authoring content.md +++ b/docs/authoring content.md @@ -1,7 +1,5 @@ --- title: Authoring Content -tags: - - plugin/transformer --- All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've [[index#🪴 Get Started|setup Quartz]] already, this folder should already be initialized. Any Markdown in this folder will get processed by Quartz. @@ -44,15 +42,4 @@ First, make sure you've [[setting up your GitHub repository|already setup your G ## Customization -Frontmatter parsing for `title`, `tags`, `aliases` and `cssclasses` is a functionality of the `FrontMatter` plugin. The plugin is defined in `quartz/plugins/transformers/frontmatter.ts`. - -- This plugin (`Plugin.SyntaxHighlighting()`) should not be removed from `quartz.config.ts`, otherwise Quartz will break. -- To customize frontmatter parsing, use the configuration options of the plugin: - - `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. - - `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. - -Frontmatter parsing for `date` is a functionality of the `CreatedModifiedDate` plugin. The plugin is defined in `quartz/plugins/transformers/lastmod.ts`. - -- To remove dates from all pages, delete all usages of `Plugin.CreatedModifiedDate()` from `quartz.config.ts`. -- To customize date parsing, use the configuration options of the plugin: - - `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. \ No newline at end of file +Frontmatter parsing for `title`, `tags`, `aliases` and `cssclasses` is a functionality of the [[Frontmatter]] plugin. Frontmatter parsing for `date` is a functionality of the [[CreatedModifiedDate]] plugin. See the plugin pages for customization options. diff --git a/docs/configuration.md b/docs/configuration.md index 7b25bcd391f71..926a983d4085f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -73,7 +73,7 @@ By adding, removing, and reordering plugins from the `tranformers`, `filters`, a > [!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. -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. If you do not pass in a configuration, the plugin will use its default settings. +Additionally, plugins may also have their own configuration settings that you can pass in. For example, the [[plugins/Latex|Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose between Katex and MathJax. If you do not pass in a configuration, the plugin will use its default settings. ```ts transformers: [ @@ -82,89 +82,6 @@ transformers: [ ] ``` -If you'd like to make your own plugins, read the guide on [[making plugins]] for more information. +The current default plugins can be found [here](https://github.com/jackyzha0/quartz/blob/v4/quartz.config.ts). For a list of all plugins and the available configuration options, visit the [[plugin]] tag overview. -By default, Quartz is configured to use the following plugins: - -```ts -transformers: [ - Plugin.FrontMatter(...), - Plugin.CreatedModifiedDate(...), - Plugin.Latex(...), - Plugin.SyntaxHighlighting(...), - Plugin.ObsidianFlavoredMarkdown(...), - Plugin.GitHubFlavoredMarkdown(), - Plugin.TableOfContents(), - Plugin.CrawlLinks(...), - Plugin.Description(), -] - -filters: [ - Plugin.RemoveDrafts() -] - -emitters: [ - Plugin.AliasRedirects(), - Plugin.ComponentResources(...), - Plugin.ContentPage(), - Plugin.FolderPage(), - Plugin.TagPage(), - Plugin.ContentIndex(...), - Plugin.Assets(), - Plugin.Static(), - Plugin.NotFoundPage(), -] -``` - -There are a few more that you can add to the `transformers`, `filters`, and `emitters`: - -```ts -transformers: [ - Plugin.HardLineBreaks(), - Plugin.OxHugoFlavouredMarkdown(), -] - -filters: [ - Plugin.ExplicitPublish(), -] - -emitters: [ - Plugin.CNAME(), -] -``` - -### Plugin.FrontMatter - -This plugin uses [gray-matter](https://github.com/jonschlinkert/gray-matter) to parse the frontmatter of the file for the metadata fields `title`, `tags`, `aliases` and `cssclasses`. See [[authoring content#Syntax]] for a description of what Quartz does with the content of these fields. - -Options: - -- `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. -- `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. - -### Plugin.CreatedModifiedDate - -This plugin determines the created, modified, and published dates for a file using three potential data sources: front matter metadata, Git history, and the filesystem. - -If it encounters invalid date formats, it defaults to the current date. - -Options: - -- `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. - -### Plugin.Latex - -This plugin adds LaTeX rendering support. See [[Latex]] for more details. - -Options: - -- `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. - -### Plugin.SyntaxHighlighting - -This plugin adds syntax highlighting for code blocks. See [[syntax highlighting]] for more information. - -#### Options - -- `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. -- `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. \ No newline at end of file +If you'd like to make your own plugins, read the guide on [[making plugins]] for more information. \ No newline at end of file diff --git a/docs/features/Latex.md b/docs/features/Latex.md index a0a2c24125e51..dcbeced0d9cfc 100644 --- a/docs/features/Latex.md +++ b/docs/features/Latex.md @@ -1,6 +1,4 @@ --- -tags: - - plugin/transformer --- Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time. @@ -59,8 +57,4 @@ In `quartz.config.ts`, you can configure Quartz to use [MathJax SVG rendering](h ## Customization -Syntax highlighting is a functionality of the `Latex` plugin. The plugin is defined in `quartz/plugins/transformers/latex.ts`. - -- To remove Latex support, delete all usages of `Plugin.Latex()` from `quartz.config.ts`. -- To customize Latex support, use the configuration options of the plugin: - - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. +Latex parsing is a functionality of the [[plugins/Latex|Latex]] plugin. See the plugin page for customization options. diff --git a/docs/features/syntax highlighting.md b/docs/features/syntax highlighting.md index 1f85ce4e1483d..6614119878130 100644 --- a/docs/features/syntax highlighting.md +++ b/docs/features/syntax highlighting.md @@ -1,7 +1,5 @@ --- title: Syntax Highlighting -tags: - - plugin/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,10 +128,4 @@ const [name, setName] = useState('Taylor'); ## Customization -Syntax highlighting is a functionality of the `SyntaxHighlighting` plugin. The plugin is defined in `quartz/plugins/transformers/syntax.ts`. - -- To remove syntax highlighting, delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`. -- To customize syntax highlighting, use the configuration options of the plugin: - - `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. - - `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. -- In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. +Syntax highlighting is a functionality of the [[SyntaxHighlighting]] plugin. See the plugin page for customization options. diff --git a/docs/index.md b/docs/index.md index f25b6e24425d4..87cf024a3458c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,7 +31,7 @@ If you prefer instructions in a video format you can try following Nicole van de ## 🔧 Features -- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], [[Docker Support]], [[i18n|internationalization]] and [many more](./features) right out of the box +- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[features/Latex|Latex]], [[syntax highlighting]], [[popover previews]], [[Docker Support]], [[i18n|internationalization]] 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 diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md new file mode 100644 index 0000000000000..7884c17ea6b40 --- /dev/null +++ b/docs/plugins/CreatedModifiedDate.md @@ -0,0 +1,17 @@ +--- +title: "Plugin.CreatedModifiedDate()" +tags: + - plugin/transformer +--- + +This plugin determines the created, modified, and published dates for a document using three potential data sources: front matter metadata, Git history, and the filesystem. + +If it encounters invalid date formats, it defaults to the current date. + +- To remove dates from all pages, delete all usages of `Plugin.CreatedModifiedDate()` from `quartz.config.ts`. +- To customize date parsing, use the configuration options of the plugin: + - `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. + +The source of this plugin can be found in [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). + +See the backlinks for functionalities where this plugin is used. diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md new file mode 100644 index 0000000000000..84c37e5d8c5bc --- /dev/null +++ b/docs/plugins/Frontmatter.md @@ -0,0 +1,14 @@ +--- +title: "Plugin.Frontmatter()" +tags: + - plugin/transformer +--- + +- This plugin (`Plugin.Frontmatter()`) should not be removed from `quartz.config.ts`, otherwise Quartz will break. +- To customize frontmatter parsing, use the configuration options of the plugin: + - `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. + - `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. + +The source of this plugin can be found in [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts). + +See the backlinks for functionalities where this plugin is used. diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md new file mode 100644 index 0000000000000..296d8e9bd0c01 --- /dev/null +++ b/docs/plugins/Latex.md @@ -0,0 +1,13 @@ +--- +title: "Plugin.Latex()" +tags: + - plugin/transformer +--- + +- To remove Latex support, delete all usages of `Plugin.Latex()` from `quartz.config.ts`. +- To customize Latex support, use the configuration options of the plugin: + - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. + +The source of this plugin can be found in [`quartz/plugins/transformers/latex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/latex.ts). + +See the backlinks for functionalities where this plugin is used. diff --git a/docs/plugins/SyntaxHighlighting.md b/docs/plugins/SyntaxHighlighting.md new file mode 100644 index 0000000000000..769d2aaf796a6 --- /dev/null +++ b/docs/plugins/SyntaxHighlighting.md @@ -0,0 +1,15 @@ +--- +title: "Plugin.SyntaxHighlighting()" +tags: + - plugin/transformer +--- + +- To remove syntax highlighting, delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`. +- To customize syntax highlighting, use the configuration options of the plugin: + - `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. + - `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. +- In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. + +The source of this plugin can be found in [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts). + +See the backlinks for functionalities where this plugin is used. diff --git a/docs/plugins/index.md b/docs/plugins/index.md new file mode 100644 index 0000000000000..298ff164cf8b7 --- /dev/null +++ b/docs/plugins/index.md @@ -0,0 +1,3 @@ +--- +title: Plugins +--- diff --git a/docs/tags/plugin.md b/docs/tags/plugin.md new file mode 100644 index 0000000000000..298ff164cf8b7 --- /dev/null +++ b/docs/tags/plugin.md @@ -0,0 +1,3 @@ +--- +title: Plugins +--- From c28a0534b3057570c6ae3454c1aaa6677fdcf4df Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 11:19:16 +0100 Subject: [PATCH 04/38] docs: update latex example code snippet --- docs/advanced/making plugins.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md index 7504de06ee2c8..4e60a22d1e0ee 100644 --- a/docs/advanced/making plugins.md +++ b/docs/advanced/making plugins.md @@ -58,7 +58,7 @@ A good example of a transformer plugin that borrows from the `remark` and `rehyp ```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 { @@ -74,8 +74,6 @@ export const Latex: QuartzTransformerPlugin = (opts?: Options) => { }, htmlPlugins() { if (engine === "katex") { - // if you need to pass options into a plugin, you - // can use a tuple of [plugin, options] return [[rehypeKatex, { output: "html" }]] } else { return [rehypeMathjax] @@ -84,10 +82,14 @@ export const Latex: QuartzTransformerPlugin = (opts?: Options) => { externalResources() { if (engine === "katex") { return { - css: ["https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css"], + css: [ + // base css + "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/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://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/copy-tex.min.js", loadTime: "afterDOMReady", contentType: "external", }, From d8d2b097f60f3234cd564decedb3165a2ed22a22 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 11:19:37 +0100 Subject: [PATCH 05/38] docs: fix spelling of latex in title --- docs/features/Latex.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/features/Latex.md b/docs/features/Latex.md index dcbeced0d9cfc..8b53f1f11804e 100644 --- a/docs/features/Latex.md +++ b/docs/features/Latex.md @@ -1,4 +1,5 @@ --- +title: LaTeX --- Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time. From 2c9193749dbb0c645b8c2db8da926ec4a17c4e4c Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 11:20:41 +0100 Subject: [PATCH 06/38] docs: add missing linebreak --- docs/authoring content.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/authoring content.md b/docs/authoring content.md index e652f1f8c085c..a7ae9e2ffc66b 100644 --- a/docs/authoring content.md +++ b/docs/authoring content.md @@ -35,6 +35,7 @@ Some common frontmatter fields that are natively supported by Quartz: - `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format. The frontmatter is parsed using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. + ## Syncing your Content When your Quartz is at a point you're happy with, you can save your changes to GitHub. From cb1c1c06c6b0721a5b9990323a8904fb996a58f8 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 11:23:18 +0100 Subject: [PATCH 07/38] docs: remove plugin tag from feature pages --- docs/features/Obsidian compatibility.md | 2 -- docs/features/OxHugo compatibility.md | 2 -- docs/features/callouts.md | 2 -- docs/features/folder and tag listings.md | 2 -- docs/features/private pages.md | 2 -- docs/features/table of contents.md | 1 - 6 files changed, 11 deletions(-) diff --git a/docs/features/Obsidian compatibility.md b/docs/features/Obsidian compatibility.md index 1254370e0765a..830563e86ae99 100644 --- a/docs/features/Obsidian compatibility.md +++ b/docs/features/Obsidian compatibility.md @@ -1,6 +1,4 @@ --- -tags: - - plugin/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. diff --git a/docs/features/OxHugo compatibility.md b/docs/features/OxHugo compatibility.md index 3143eb1b5f265..3db8c4a8e17ba 100644 --- a/docs/features/OxHugo compatibility.md +++ b/docs/features/OxHugo compatibility.md @@ -1,6 +1,4 @@ --- -tags: - - plugin/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. diff --git a/docs/features/callouts.md b/docs/features/callouts.md index d73979284ab66..e1ee26e6b5dbf 100644 --- a/docs/features/callouts.md +++ b/docs/features/callouts.md @@ -1,7 +1,5 @@ --- title: Callouts -tags: - - plugin/transformer --- Quartz supports the same Admonition-callout syntax as Obsidian. diff --git a/docs/features/folder and tag listings.md b/docs/features/folder and tag listings.md index dfde7c26ebc57..364b0f007ddf3 100644 --- a/docs/features/folder and tag listings.md +++ b/docs/features/folder and tag listings.md @@ -1,7 +1,5 @@ --- title: Folder and Tag Listings -tags: - - plugin/emitter --- Quartz creates listing pages for any folders and tags you have. diff --git a/docs/features/private pages.md b/docs/features/private pages.md index 638c628b6b662..972c941193473 100644 --- a/docs/features/private pages.md +++ b/docs/features/private pages.md @@ -1,7 +1,5 @@ --- title: Private Pages -tags: - - plugin/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: diff --git a/docs/features/table of contents.md b/docs/features/table of contents.md index 0298ffaabf9f5..db3e5e4cac3e6 100644 --- a/docs/features/table of contents.md +++ b/docs/features/table of contents.md @@ -2,7 +2,6 @@ title: "Table of Contents" tags: - component - - plugin/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. From 5a41958ba4751fdcd9aae3cefe899c47145011b0 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 18:31:55 +0100 Subject: [PATCH 08/38] docs: shorten titles --- docs/plugins/CreatedModifiedDate.md | 4 ++-- docs/plugins/Frontmatter.md | 6 +++--- docs/plugins/Latex.md | 4 ++-- docs/plugins/SyntaxHighlighting.md | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index 7884c17ea6b40..10a956fbd319e 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -1,5 +1,5 @@ --- -title: "Plugin.CreatedModifiedDate()" +title: "CreatedModifiedDate" tags: - plugin/transformer --- @@ -10,7 +10,7 @@ If it encounters invalid date formats, it defaults to the current date. - To remove dates from all pages, delete all usages of `Plugin.CreatedModifiedDate()` from `quartz.config.ts`. - To customize date parsing, use the configuration options of the plugin: - - `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. + - `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. The source of this plugin can be found in [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md index 84c37e5d8c5bc..6d6f2d5cf66e8 100644 --- a/docs/plugins/Frontmatter.md +++ b/docs/plugins/Frontmatter.md @@ -1,13 +1,13 @@ --- -title: "Plugin.Frontmatter()" +title: "Frontmatter" tags: - plugin/transformer --- - This plugin (`Plugin.Frontmatter()`) should not be removed from `quartz.config.ts`, otherwise Quartz will break. - To customize frontmatter parsing, use the configuration options of the plugin: - - `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. - - `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. + - `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. + - `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. The source of this plugin can be found in [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts). diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md index 296d8e9bd0c01..bb665f87abb10 100644 --- a/docs/plugins/Latex.md +++ b/docs/plugins/Latex.md @@ -1,12 +1,12 @@ --- -title: "Plugin.Latex()" +title: "Latex" tags: - plugin/transformer --- - To remove Latex support, delete all usages of `Plugin.Latex()` from `quartz.config.ts`. - To customize Latex support, use the configuration options of the plugin: - - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. + - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. The source of this plugin can be found in [`quartz/plugins/transformers/latex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/latex.ts). diff --git a/docs/plugins/SyntaxHighlighting.md b/docs/plugins/SyntaxHighlighting.md index 769d2aaf796a6..47f0c054c1d06 100644 --- a/docs/plugins/SyntaxHighlighting.md +++ b/docs/plugins/SyntaxHighlighting.md @@ -1,13 +1,13 @@ --- -title: "Plugin.SyntaxHighlighting()" +title: "SyntaxHighlighting" tags: - plugin/transformer --- - To remove syntax highlighting, delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`. - To customize syntax highlighting, use the configuration options of the plugin: - - `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. - - `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. + - `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. + - `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. - In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. The source of this plugin can be found in [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts). From 624dd369e300c15873f0440f800f19ef18330409 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 18:33:58 +0100 Subject: [PATCH 09/38] docs: refine wording --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 926a983d4085f..42dd1174d120b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -84,4 +84,4 @@ transformers: [ The current default plugins can be found [here](https://github.com/jackyzha0/quartz/blob/v4/quartz.config.ts). For a list of all plugins and the available configuration options, visit the [[plugin]] tag overview. -If you'd like to make your own plugins, read the guide on [[making plugins]] for more information. \ No newline at end of file +If you'd like to make your own plugins, read the guide on [[making plugins|making custom plugins]] for more information. From 082b1753cedf02da2328aee85f23e98694e7dc99 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 18:37:14 +0100 Subject: [PATCH 10/38] docs: move plugin details for frontmatter --- docs/authoring content.md | 2 -- docs/plugins/Frontmatter.md | 2 ++ 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authoring content.md b/docs/authoring content.md index a7ae9e2ffc66b..f9aeabcfe7ca2 100644 --- a/docs/authoring content.md +++ b/docs/authoring content.md @@ -34,8 +34,6 @@ Some common frontmatter fields that are natively supported by Quartz: - `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz. - `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format. -The frontmatter is parsed using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. - ## Syncing your Content When your Quartz is at a point you're happy with, you can save your changes to GitHub. diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md index 6d6f2d5cf66e8..94226f96e4a5b 100644 --- a/docs/plugins/Frontmatter.md +++ b/docs/plugins/Frontmatter.md @@ -4,6 +4,8 @@ tags: - plugin/transformer --- +This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. + - This plugin (`Plugin.Frontmatter()`) should not be removed from `quartz.config.ts`, otherwise Quartz will break. - To customize frontmatter parsing, use the configuration options of the plugin: - `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. From 0cb71005e070ce0258e3b2efd508ce1b3fb98666 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 21:48:34 +0100 Subject: [PATCH 11/38] docs: add features/* tags --- docs/features/Latex.md | 2 ++ docs/features/Mermaid diagrams.md | 4 ++++ docs/features/Obsidian compatibility.md | 3 +++ docs/features/OxHugo compatibility.md | 3 +++ docs/features/callouts.md | 2 ++ docs/features/folder and tag listings.md | 2 ++ docs/features/private pages.md | 2 ++ docs/features/syntax highlighting.md | 2 ++ docs/features/table of contents.md | 1 + 9 files changed, 21 insertions(+) diff --git a/docs/features/Latex.md b/docs/features/Latex.md index 8b53f1f11804e..9e46d987ff29b 100644 --- a/docs/features/Latex.md +++ b/docs/features/Latex.md @@ -1,5 +1,7 @@ --- title: LaTeX +tags: + - features/transformer --- Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time. diff --git a/docs/features/Mermaid diagrams.md b/docs/features/Mermaid diagrams.md index f14a5589b7701..c247518d9cfda 100644 --- a/docs/features/Mermaid diagrams.md +++ b/docs/features/Mermaid diagrams.md @@ -1,3 +1,7 @@ +--- +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. diff --git a/docs/features/Obsidian compatibility.md b/docs/features/Obsidian compatibility.md index 830563e86ae99..acbfc468e5279 100644 --- a/docs/features/Obsidian compatibility.md +++ b/docs/features/Obsidian compatibility.md @@ -1,4 +1,7 @@ --- +title: "Obsidian Compatibility" +tags: + - features/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. diff --git a/docs/features/OxHugo compatibility.md b/docs/features/OxHugo compatibility.md index 3db8c4a8e17ba..876f54e9e4a09 100644 --- a/docs/features/OxHugo compatibility.md +++ b/docs/features/OxHugo compatibility.md @@ -1,4 +1,7 @@ --- +title: "OxHugo Compatibility" +tags: + - features/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. diff --git a/docs/features/callouts.md b/docs/features/callouts.md index e1ee26e6b5dbf..428ab25f2fc46 100644 --- a/docs/features/callouts.md +++ b/docs/features/callouts.md @@ -1,5 +1,7 @@ --- title: Callouts +tags: + - features/transformer --- Quartz supports the same Admonition-callout syntax as Obsidian. diff --git a/docs/features/folder and tag listings.md b/docs/features/folder and tag listings.md index 364b0f007ddf3..6e28f93348d6f 100644 --- a/docs/features/folder and tag listings.md +++ b/docs/features/folder and tag listings.md @@ -1,5 +1,7 @@ --- title: Folder and Tag Listings +tags: + - features/emitter --- Quartz creates listing pages for any folders and tags you have. diff --git a/docs/features/private pages.md b/docs/features/private pages.md index 972c941193473..32f3a993ba15b 100644 --- a/docs/features/private pages.md +++ b/docs/features/private pages.md @@ -1,5 +1,7 @@ --- title: Private Pages +tags: + - 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: diff --git a/docs/features/syntax highlighting.md b/docs/features/syntax highlighting.md index 6614119878130..ccc6e5a3fc1ea 100644 --- a/docs/features/syntax highlighting.md +++ b/docs/features/syntax highlighting.md @@ -1,5 +1,7 @@ --- title: Syntax Highlighting +tags: + - features/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. diff --git a/docs/features/table of contents.md b/docs/features/table of contents.md index db3e5e4cac3e6..e5612a6ffe250 100644 --- a/docs/features/table of contents.md +++ b/docs/features/table of contents.md @@ -2,6 +2,7 @@ title: "Table of Contents" tags: - component + - features/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. From 503aaf2cc957233c8137d1a5c6ef6d046d466e67 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 21:56:19 +0100 Subject: [PATCH 12/38] docs: update latex example --- docs/advanced/making plugins.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md index 4e60a22d1e0ee..b2bacf0aa3f3c 100644 --- a/docs/advanced/making plugins.md +++ b/docs/advanced/making plugins.md @@ -74,6 +74,8 @@ export const Latex: QuartzTransformerPlugin = (opts?: Options) => { }, htmlPlugins() { if (engine === "katex") { + // if you need to pass options into a plugin, you + // can use a tuple of [plugin, options] return [[rehypeKatex, { output: "html" }]] } else { return [rehypeMathjax] @@ -84,12 +86,12 @@ export const Latex: QuartzTransformerPlugin = (opts?: Options) => { return { css: [ // base css - "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css", + "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css", ], js: [ { // fix copy behaviour: https://github.com/KaTeX/KaTeX/blob/main/contrib/copy-tex/README.md - src: "https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/copy-tex.min.js", + src: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/copy-tex.min.js", loadTime: "afterDOMReady", contentType: "external", }, From 4e7912bb457db17358ccd06e98e7664d1e046c9e Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 22:03:07 +0100 Subject: [PATCH 13/38] docs: make references more explicit --- docs/plugins/CreatedModifiedDate.md | 6 +----- docs/plugins/Frontmatter.md | 4 +--- docs/plugins/Latex.md | 4 ++-- docs/plugins/SyntaxHighlighting.md | 4 ++-- 4 files changed, 6 insertions(+), 12 deletions(-) diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index 10a956fbd319e..494b67696fe83 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -4,14 +4,10 @@ tags: - plugin/transformer --- -This plugin determines the created, modified, and published dates for a document using three potential data sources: front matter metadata, Git history, and the filesystem. - -If it encounters invalid date formats, it defaults to the current date. +This plugin determines the created, modified, and published dates for a document using three potential data sources: front matter metadata, Git history, and the filesystem. See [[authoring content#Syntax]] for more information. - To remove dates from all pages, delete all usages of `Plugin.CreatedModifiedDate()` from `quartz.config.ts`. - To customize date parsing, use the configuration options of the plugin: - `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. The source of this plugin can be found in [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). - -See the backlinks for functionalities where this plugin is used. diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md index 94226f96e4a5b..efcb415852647 100644 --- a/docs/plugins/Frontmatter.md +++ b/docs/plugins/Frontmatter.md @@ -4,7 +4,7 @@ tags: - plugin/transformer --- -This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. +This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. See [[authoring content#Syntax]] for more information. - This plugin (`Plugin.Frontmatter()`) should not be removed from `quartz.config.ts`, otherwise Quartz will break. - To customize frontmatter parsing, use the configuration options of the plugin: @@ -12,5 +12,3 @@ This plugin parses the frontmatter of the page using the [gray-matter](https://g - `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. The source of this plugin can be found in [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts). - -See the backlinks for functionalities where this plugin is used. diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md index bb665f87abb10..e7910a180bf6d 100644 --- a/docs/plugins/Latex.md +++ b/docs/plugins/Latex.md @@ -4,10 +4,10 @@ tags: - plugin/transformer --- +This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more information. + - To remove Latex support, delete all usages of `Plugin.Latex()` from `quartz.config.ts`. - To customize Latex support, use the configuration options of the plugin: - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. The source of this plugin can be found in [`quartz/plugins/transformers/latex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/latex.ts). - -See the backlinks for functionalities where this plugin is used. diff --git a/docs/plugins/SyntaxHighlighting.md b/docs/plugins/SyntaxHighlighting.md index 47f0c054c1d06..398568633e76c 100644 --- a/docs/plugins/SyntaxHighlighting.md +++ b/docs/plugins/SyntaxHighlighting.md @@ -4,6 +4,8 @@ tags: - plugin/transformer --- +This plugin is used to add syntax highlighting to code blocks in Quartz. See [[syntax highlighting]] for more information. + - To remove syntax highlighting, delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`. - To customize syntax highlighting, use the configuration options of the plugin: - `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. @@ -11,5 +13,3 @@ tags: - In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. The source of this plugin can be found in [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts). - -See the backlinks for functionalities where this plugin is used. From 467d6692230246e438820665e8b4cc8c47432e12 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Mon, 19 Feb 2024 22:10:19 +0100 Subject: [PATCH 14/38] docs: add stubs for the remaining plugins --- docs/plugins/AliasRedirects.md | 7 +++++++ docs/plugins/Assets.md | 7 +++++++ docs/plugins/CNAME.md | 7 +++++++ docs/plugins/ComponentResources.md | 7 +++++++ docs/plugins/ContentIndex.md | 7 +++++++ docs/plugins/ContentPage.md | 7 +++++++ docs/plugins/CrawlLinks.md | 7 +++++++ docs/plugins/Description.md | 7 +++++++ docs/plugins/ExplicitPublish.md | 7 +++++++ docs/plugins/FolderPage.md | 7 +++++++ docs/plugins/GitHubFlavoredMarkdown.md | 7 +++++++ docs/plugins/HardLineBreaks.md | 7 +++++++ docs/plugins/NotFoundPage.md | 7 +++++++ docs/plugins/ObsidianFlavoredMarkdown.md | 7 +++++++ docs/plugins/OxHugoFlavoredMarkdown.md | 7 +++++++ docs/plugins/RemoveDrafts.md | 7 +++++++ docs/plugins/Static.md | 7 +++++++ docs/plugins/TableOfContents.md | 7 +++++++ docs/plugins/TagPage.md | 7 +++++++ 19 files changed, 133 insertions(+) create mode 100644 docs/plugins/AliasRedirects.md create mode 100644 docs/plugins/Assets.md create mode 100644 docs/plugins/CNAME.md create mode 100644 docs/plugins/ComponentResources.md create mode 100644 docs/plugins/ContentIndex.md create mode 100644 docs/plugins/ContentPage.md create mode 100644 docs/plugins/CrawlLinks.md create mode 100644 docs/plugins/Description.md create mode 100644 docs/plugins/ExplicitPublish.md create mode 100644 docs/plugins/FolderPage.md create mode 100644 docs/plugins/GitHubFlavoredMarkdown.md create mode 100644 docs/plugins/HardLineBreaks.md create mode 100644 docs/plugins/NotFoundPage.md create mode 100644 docs/plugins/ObsidianFlavoredMarkdown.md create mode 100644 docs/plugins/OxHugoFlavoredMarkdown.md create mode 100644 docs/plugins/RemoveDrafts.md create mode 100644 docs/plugins/Static.md create mode 100644 docs/plugins/TableOfContents.md create mode 100644 docs/plugins/TagPage.md diff --git a/docs/plugins/AliasRedirects.md b/docs/plugins/AliasRedirects.md new file mode 100644 index 0000000000000..4081a2ac5d87a --- /dev/null +++ b/docs/plugins/AliasRedirects.md @@ -0,0 +1,7 @@ +--- +title: AliasRedirects +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md new file mode 100644 index 0000000000000..9ffae91cf2c9d --- /dev/null +++ b/docs/plugins/Assets.md @@ -0,0 +1,7 @@ +--- +title: Assets +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/CNAME.md b/docs/plugins/CNAME.md new file mode 100644 index 0000000000000..db05000a84682 --- /dev/null +++ b/docs/plugins/CNAME.md @@ -0,0 +1,7 @@ +--- +title: CNAME +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/ComponentResources.md b/docs/plugins/ComponentResources.md new file mode 100644 index 0000000000000..17b1686ac21b7 --- /dev/null +++ b/docs/plugins/ComponentResources.md @@ -0,0 +1,7 @@ +--- +title: ComponentResources +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/ContentIndex.md b/docs/plugins/ContentIndex.md new file mode 100644 index 0000000000000..2734ec4c7b313 --- /dev/null +++ b/docs/plugins/ContentIndex.md @@ -0,0 +1,7 @@ +--- +title: ContentIndex +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/ContentPage.md b/docs/plugins/ContentPage.md new file mode 100644 index 0000000000000..4371297736ecc --- /dev/null +++ b/docs/plugins/ContentPage.md @@ -0,0 +1,7 @@ +--- +title: ContentPage +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/CrawlLinks.md b/docs/plugins/CrawlLinks.md new file mode 100644 index 0000000000000..962443f07d039 --- /dev/null +++ b/docs/plugins/CrawlLinks.md @@ -0,0 +1,7 @@ +--- +title: CrawlLinks +tags: + - plugin/transformer +--- + +This plugin ... diff --git a/docs/plugins/Description.md b/docs/plugins/Description.md new file mode 100644 index 0000000000000..dbb201c740f21 --- /dev/null +++ b/docs/plugins/Description.md @@ -0,0 +1,7 @@ +--- +title: Description +tags: + - plugin/transformer +--- + +This plugin ... diff --git a/docs/plugins/ExplicitPublish.md b/docs/plugins/ExplicitPublish.md new file mode 100644 index 0000000000000..288ae74476183 --- /dev/null +++ b/docs/plugins/ExplicitPublish.md @@ -0,0 +1,7 @@ +--- +title: ExplicitPublish +tags: + - plugin/filter +--- + +This plugin ... diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md new file mode 100644 index 0000000000000..fa391244f8160 --- /dev/null +++ b/docs/plugins/FolderPage.md @@ -0,0 +1,7 @@ +--- +title: FolderPage +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/GitHubFlavoredMarkdown.md b/docs/plugins/GitHubFlavoredMarkdown.md new file mode 100644 index 0000000000000..4aaf99a092395 --- /dev/null +++ b/docs/plugins/GitHubFlavoredMarkdown.md @@ -0,0 +1,7 @@ +--- +title: GitHubFlavoredMarkdown +tags: + - plugin/transformer +--- + +This plugin ... diff --git a/docs/plugins/HardLineBreaks.md b/docs/plugins/HardLineBreaks.md new file mode 100644 index 0000000000000..12ae2195c0b3d --- /dev/null +++ b/docs/plugins/HardLineBreaks.md @@ -0,0 +1,7 @@ +--- +title: HardLineBreaks +tags: + - plugin/transformer +--- + +This plugin ... diff --git a/docs/plugins/NotFoundPage.md b/docs/plugins/NotFoundPage.md new file mode 100644 index 0000000000000..afe11688c0726 --- /dev/null +++ b/docs/plugins/NotFoundPage.md @@ -0,0 +1,7 @@ +--- +title: NotFoundPage +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/ObsidianFlavoredMarkdown.md b/docs/plugins/ObsidianFlavoredMarkdown.md new file mode 100644 index 0000000000000..c138e4bc734f0 --- /dev/null +++ b/docs/plugins/ObsidianFlavoredMarkdown.md @@ -0,0 +1,7 @@ +--- +title: ObsidianFlavoredMarkdown +tags: + - plugin/transformer +--- + +This plugin ... diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md new file mode 100644 index 0000000000000..4d49a03ac4caf --- /dev/null +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -0,0 +1,7 @@ +--- +title: OxHugoFlavoredMarkdown +tags: + - plugin/transformer +--- + +This plugin ... diff --git a/docs/plugins/RemoveDrafts.md b/docs/plugins/RemoveDrafts.md new file mode 100644 index 0000000000000..ca0c5e328580c --- /dev/null +++ b/docs/plugins/RemoveDrafts.md @@ -0,0 +1,7 @@ +--- +title: RemoveDrafts +tags: + - plugin/filter +--- + +This plugin ... diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md new file mode 100644 index 0000000000000..721724eaea265 --- /dev/null +++ b/docs/plugins/Static.md @@ -0,0 +1,7 @@ +--- +title: Static +tags: + - plugin/emitter +--- + +This plugin ... diff --git a/docs/plugins/TableOfContents.md b/docs/plugins/TableOfContents.md new file mode 100644 index 0000000000000..3b8f6abbdd115 --- /dev/null +++ b/docs/plugins/TableOfContents.md @@ -0,0 +1,7 @@ +--- +title: TableOfContents +tags: + - plugin/transformer +--- + +This plugin ... diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md new file mode 100644 index 0000000000000..b370f254f1ab0 --- /dev/null +++ b/docs/plugins/TagPage.md @@ -0,0 +1,7 @@ +--- +title: TagPage +tags: + - plugin/emitter +--- + +This plugin ... From 7dd589f8048ae075587511a3785f958d3ae66fe1 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 10:43:59 +0100 Subject: [PATCH 15/38] docs: more descriptions --- docs/plugins/AliasRedirects.md | 4 +++- docs/plugins/Assets.md | 4 +++- docs/plugins/CNAME.md | 4 +++- docs/plugins/ComponentResources.md | 2 +- docs/plugins/ContentIndex.md | 10 +++++++++- docs/plugins/ContentPage.md | 2 +- docs/plugins/CrawlLinks.md | 10 +++++++++- docs/plugins/CreatedModifiedDate.md | 2 +- docs/plugins/Description.md | 12 +++++++++++- docs/plugins/ExplicitPublish.md | 4 +++- docs/plugins/FolderPage.md | 4 +++- docs/plugins/GitHubFlavoredMarkdown.md | 9 ++++++++- docs/plugins/HardLineBreaks.md | 4 +++- docs/plugins/NotFoundPage.md | 4 +++- docs/plugins/ObsidianFlavoredMarkdown.md | 17 ++++++++++++++++- docs/plugins/OxHugoFlavoredMarkdown.md | 10 +++++++++- docs/plugins/RemoveDrafts.md | 4 +++- docs/plugins/Static.md | 2 +- docs/plugins/TableOfContents.md | 9 ++++++++- docs/plugins/TagPage.md | 2 +- 20 files changed, 99 insertions(+), 20 deletions(-) diff --git a/docs/plugins/AliasRedirects.md b/docs/plugins/AliasRedirects.md index 4081a2ac5d87a..7600c7384d60c 100644 --- a/docs/plugins/AliasRedirects.md +++ b/docs/plugins/AliasRedirects.md @@ -4,4 +4,6 @@ tags: - plugin/emitter --- -This plugin ... +This plugin generates HTML redirect pages for aliases and permalinks defined in the frontmatter of content files, so that alternative paths correctly lead to the intended content. + +- To remove this functionality, delete all usages of `Plugin.AliasRedirects()` from `quartz.config.ts`. \ No newline at end of file diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index 9ffae91cf2c9d..4a7205b53ca57 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -4,4 +4,6 @@ tags: - plugin/emitter --- -This plugin ... +This plugin manages and emits non-Markdown assets (like images, scripts, stylesheets, etc.) from the content directory to the output directory. It ensures that all required static assets are available in the generated site. + +- To remove support for static content, delete all usages of `Plugin.Assets()` from `quartz.config.ts`. \ No newline at end of file diff --git a/docs/plugins/CNAME.md b/docs/plugins/CNAME.md index db05000a84682..67cd7fa4dee90 100644 --- a/docs/plugins/CNAME.md +++ b/docs/plugins/CNAME.md @@ -4,4 +4,6 @@ tags: - plugin/emitter --- -This plugin ... +This plugin generates a `CNAME` file as part of the site's output. This is needed for configuring custom domain names on platforms like GitHub Pages. The domain name is extracted from the site's base URL, which is then written to a `CNAME` file in the root of the output directory. + +- To add this functionality, add `Plugin.CNAME()` to the `emitters` section of `quartz.config.ts`. \ No newline at end of file diff --git a/docs/plugins/ComponentResources.md b/docs/plugins/ComponentResources.md index 17b1686ac21b7..f9771c70748b4 100644 --- a/docs/plugins/ComponentResources.md +++ b/docs/plugins/ComponentResources.md @@ -4,4 +4,4 @@ tags: - plugin/emitter --- -This plugin ... +This plugin manages and emits the static resources required for the Quartz framework. This includes CSS stylesheets and JavaScript scripts that enhance the functionality and aesthetics of the generated site. diff --git a/docs/plugins/ContentIndex.md b/docs/plugins/ContentIndex.md index 2734ec4c7b313..7e17939bba140 100644 --- a/docs/plugins/ContentIndex.md +++ b/docs/plugins/ContentIndex.md @@ -4,4 +4,12 @@ tags: - plugin/emitter --- -This plugin ... +This plugin creates a comprehensive index of the site's content, generating additional resources like a sitemap and RSS feed. + +- To remove this functionality, delete all usages of `Plugin.ContentIndex()` from `quartz.config.ts`. +- To customize, use the configuration options of the plugin: + - `enableSiteMap`: When `true` (default), generates a sitemap XML file (`sitemap.xml`) listing all site URLs for search engines in content discovery. + - `enableRSS`: When `true` (default), produces an RSS feed (`index.xml`) with recent content updates. + - `rssLimit`: Defines the maximum number of entries to include in the RSS feed, helping to focus on the most recent or relevant content. Defaults to `10`. + - `rssFullHtml`: When `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries. + - `includeEmptyFiles`: When `true` (default), content files with no body text are included in the generated index and resources. \ No newline at end of file diff --git a/docs/plugins/ContentPage.md b/docs/plugins/ContentPage.md index 4371297736ecc..4847a1cd9b4ae 100644 --- a/docs/plugins/ContentPage.md +++ b/docs/plugins/ContentPage.md @@ -4,4 +4,4 @@ tags: - plugin/emitter --- -This plugin ... +This plugin is a core component of the Quartz framework. It generates the HTML pages for each piece of Markdown content. It creates the full-page layout, including headers, footers, and body content, among others. \ No newline at end of file diff --git a/docs/plugins/CrawlLinks.md b/docs/plugins/CrawlLinks.md index 962443f07d039..8e297d6c39d65 100644 --- a/docs/plugins/CrawlLinks.md +++ b/docs/plugins/CrawlLinks.md @@ -4,4 +4,12 @@ tags: - plugin/transformer --- -This plugin ... +This plugin parses links and processes them to point to the right places. It is also needed for embedded links (like images). + +- To remove link processing, remove, delete all usages of `Plugin.CrawlLinks()` from `quartz.config.ts`. This is _not_ recommended and will likely break the page. +- To customize link processing, use the configuration options of the plugin: + - `markdownLinkResolution`: Defines the strategy for resolving Markdown paths, can be `"absolute"` (default), `"relative"` or `"shortest"`. + - `prettyLinks`: When `true` (default), simplifies links by removing folder paths, making them more user-friendly. + - `openLinksInNewTab`: When `true`, configures external links to open in a new tab. Defaults to `false`. + - `lazyLoad`: When `true`, adds lazy loading to resource elements (`img`, `video`, etc.) to improve page load performance. Defaults to `false`. + - `externalLinkIcon`: Adds an icon next to external links when `true` (default) to visually distinguishing them from internal links. \ No newline at end of file diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index 494b67696fe83..608affc2cf183 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -8,6 +8,6 @@ This plugin determines the created, modified, and published dates for a document - To remove dates from all pages, delete all usages of `Plugin.CreatedModifiedDate()` from `quartz.config.ts`. - To customize date parsing, use the configuration options of the plugin: - - `priority`: the data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. + - `priority`: The data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. The source of this plugin can be found in [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). diff --git a/docs/plugins/Description.md b/docs/plugins/Description.md index dbb201c740f21..836956bd5d170 100644 --- a/docs/plugins/Description.md +++ b/docs/plugins/Description.md @@ -4,4 +4,14 @@ tags: - plugin/transformer --- -This plugin ... +This plugin generates descriptions that are used in various places: +- as metadata for the HTML `head` +- in FolderContent.tsx (TODO: What does it do there?) +- in TagContent.tsx (TODO: What does it do there?) +- in contentIndex.ts (TODO: What does it do there?) + +If the frontmatter contains a `description` property, it is used (see [[authoring content#Syntax]]). Otherwise, the full text of the file is used. + +- To remove descriptions, delete all usages of `Plugin.Description()` from `quartz.config.ts`. +- To customize description generation, use the configuration options of the plugin: + - `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length. \ No newline at end of file diff --git a/docs/plugins/ExplicitPublish.md b/docs/plugins/ExplicitPublish.md index 288ae74476183..8eba4eecb9267 100644 --- a/docs/plugins/ExplicitPublish.md +++ b/docs/plugins/ExplicitPublish.md @@ -4,4 +4,6 @@ tags: - plugin/filter --- -This plugin ... +This plugin filters content based on an explicit `publish` flag in the frontmatter, allowing only content that is explicitly marked for publication (set to `true`) to pass through. It's kind of the opposite of [[RemoveDrafts]]. + +- To add this functionality, add `Plugin.ExplicitPublish()` to the `filters` section of `quartz.config.ts`. \ No newline at end of file diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md index fa391244f8160..eb4a9dab13258 100644 --- a/docs/plugins/FolderPage.md +++ b/docs/plugins/FolderPage.md @@ -4,4 +4,6 @@ tags: - plugin/emitter --- -This plugin ... +This plugin generates index pages for folders, creating a listing page for each folder that contains multiple content files. + +Example: \ No newline at end of file diff --git a/docs/plugins/GitHubFlavoredMarkdown.md b/docs/plugins/GitHubFlavoredMarkdown.md index 4aaf99a092395..9a7ef0e1163b4 100644 --- a/docs/plugins/GitHubFlavoredMarkdown.md +++ b/docs/plugins/GitHubFlavoredMarkdown.md @@ -4,4 +4,11 @@ tags: - plugin/transformer --- -This plugin ... +This plugin enhances Markdown processing to support GitHub Flavored Markdown (GFM) which adds features like autolink literals, footnotes, strikethrough, tables and tasklists. + +In addition, this plugin adds optional features for typographic refinement (such as converting straight quotes to curly quotes, dashes to en-dashes/em-dashes, and ellipses) and automatic heading links as a symbol that appears next to the heading on hover. + + +- To remove recognizing the GitHub Markdown style, delete all usages of `Plugin.GitHubFlavoredMarkdown()` from `quartz.config.ts`. +- `enableSmartyPants`: When true, enables typographic enhancements. Default is true. +- `linkHeadings`: When true, automatically adds links to headings. Default is true. \ No newline at end of file diff --git a/docs/plugins/HardLineBreaks.md b/docs/plugins/HardLineBreaks.md index 12ae2195c0b3d..bca0f2024fa59 100644 --- a/docs/plugins/HardLineBreaks.md +++ b/docs/plugins/HardLineBreaks.md @@ -4,4 +4,6 @@ tags: - plugin/transformer --- -This plugin ... +This plugin automatically converts single line breaks in Markdown text into hard line breaks in the HTML output. This plugin is not enabled by default. + +- To add this functionality, add `Plugin.HardLineBreaks()` to the `transformers` section of `quartz.config.ts`. \ No newline at end of file diff --git a/docs/plugins/NotFoundPage.md b/docs/plugins/NotFoundPage.md index afe11688c0726..45e5abea01c48 100644 --- a/docs/plugins/NotFoundPage.md +++ b/docs/plugins/NotFoundPage.md @@ -4,4 +4,6 @@ tags: - plugin/emitter --- -This plugin ... +This plugin is designed to generate a custom 404 (Not Found) page for the website to handle broken or non-existent URLs. + +- To remove this functionality, delete all usages of `Plugin.NotFoundPage()` from `quartz.config.ts`. \ No newline at end of file diff --git a/docs/plugins/ObsidianFlavoredMarkdown.md b/docs/plugins/ObsidianFlavoredMarkdown.md index c138e4bc734f0..7e8bd7ed95255 100644 --- a/docs/plugins/ObsidianFlavoredMarkdown.md +++ b/docs/plugins/ObsidianFlavoredMarkdown.md @@ -4,4 +4,19 @@ tags: - plugin/transformer --- -This plugin ... +This plugin extends Markdown processing to include features commonly used in Obsidian, such as enhanced link handling, callouts, mermaid diagrams, checkboxes, and more. + +- To ignore Obsidian specific markdown parsing, delete all usages of `Plugin.ObsidianFlavoredMarkdown()` from `quartz.config.ts`. Don't do this if you're using Obsidian to author the content! +- To customize markdown parsing, use the configuration options of the plugin: + - `comments`: When `true` (default), enables parsing of comment blocks. + - `highlight`: When `true` (default), highlights text within content. + - `wikilinks`:When `true` (default), adds wikilink support. + - `callouts`: When `true` (default), adds support for callout blocks for emphasizing content. + - `mermaid`: When `true` (default), enables Mermaid diagram rendering within Markdown files. + - `parseTags`: When `true` (default), parses and links tags within the content. + - `parseArrows`: When `true` (default), transforms arrow symbols into their HTML character equivalents. + - `parseBlockReferences`: When `true` (default), handles block references, linking to specific content blocks. + - `enableInHtmlEmbed`: When `true`, allows embedding of content directly within HTML. Defaults to `false`. + - `enableYouTubeEmbed`: When `true` (default), enables the embedding of YouTube videos. + - `enableVideoEmbed`: When `true` (default), enables the embedding of video files. + - `enableCheckbox`: When `true`, adds support for interactive checkboxes in content. Defaults to `false`. \ No newline at end of file diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md index 4d49a03ac4caf..df70559e6645d 100644 --- a/docs/plugins/OxHugoFlavoredMarkdown.md +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -4,4 +4,12 @@ tags: - plugin/transformer --- -This plugin ... +This plugin modifies Markdown content generated by [ox-hugo](https://github.com/kaushalmodi/ox-hugo) to make it compatible with Quartz, addressing specific formatting and syntax issues. See [[OxHugo compatibility]] for more information. This plugin is not enabled by default. + +- To add this functionality, add `Plugin.OxHugoFlavoredMarkdown()` to the `transformers` section of `quartz.config.ts`. +- To customize, use the configuration options of the plugin: + - `wikilinks`: When `true` (default), converts Hugo `relref` shortcodes to Quartz wikilinks. + - `removePredefinedAnchor`: When `true` (default), strips predefined anchors from headings. + - `removeHugoShortcode`: When `true` (default), removes Hugo shortcode syntax from the content. + - `replaceFigureWithMdImg`: When `true` (default), transforms `
` HTML tags into Markdown image syntax. + - `replaceOrgLatex`: When `true` (default), converts Org-mode LaTeX fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations). \ No newline at end of file diff --git a/docs/plugins/RemoveDrafts.md b/docs/plugins/RemoveDrafts.md index ca0c5e328580c..b9420796775b0 100644 --- a/docs/plugins/RemoveDrafts.md +++ b/docs/plugins/RemoveDrafts.md @@ -4,4 +4,6 @@ tags: - plugin/filter --- -This plugin ... +This plugin is designed to filter out draft content from the publishing pipeline, so only finalized content is made available. It operates by checking the `draft` flag in the frontmatter of each file. When it's set to `true`, the content is filtered out. + +- To disable this functionality, delete all usages of `Plugin.RemoveDrafts()` from `quartz.config.ts`. \ No newline at end of file diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md index 721724eaea265..066deed93ff89 100644 --- a/docs/plugins/Static.md +++ b/docs/plugins/Static.md @@ -4,4 +4,4 @@ tags: - plugin/emitter --- -This plugin ... +This plugin handles the static assets. It ensures that all necessary static files, such as images, scripts, and stylesheets, are included in the final build, ready for deployment. \ No newline at end of file diff --git a/docs/plugins/TableOfContents.md b/docs/plugins/TableOfContents.md index 3b8f6abbdd115..1a07278e8379d 100644 --- a/docs/plugins/TableOfContents.md +++ b/docs/plugins/TableOfContents.md @@ -4,4 +4,11 @@ tags: - plugin/transformer --- -This plugin ... +This plugin generates a Table of Contents (TOC) for Markdown documents. By default it is displayed in the right side bar. + +- To remove the TOC from all pages, delete all usages of `Plugin.TableOfContents()` from `quartz.config.ts`. +- To configure the TOC, use the configuration options of the plugin: + - `maxDepth`: Limits the depth of headings included in the TOC, ranging from `1` (top-level headings only) to `6` (all heading levels). Default is `3`. + - `minEntries`: The minimum number of heading entries required for the TOC to be displayed. Default is `1`. + - `showByDefault`: When `true` (default), the TOC should be shown by default. Can be overridden by frontmatter settings. + - `collapseByDefault`: When `true` the TOC starts in a collapsed state. Default is `false`. \ No newline at end of file diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md index b370f254f1ab0..258531feff2c7 100644 --- a/docs/plugins/TagPage.md +++ b/docs/plugins/TagPage.md @@ -4,4 +4,4 @@ tags: - plugin/emitter --- -This plugin ... +This plugin creates dedicated pages for each tag used in the content. \ No newline at end of file From 260bfb26c14a178d1d77f3677f176a814fadf665 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 10:44:30 +0100 Subject: [PATCH 16/38] docs: fix feature tags --- docs/features/Latex.md | 2 +- docs/features/Obsidian compatibility.md | 2 +- docs/features/OxHugo compatibility.md | 2 +- docs/features/callouts.md | 2 +- docs/features/folder and tag listings.md | 2 +- docs/features/syntax highlighting.md | 2 +- docs/features/table of contents.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/features/Latex.md b/docs/features/Latex.md index 9e46d987ff29b..6e1c59fbb41ae 100644 --- a/docs/features/Latex.md +++ b/docs/features/Latex.md @@ -1,7 +1,7 @@ --- title: LaTeX tags: - - features/transformer + - feature/transformer --- Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time. diff --git a/docs/features/Obsidian compatibility.md b/docs/features/Obsidian compatibility.md index acbfc468e5279..04a1d63de9fc3 100644 --- a/docs/features/Obsidian compatibility.md +++ b/docs/features/Obsidian compatibility.md @@ -1,7 +1,7 @@ --- title: "Obsidian Compatibility" tags: - - features/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. diff --git a/docs/features/OxHugo compatibility.md b/docs/features/OxHugo compatibility.md index 876f54e9e4a09..e8e8331b40a63 100644 --- a/docs/features/OxHugo compatibility.md +++ b/docs/features/OxHugo compatibility.md @@ -1,7 +1,7 @@ --- title: "OxHugo Compatibility" tags: - - features/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. diff --git a/docs/features/callouts.md b/docs/features/callouts.md index 428ab25f2fc46..5b1cb0ee7589f 100644 --- a/docs/features/callouts.md +++ b/docs/features/callouts.md @@ -1,7 +1,7 @@ --- title: Callouts tags: - - features/transformer + - feature/transformer --- Quartz supports the same Admonition-callout syntax as Obsidian. diff --git a/docs/features/folder and tag listings.md b/docs/features/folder and tag listings.md index 6e28f93348d6f..47d5f42732b95 100644 --- a/docs/features/folder and tag listings.md +++ b/docs/features/folder and tag listings.md @@ -1,7 +1,7 @@ --- title: Folder and Tag Listings tags: - - features/emitter + - feature/emitter --- Quartz creates listing pages for any folders and tags you have. diff --git a/docs/features/syntax highlighting.md b/docs/features/syntax highlighting.md index ccc6e5a3fc1ea..16fef2575757b 100644 --- a/docs/features/syntax highlighting.md +++ b/docs/features/syntax highlighting.md @@ -1,7 +1,7 @@ --- title: Syntax Highlighting tags: - - features/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. diff --git a/docs/features/table of contents.md b/docs/features/table of contents.md index e5612a6ffe250..e5ab829b4046c 100644 --- a/docs/features/table of contents.md +++ b/docs/features/table of contents.md @@ -2,7 +2,7 @@ title: "Table of Contents" tags: - component - - features/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. From eb9b1af6a1fef8101166d25d11f7248de4b57d49 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 10:44:40 +0100 Subject: [PATCH 17/38] docs: descriptions --- docs/authoring content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authoring content.md b/docs/authoring content.md index f9aeabcfe7ca2..d872a964fa6c5 100644 --- a/docs/authoring content.md +++ b/docs/authoring content.md @@ -41,4 +41,4 @@ First, make sure you've [[setting up your GitHub repository|already setup your G ## Customization -Frontmatter parsing for `title`, `tags`, `aliases` and `cssclasses` is a functionality of the [[Frontmatter]] plugin. Frontmatter parsing for `date` is a functionality of the [[CreatedModifiedDate]] plugin. See the plugin pages for customization options. +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. From c715df73d94ff406a93f21a52c3598bc10a1993d Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 12:55:32 +0100 Subject: [PATCH 18/38] docs: new plugin pages --- docs/plugins/AliasRedirects.md | 11 ++++++- docs/plugins/Assets.md | 11 ++++++- docs/plugins/CNAME.md | 11 ++++++- docs/plugins/ComponentResources.md | 11 +++++++ docs/plugins/ContentIndex.md | 24 ++++++++++---- docs/plugins/ContentPage.md | 13 +++++++- docs/plugins/CrawlLinks.md | 27 ++++++++++++---- docs/plugins/CreatedModifiedDate.md | 20 +++++++++--- docs/plugins/Description.md | 19 +++++++++-- docs/plugins/ExplicitPublish.md | 11 ++++++- docs/plugins/FolderPage.md | 13 +++++++- docs/plugins/Frontmatter.md | 21 +++++++++--- docs/plugins/GitHubFlavoredMarkdown.md | 14 ++++++-- docs/plugins/HardLineBreaks.md | 11 ++++++- docs/plugins/Latex.md | 13 ++++++-- docs/plugins/NotFoundPage.md | 11 ++++++- docs/plugins/ObsidianFlavoredMarkdown.md | 41 ++++++++++++++++-------- docs/plugins/OxHugoFlavoredMarkdown.md | 28 ++++++++++------ docs/plugins/RemoveDrafts.md | 11 ++++++- docs/plugins/Static.md | 13 +++++++- docs/plugins/SyntaxHighlighting.md | 21 ++++++++---- docs/plugins/TableOfContents.md | 29 ++++++++++++----- docs/plugins/TagPage.md | 13 +++++++- 23 files changed, 317 insertions(+), 80 deletions(-) diff --git a/docs/plugins/AliasRedirects.md b/docs/plugins/AliasRedirects.md index 7600c7384d60c..586c6ccfc1d56 100644 --- a/docs/plugins/AliasRedirects.md +++ b/docs/plugins/AliasRedirects.md @@ -6,4 +6,13 @@ tags: This plugin generates HTML redirect pages for aliases and permalinks defined in the frontmatter of content files, so that alternative paths correctly lead to the intended content. -- To remove this functionality, delete all usages of `Plugin.AliasRedirects()` from `quartz.config.ts`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.AliasRedirects()`. +- Source: [`quartz/plugins/emitters/aliases.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/aliases.ts). diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index 4a7205b53ca57..5c614ca06070f 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -6,4 +6,13 @@ tags: This plugin manages and emits non-Markdown assets (like images, scripts, stylesheets, etc.) from the content directory to the output directory. It ensures that all required static assets are available in the generated site. -- To remove support for static content, delete all usages of `Plugin.Assets()` from `quartz.config.ts`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.Assets()`. +- Source: [`quartz/plugins/emitters/assets.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/assets.ts). diff --git a/docs/plugins/CNAME.md b/docs/plugins/CNAME.md index 67cd7fa4dee90..2a02828105931 100644 --- a/docs/plugins/CNAME.md +++ b/docs/plugins/CNAME.md @@ -6,4 +6,13 @@ tags: This plugin generates a `CNAME` file as part of the site's output. This is needed for configuring custom domain names on platforms like GitHub Pages. The domain name is extracted from the site's base URL, which is then written to a `CNAME` file in the root of the output directory. -- To add this functionality, add `Plugin.CNAME()` to the `emitters` section of `quartz.config.ts`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.CNAME()`. +- Source: [`quartz/plugins/emitters/cname.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/cname.ts). diff --git a/docs/plugins/ComponentResources.md b/docs/plugins/ComponentResources.md index f9771c70748b4..dc5e7e25af343 100644 --- a/docs/plugins/ComponentResources.md +++ b/docs/plugins/ComponentResources.md @@ -5,3 +5,14 @@ tags: --- This plugin manages and emits the static resources required for the Quartz framework. This includes CSS stylesheets and JavaScript scripts that enhance the functionality and aesthetics of the generated site. + +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.ComponentResources()`. +- Source: [`quartz/plugins/emitters/componentResources.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/componentResources.ts). diff --git a/docs/plugins/ContentIndex.md b/docs/plugins/ContentIndex.md index 7e17939bba140..fe4883120609f 100644 --- a/docs/plugins/ContentIndex.md +++ b/docs/plugins/ContentIndex.md @@ -6,10 +6,20 @@ tags: This plugin creates a comprehensive index of the site's content, generating additional resources like a sitemap and RSS feed. -- To remove this functionality, delete all usages of `Plugin.ContentIndex()` from `quartz.config.ts`. -- To customize, use the configuration options of the plugin: - - `enableSiteMap`: When `true` (default), generates a sitemap XML file (`sitemap.xml`) listing all site URLs for search engines in content discovery. - - `enableRSS`: When `true` (default), produces an RSS feed (`index.xml`) with recent content updates. - - `rssLimit`: Defines the maximum number of entries to include in the RSS feed, helping to focus on the most recent or relevant content. Defaults to `10`. - - `rssFullHtml`: When `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries. - - `includeEmptyFiles`: When `true` (default), content files with no body text are included in the generated index and resources. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `enableSiteMap`: When `true` (default), generates a sitemap XML file (`sitemap.xml`) listing all site URLs for search engines in content discovery. +- `enableRSS`: When `true` (default), produces an RSS feed (`index.xml`) with recent content updates. +- `rssLimit`: Defines the maximum number of entries to include in the RSS feed, helping to focus on the most recent or relevant content. Defaults to `10`. +- `rssFullHtml`: When `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries. +- `includeEmptyFiles`: When `true` (default), content files with no body text are included in the generated index and resources. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.ContentIndex()`. +- Source: [`quartz/plugins/emitters/contentIndex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/contentIndex.ts). + diff --git a/docs/plugins/ContentPage.md b/docs/plugins/ContentPage.md index 4847a1cd9b4ae..83b4efe563761 100644 --- a/docs/plugins/ContentPage.md +++ b/docs/plugins/ContentPage.md @@ -4,4 +4,15 @@ tags: - plugin/emitter --- -This plugin is a core component of the Quartz framework. It generates the HTML pages for each piece of Markdown content. It creates the full-page layout, including headers, footers, and body content, among others. \ No newline at end of file +This plugin is a core component of the Quartz framework. It generates the HTML pages for each piece of Markdown content. It creates the full-page layout, including headers, footers, and body content, among others. + +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.ContentPage()`. +- Source: [`quartz/plugins/emitters/contentPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/contentPage.tsx). diff --git a/docs/plugins/CrawlLinks.md b/docs/plugins/CrawlLinks.md index 8e297d6c39d65..13da048811e39 100644 --- a/docs/plugins/CrawlLinks.md +++ b/docs/plugins/CrawlLinks.md @@ -6,10 +6,23 @@ tags: This plugin parses links and processes them to point to the right places. It is also needed for embedded links (like images). -- To remove link processing, remove, delete all usages of `Plugin.CrawlLinks()` from `quartz.config.ts`. This is _not_ recommended and will likely break the page. -- To customize link processing, use the configuration options of the plugin: - - `markdownLinkResolution`: Defines the strategy for resolving Markdown paths, can be `"absolute"` (default), `"relative"` or `"shortest"`. - - `prettyLinks`: When `true` (default), simplifies links by removing folder paths, making them more user-friendly. - - `openLinksInNewTab`: When `true`, configures external links to open in a new tab. Defaults to `false`. - - `lazyLoad`: When `true`, adds lazy loading to resource elements (`img`, `video`, etc.) to improve page load performance. Defaults to `false`. - - `externalLinkIcon`: Adds an icon next to external links when `true` (default) to visually distinguishing them from internal links. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `markdownLinkResolution`: Defines the strategy for resolving Markdown paths, can be `"absolute"` (default), `"relative"` or `"shortest"`. +- `prettyLinks`: When `true` (default), simplifies links by removing folder paths, making them more user-friendly. +- `openLinksInNewTab`: When `true`, configures external links to open in a new tab. Defaults to `false`. +- `lazyLoad`: When `true`, adds lazy loading to resource elements (`img`, `video`, etc.) to improve page load performance. Defaults to `false`. +- `externalLinkIcon`: Adds an icon next to external links when `true` (default) to visually distinguishing them from internal links. + +> [!warning] +> Removing this plugin is _not_ recommended and will likely break the page. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.CrawlLinks()`. +- Source: [`quartz/plugins/transformers/links.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/links.ts). + diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index 608affc2cf183..1684411848b12 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -4,10 +4,20 @@ tags: - plugin/transformer --- -This plugin determines the created, modified, and published dates for a document using three potential data sources: front matter metadata, Git history, and the filesystem. See [[authoring content#Syntax]] for more information. +This plugin determines the created, modified, and published dates for a document using three potential data sources: frontmatter metadata, Git history, and the filesystem. See [[authoring content#Syntax]] for more information. -- To remove dates from all pages, delete all usages of `Plugin.CreatedModifiedDate()` from `quartz.config.ts`. -- To customize date parsing, use the configuration options of the plugin: - - `priority`: The data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. -The source of this plugin can be found in [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). +This plugin accepts the following configuration options: + +- `priority`: The data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. + +> [!warning] +> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.CreatedModifiedDate()`. +- Source: [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). \ No newline at end of file diff --git a/docs/plugins/Description.md b/docs/plugins/Description.md index 836956bd5d170..e89bde1bbb70c 100644 --- a/docs/plugins/Description.md +++ b/docs/plugins/Description.md @@ -12,6 +12,19 @@ This plugin generates descriptions that are used in various places: If the frontmatter contains a `description` property, it is used (see [[authoring content#Syntax]]). Otherwise, the full text of the file is used. -- To remove descriptions, delete all usages of `Plugin.Description()` from `quartz.config.ts`. -- To customize description generation, use the configuration options of the plugin: - - `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length. + +> [!warning] +> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.Description()`. +- Source: [`quartz/plugins/transformers/description.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/description.ts). + diff --git a/docs/plugins/ExplicitPublish.md b/docs/plugins/ExplicitPublish.md index 8eba4eecb9267..d44d378c1248a 100644 --- a/docs/plugins/ExplicitPublish.md +++ b/docs/plugins/ExplicitPublish.md @@ -6,4 +6,13 @@ tags: This plugin filters content based on an explicit `publish` flag in the frontmatter, allowing only content that is explicitly marked for publication (set to `true`) to pass through. It's kind of the opposite of [[RemoveDrafts]]. -- To add this functionality, add `Plugin.ExplicitPublish()` to the `filters` section of `quartz.config.ts`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.ExplicitPublish()`. +- Source: [`quartz/plugins/filters/explicit.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/filters/explicit.ts). diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md index eb4a9dab13258..edde846d05f4b 100644 --- a/docs/plugins/FolderPage.md +++ b/docs/plugins/FolderPage.md @@ -6,4 +6,15 @@ tags: This plugin generates index pages for folders, creating a listing page for each folder that contains multiple content files. -Example: \ No newline at end of file +Example: [[folder/advanced]] + +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.FolderPage()`. +- Source: [`quartz/plugins/emitters/folderPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/folderPage.tsx). diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md index efcb415852647..8de73ed294ce9 100644 --- a/docs/plugins/Frontmatter.md +++ b/docs/plugins/Frontmatter.md @@ -6,9 +6,20 @@ tags: This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. See [[authoring content#Syntax]] for more information. -- This plugin (`Plugin.Frontmatter()`) should not be removed from `quartz.config.ts`, otherwise Quartz will break. -- To customize frontmatter parsing, use the configuration options of the plugin: - - `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. - - `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`. +- `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`. + +> [!warning] +> This plugin must not be removed, otherwise Quartz will break. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.Frontmatter()`. +- Source: [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts). -The source of this plugin can be found in [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts). diff --git a/docs/plugins/GitHubFlavoredMarkdown.md b/docs/plugins/GitHubFlavoredMarkdown.md index 9a7ef0e1163b4..8d6128cff493c 100644 --- a/docs/plugins/GitHubFlavoredMarkdown.md +++ b/docs/plugins/GitHubFlavoredMarkdown.md @@ -8,7 +8,17 @@ This plugin enhances Markdown processing to support GitHub Flavored Markdown (GF In addition, this plugin adds optional features for typographic refinement (such as converting straight quotes to curly quotes, dashes to en-dashes/em-dashes, and ellipses) and automatic heading links as a symbol that appears next to the heading on hover. +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: -- To remove recognizing the GitHub Markdown style, delete all usages of `Plugin.GitHubFlavoredMarkdown()` from `quartz.config.ts`. - `enableSmartyPants`: When true, enables typographic enhancements. Default is true. -- `linkHeadings`: When true, automatically adds links to headings. Default is true. \ No newline at end of file +- `linkHeadings`: When true, automatically adds links to headings. Default is true. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.GitHubFlavoredMarkdown()`. +- Source: [`quartz/plugins/transformers/gfm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/gfm.ts). + diff --git a/docs/plugins/HardLineBreaks.md b/docs/plugins/HardLineBreaks.md index bca0f2024fa59..1a05b6d0c008c 100644 --- a/docs/plugins/HardLineBreaks.md +++ b/docs/plugins/HardLineBreaks.md @@ -6,4 +6,13 @@ tags: This plugin automatically converts single line breaks in Markdown text into hard line breaks in the HTML output. This plugin is not enabled by default. -- To add this functionality, add `Plugin.HardLineBreaks()` to the `transformers` section of `quartz.config.ts`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.HardLineBreaks()`. +- Source: [`quartz/plugins/transformers/linebreaks.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/linebreaks.ts). diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md index e7910a180bf6d..28b5376f69844 100644 --- a/docs/plugins/Latex.md +++ b/docs/plugins/Latex.md @@ -6,8 +6,15 @@ tags: This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more information. -- To remove Latex support, delete all usages of `Plugin.Latex()` from `quartz.config.ts`. -- To customize Latex support, use the configuration options of the plugin: +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. -The source of this plugin can be found in [`quartz/plugins/transformers/latex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/latex.ts). +## Technical Details + +- Category: Transformer +- Function name: `Plugin.Latex()`. +- Source: [`quartz/plugins/transformers/latex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/latex.ts). diff --git a/docs/plugins/NotFoundPage.md b/docs/plugins/NotFoundPage.md index 45e5abea01c48..70595eae91e0f 100644 --- a/docs/plugins/NotFoundPage.md +++ b/docs/plugins/NotFoundPage.md @@ -6,4 +6,13 @@ tags: This plugin is designed to generate a custom 404 (Not Found) page for the website to handle broken or non-existent URLs. -- To remove this functionality, delete all usages of `Plugin.NotFoundPage()` from `quartz.config.ts`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.NotFoundPage()`. +- Source: [`quartz/plugins/emitters/404.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/404.tsx). diff --git a/docs/plugins/ObsidianFlavoredMarkdown.md b/docs/plugins/ObsidianFlavoredMarkdown.md index 7e8bd7ed95255..c35c8bd3748a0 100644 --- a/docs/plugins/ObsidianFlavoredMarkdown.md +++ b/docs/plugins/ObsidianFlavoredMarkdown.md @@ -6,17 +6,30 @@ tags: This plugin extends Markdown processing to include features commonly used in Obsidian, such as enhanced link handling, callouts, mermaid diagrams, checkboxes, and more. -- To ignore Obsidian specific markdown parsing, delete all usages of `Plugin.ObsidianFlavoredMarkdown()` from `quartz.config.ts`. Don't do this if you're using Obsidian to author the content! -- To customize markdown parsing, use the configuration options of the plugin: - - `comments`: When `true` (default), enables parsing of comment blocks. - - `highlight`: When `true` (default), highlights text within content. - - `wikilinks`:When `true` (default), adds wikilink support. - - `callouts`: When `true` (default), adds support for callout blocks for emphasizing content. - - `mermaid`: When `true` (default), enables Mermaid diagram rendering within Markdown files. - - `parseTags`: When `true` (default), parses and links tags within the content. - - `parseArrows`: When `true` (default), transforms arrow symbols into their HTML character equivalents. - - `parseBlockReferences`: When `true` (default), handles block references, linking to specific content blocks. - - `enableInHtmlEmbed`: When `true`, allows embedding of content directly within HTML. Defaults to `false`. - - `enableYouTubeEmbed`: When `true` (default), enables the embedding of YouTube videos. - - `enableVideoEmbed`: When `true` (default), enables the embedding of video files. - - `enableCheckbox`: When `true`, adds support for interactive checkboxes in content. Defaults to `false`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `comments`: When `true` (default), enables parsing of comment blocks. +- `highlight`: When `true` (default), highlights text within content. +- `wikilinks`:When `true` (default), adds wikilink support. +- `callouts`: When `true` (default), adds support for callout blocks for emphasizing content. +- `mermaid`: When `true` (default), enables Mermaid diagram rendering within Markdown files. +- `parseTags`: When `true` (default), parses and links tags within the content. +- `parseArrows`: When `true` (default), transforms arrow symbols into their HTML character equivalents. +- `parseBlockReferences`: When `true` (default), handles block references, linking to specific content blocks. +- `enableInHtmlEmbed`: When `true`, allows embedding of content directly within HTML. Defaults to `false`. +- `enableYouTubeEmbed`: When `true` (default), enables the embedding of YouTube videos. +- `enableVideoEmbed`: When `true` (default), enables the embedding of video files. +- `enableCheckbox`: When `true`, adds support for interactive checkboxes in content. Defaults to `false`. + +> [!warning] +> Don't remove this plugin if you're using Obsidian to author the content! + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.ObsidianFlavoredMarkdown()`. +- Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts). + diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md index df70559e6645d..d85b09c7e3d8c 100644 --- a/docs/plugins/OxHugoFlavoredMarkdown.md +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -4,12 +4,22 @@ tags: - plugin/transformer --- -This plugin modifies Markdown content generated by [ox-hugo](https://github.com/kaushalmodi/ox-hugo) to make it compatible with Quartz, addressing specific formatting and syntax issues. See [[OxHugo compatibility]] for more information. This plugin is not enabled by default. - -- To add this functionality, add `Plugin.OxHugoFlavoredMarkdown()` to the `transformers` section of `quartz.config.ts`. -- To customize, use the configuration options of the plugin: - - `wikilinks`: When `true` (default), converts Hugo `relref` shortcodes to Quartz wikilinks. - - `removePredefinedAnchor`: When `true` (default), strips predefined anchors from headings. - - `removeHugoShortcode`: When `true` (default), removes Hugo shortcode syntax from the content. - - `replaceFigureWithMdImg`: When `true` (default), transforms `
` HTML tags into Markdown image syntax. - - `replaceOrgLatex`: When `true` (default), converts Org-mode LaTeX fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations). \ No newline at end of file +This plugin modifies Markdown content generated by [ox-hugo](https://github.com/kaushalmodi/ox-hugo) to make it compatible with Quartz, addressing specific formatting and syntax issues. See [[OxHugo compatibility]] for more information. + +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `wikilinks`: When `true` (default), converts Hugo `relref` shortcodes to Quartz wikilinks. +- `removePredefinedAnchor`: When `true` (default), strips predefined anchors from headings. +- `removeHugoShortcode`: When `true` (default), removes Hugo shortcode syntax from the content. +- `replaceFigureWithMdImg`: When `true` (default), transforms `
` HTML tags into Markdown image syntax. +- `replaceOrgLatex`: When `true` (default), converts Org-mode LaTeX fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations). + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.OxHugoFlavoredMarkdown()`. +- Source: [`quartz/plugins/transformers/oxhugofm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/oxhugofm.ts). + diff --git a/docs/plugins/RemoveDrafts.md b/docs/plugins/RemoveDrafts.md index b9420796775b0..433ba35582165 100644 --- a/docs/plugins/RemoveDrafts.md +++ b/docs/plugins/RemoveDrafts.md @@ -6,4 +6,13 @@ tags: This plugin is designed to filter out draft content from the publishing pipeline, so only finalized content is made available. It operates by checking the `draft` flag in the frontmatter of each file. When it's set to `true`, the content is filtered out. -- To disable this functionality, delete all usages of `Plugin.RemoveDrafts()` from `quartz.config.ts`. \ No newline at end of file +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Filter +- Function name: `Plugin.RemoveDrafts()`. +- Source: [`quartz/plugins/filters/draft.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/filters/draft.ts). diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md index 066deed93ff89..01ea5f410b330 100644 --- a/docs/plugins/Static.md +++ b/docs/plugins/Static.md @@ -4,4 +4,15 @@ tags: - plugin/emitter --- -This plugin handles the static assets. It ensures that all necessary static files, such as images, scripts, and stylesheets, are included in the final build, ready for deployment. \ No newline at end of file +This plugin handles the static assets. It ensures that all necessary static files, such as images, scripts, and stylesheets, are included in the final build, ready for deployment. + +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.Static()`. +- Source: [`quartz/plugins/emitters/static.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/static.ts). diff --git a/docs/plugins/SyntaxHighlighting.md b/docs/plugins/SyntaxHighlighting.md index 398568633e76c..b380911871798 100644 --- a/docs/plugins/SyntaxHighlighting.md +++ b/docs/plugins/SyntaxHighlighting.md @@ -6,10 +6,19 @@ tags: This plugin is used to add syntax highlighting to code blocks in Quartz. See [[syntax highlighting]] for more information. -- To remove syntax highlighting, delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`. -- To customize syntax highlighting, use the configuration options of the plugin: - - `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. - - `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. -- In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `theme`: a separate id of one of the [themes bundled with Shikiji](https://shikiji.netlify.app/themes). One for light mode and one for dark mode. Defaults to `theme: { light: "github-light", dark: "github-dark" }`. +- `keepBackground`: If set to `true`, the background of the Shikiji theme will be used. With `false` (default) the Quartz theme color for background will be used instead. + +In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.SyntaxHighlighting()`. +- Source: [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts). -The source of this plugin can be found in [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts). diff --git a/docs/plugins/TableOfContents.md b/docs/plugins/TableOfContents.md index 1a07278e8379d..466e09da85e4b 100644 --- a/docs/plugins/TableOfContents.md +++ b/docs/plugins/TableOfContents.md @@ -4,11 +4,24 @@ tags: - plugin/transformer --- -This plugin generates a Table of Contents (TOC) for Markdown documents. By default it is displayed in the right side bar. - -- To remove the TOC from all pages, delete all usages of `Plugin.TableOfContents()` from `quartz.config.ts`. -- To configure the TOC, use the configuration options of the plugin: - - `maxDepth`: Limits the depth of headings included in the TOC, ranging from `1` (top-level headings only) to `6` (all heading levels). Default is `3`. - - `minEntries`: The minimum number of heading entries required for the TOC to be displayed. Default is `1`. - - `showByDefault`: When `true` (default), the TOC should be shown by default. Can be overridden by frontmatter settings. - - `collapseByDefault`: When `true` the TOC starts in a collapsed state. Default is `false`. \ No newline at end of file +This plugin generates a table of contents (TOC) for Markdown documents. By default it is displayed in the right sidebar. See [[table of contents]] for more information. + +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin accepts the following configuration options: + +- `maxDepth`: Limits the depth of headings included in the TOC, ranging from `1` (top level headings only) to `6` (all heading levels). Default is `3`. +- `minEntries`: The minimum number of heading entries required for the TOC to be displayed. Default is `1`. +- `showByDefault`: If `true` (default), the TOC should be displayed by default. Can be overridden by frontmatter settings. +- `collapseByDefault`: If `true`, the TOC will start in a collapsed state. Default is `false`. + +> [!warning] +> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. + +## Technical Details + +- Category: Transformer +- Function name: `Plugin.TableOfContents()`. +- Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts). + diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md index 258531feff2c7..758dfab898c89 100644 --- a/docs/plugins/TagPage.md +++ b/docs/plugins/TagPage.md @@ -4,4 +4,15 @@ tags: - plugin/emitter --- -This plugin creates dedicated pages for each tag used in the content. \ No newline at end of file +This plugin creates dedicated pages for each tag used in the content. + +> [!note] +> For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. + +This plugin has no configuration options. + +## Technical Details + +- Category: Emitter +- Function name: `Plugin.AliasRedirects()`. +- Source: [`quartz/plugins/emitters/tagPage.tsx`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/tagPage.tsx). From 23a00112d637f23ea30046301610e17aa858230c Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 12:55:55 +0100 Subject: [PATCH 19/38] docs: update configuration page --- docs/configuration.md | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 42dd1174d120b..72ab3154287f5 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -56,7 +56,7 @@ 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: [...], @@ -64,24 +64,40 @@ plugins: { } ``` -- [[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 customise 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. + +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 title="quartz.config.ts" +transformers: [ + ... + 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. -Additionally, plugins may also have their own configuration settings that you can pass in. For example, the [[plugins/Latex|Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose between Katex and MathJax. 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 +```ts title="quartz.config.ts" transformers: [ - Plugin.FrontMatter(), // uses default options - Plugin.Latex({ renderEngine: "katex" }), // specify some options + Plugin.FrontMatter(), // use default options + Plugin.Latex({ renderEngine: "katex" }), // set some custom options ] ``` -The current default plugins can be found [here](https://github.com/jackyzha0/quartz/blob/v4/quartz.config.ts). For a list of all plugins and the available configuration options, visit the [[plugin]] tag overview. +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, read the guide on [[making plugins|making custom plugins]] for more information. +If you'd like to make your own plugins, see the [[making plugins|making custom plugins]] guide. From de8d32ef38285f4f25caf305c19ef5a896e47e87 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 13:36:45 +0100 Subject: [PATCH 20/38] docs: more plugin work --- docs/features/Latex.md | 4 ---- docs/features/Mermaid diagrams.md | 2 +- docs/features/Obsidian compatibility.md | 25 ++++------------------- docs/features/OxHugo compatibility.md | 15 ++------------ docs/features/RSS Feed.md | 4 +--- docs/features/callouts.md | 7 ++++--- docs/features/folder and tag listings.md | 5 +---- docs/features/private pages.md | 4 ++-- docs/features/table of contents.md | 17 ++++------------ docs/features/wikilinks.md | 2 +- docs/plugins/CrawlLinks.md | 2 +- docs/plugins/ExplicitPublish.md | 2 +- docs/plugins/FolderPage.md | 4 +++- docs/plugins/Frontmatter.md | 2 +- docs/plugins/Latex.md | 2 +- docs/plugins/ObsidianFlavoredMarkdown.md | 26 ++++++++++++------------ docs/plugins/OxHugoFlavoredMarkdown.md | 15 ++++++++++---- docs/plugins/RemoveDrafts.md | 2 +- docs/plugins/TableOfContents.md | 2 +- docs/plugins/TagPage.md | 4 +++- 20 files changed, 56 insertions(+), 90 deletions(-) diff --git a/docs/features/Latex.md b/docs/features/Latex.md index 6e1c59fbb41ae..a701c0ddb35a8 100644 --- a/docs/features/Latex.md +++ b/docs/features/Latex.md @@ -54,10 +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 Latex parsing is a functionality of the [[plugins/Latex|Latex]] plugin. See the plugin page for customization options. diff --git a/docs/features/Mermaid diagrams.md b/docs/features/Mermaid diagrams.md index c247518d9cfda..fe96416fe63db 100644 --- a/docs/features/Mermaid diagrams.md +++ b/docs/features/Mermaid diagrams.md @@ -7,7 +7,7 @@ Quartz supports Mermaid which allows you to add diagrams and charts to your note 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 diff --git a/docs/features/Obsidian compatibility.md b/docs/features/Obsidian compatibility.md index 04a1d63de9fc3..e469f48665975 100644 --- a/docs/features/Obsidian compatibility.md +++ b/docs/features/Obsidian compatibility.md @@ -6,29 +6,12 @@ tags: 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. diff --git a/docs/features/OxHugo compatibility.md b/docs/features/OxHugo compatibility.md index e8e8331b40a63..e220511467e2b 100644 --- a/docs/features/OxHugo compatibility.md +++ b/docs/features/OxHugo compatibility.md @@ -6,7 +6,7 @@ tags: [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: { @@ -26,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 `
` 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. diff --git a/docs/features/RSS Feed.md b/docs/features/RSS Feed.md index bfeb399c98fbd..b394ce8eaeccc 100644 --- a/docs/features/RSS Feed.md +++ b/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. diff --git a/docs/features/callouts.md b/docs/features/callouts.md index 5b1cb0ee7589f..fb7e1fb8b16a7 100644 --- a/docs/features/callouts.md +++ b/docs/features/callouts.md @@ -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 diff --git a/docs/features/folder and tag listings.md b/docs/features/folder and tag listings.md index 47d5f42732b95..11e3e520777ce 100644 --- a/docs/features/folder and tag listings.md +++ b/docs/features/folder and tag listings.md @@ -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. diff --git a/docs/features/private pages.md b/docs/features/private pages.md index 32f3a993ba15b..1e8f8aa24c90e 100644 --- a/docs/features/private pages.md +++ b/docs/features/private pages.md @@ -8,9 +8,9 @@ There may be some notes you want to avoid publishing as a website. Quartz suppor ## 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. diff --git a/docs/features/table of contents.md b/docs/features/table of contents.md index e5ab829b4046c..aeae84e7a17d9 100644 --- a/docs/features/table of contents.md +++ b/docs/features/table of contents.md @@ -7,20 +7,11 @@ tags: 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`. \ No newline at end of file diff --git a/docs/features/wikilinks.md b/docs/features/wikilinks.md index 1b005327c5b49..ad4f2d7798e31 100644 --- a/docs/features/wikilinks.md +++ b/docs/features/wikilinks.md @@ -4,7 +4,7 @@ title: Wikilinks Wikilinks were pioneered by earlier internet wikis to make it easier to write links across pages without needing to write Markdown or HTML links each time. -Quartz supports Wikilinks by default and these links are resolved by Quartz using `Plugin.CrawlLinks`. See the [Obsidian Help page on Internal Links](https://help.obsidian.md/Linking+notes+and+files/Internal+links) for more information on Wikilink syntax. +Quartz supports Wikilinks by default and these links are resolved by Quartz using the [[CrawlLinks]] plugin. See the [Obsidian Help page on Internal Links](https://help.obsidian.md/Linking+notes+and+files/Internal+links) for more information on Wikilink syntax. This is enabled as a part of [[Obsidian compatibility]] and can be configured and enabled/disabled from that plugin. diff --git a/docs/plugins/CrawlLinks.md b/docs/plugins/CrawlLinks.md index 13da048811e39..c8f56cc01dcf6 100644 --- a/docs/plugins/CrawlLinks.md +++ b/docs/plugins/CrawlLinks.md @@ -4,7 +4,7 @@ tags: - plugin/transformer --- -This plugin parses links and processes them to point to the right places. It is also needed for embedded links (like images). +This plugin parses links and processes them to point to the right places. It is also needed for embedded links (like images). See [[Obsidian compatibility]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/ExplicitPublish.md b/docs/plugins/ExplicitPublish.md index d44d378c1248a..cb74f9c2e8278 100644 --- a/docs/plugins/ExplicitPublish.md +++ b/docs/plugins/ExplicitPublish.md @@ -4,7 +4,7 @@ tags: - plugin/filter --- -This plugin filters content based on an explicit `publish` flag in the frontmatter, allowing only content that is explicitly marked for publication (set to `true`) to pass through. It's kind of the opposite of [[RemoveDrafts]]. +This plugin filters content based on an explicit `publish` flag in the frontmatter, allowing only content that is explicitly marked for publication to pass through. It's the opt-in version of [[RemoveDrafts]]. See [[private pages]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md index edde846d05f4b..1cac6c85674c2 100644 --- a/docs/plugins/FolderPage.md +++ b/docs/plugins/FolderPage.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin generates index pages for folders, creating a listing page for each folder that contains multiple content files. +This plugin generates index pages for folders, creating a listing page for each folder that contains multiple content files. See [[folder and tag listings]] for more information. Example: [[folder/advanced]] @@ -13,6 +13,8 @@ Example: [[folder/advanced]] This plugin has no configuration options. +The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `FolderContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/FolderContent.tsx`). + ## Technical Details - Category: Emitter diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md index 8de73ed294ce9..48b68684d2818 100644 --- a/docs/plugins/Frontmatter.md +++ b/docs/plugins/Frontmatter.md @@ -4,7 +4,7 @@ tags: - plugin/transformer --- -This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. See [[authoring content#Syntax]] for more information. +This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. See [[authoring content#Syntax]], [[Obsidian compatibility]] and [[OxHugo compatibility]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md index 28b5376f69844..2e5a5c2a2f82b 100644 --- a/docs/plugins/Latex.md +++ b/docs/plugins/Latex.md @@ -11,7 +11,7 @@ This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more This plugin accepts the following configuration options: - - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for MathJax. Defaults to KaTeX. + - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX. ## Technical Details diff --git a/docs/plugins/ObsidianFlavoredMarkdown.md b/docs/plugins/ObsidianFlavoredMarkdown.md index c35c8bd3748a0..accce8b1b23b9 100644 --- a/docs/plugins/ObsidianFlavoredMarkdown.md +++ b/docs/plugins/ObsidianFlavoredMarkdown.md @@ -4,25 +4,25 @@ tags: - plugin/transformer --- -This plugin extends Markdown processing to include features commonly used in Obsidian, such as enhanced link handling, callouts, mermaid diagrams, checkboxes, and more. +This plugin extends Markdown processing to include features commonly used in Obsidian, such as enhanced link handling, callouts, mermaid diagrams, checkboxes, and more. See [[Obsidian compatibility]], [[wikilinks]], [[Mermaid diagrams]] and [[callouts]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. This plugin accepts the following configuration options: -- `comments`: When `true` (default), enables parsing of comment blocks. -- `highlight`: When `true` (default), highlights text within content. -- `wikilinks`:When `true` (default), adds wikilink support. -- `callouts`: When `true` (default), adds support for callout blocks for emphasizing content. -- `mermaid`: When `true` (default), enables Mermaid diagram rendering within Markdown files. -- `parseTags`: When `true` (default), parses and links tags within the content. -- `parseArrows`: When `true` (default), transforms arrow symbols into their HTML character equivalents. -- `parseBlockReferences`: When `true` (default), handles block references, linking to specific content blocks. -- `enableInHtmlEmbed`: When `true`, allows embedding of content directly within HTML. Defaults to `false`. -- `enableYouTubeEmbed`: When `true` (default), enables the embedding of YouTube videos. -- `enableVideoEmbed`: When `true` (default), enables the embedding of video files. -- `enableCheckbox`: When `true`, adds support for interactive checkboxes in content. Defaults to `false`. +- `comments`: If `true` (default), enables parsing of `%%` style Obsidian comment blocks. +- `highlight`: If `true` (default), enables parsing of `==` style highlights within content. +- `wikilinks`:If `true` (default), turns [[wikilinks]] into regular links. +- `callouts`: If `true` (default), adds support for [[callouts|callout]] blocks for emphasizing content. +- `mermaid`: If `true` (default), enables [[Mermaid diagrams|Mermaid diagram]] rendering within Markdown files. +- `parseTags`: If `true` (default), parses and links tags within the content. +- `parseArrows`: If `true` (default), transforms arrow symbols into their HTML character equivalents. +- `parseBlockReferences`: If `true` (default), handles block references, linking to specific content blocks. +- `enableInHtmlEmbed`: If `true`, allows embedding of content directly within HTML. Defaults to `false`. +- `enableYouTubeEmbed`: If `true` (default), enables the embedding of YouTube videos using external image Markdown syntax. +- `enableVideoEmbed`: If `true` (default), enables the embedding of video files. +- `enableCheckbox`: If `true`, adds support for interactive checkboxes in content. Defaults to `false`. > [!warning] > Don't remove this plugin if you're using Obsidian to author the content! diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md index d85b09c7e3d8c..20d70df3f7a50 100644 --- a/docs/plugins/OxHugoFlavoredMarkdown.md +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -11,11 +11,18 @@ This plugin modifies Markdown content generated by [ox-hugo](https://github.com/ This plugin accepts the following configuration options: -- `wikilinks`: When `true` (default), converts Hugo `relref` shortcodes to Quartz wikilinks. +- `wikilinks`: When `true` (default), converts Hugo `{{ relref }}` shortcodes to Quartz [[wikilinks]]. - `removePredefinedAnchor`: When `true` (default), strips predefined anchors from headings. -- `removeHugoShortcode`: When `true` (default), removes Hugo shortcode syntax from the content. -- `replaceFigureWithMdImg`: When `true` (default), transforms `
` HTML tags into Markdown image syntax. -- `replaceOrgLatex`: When `true` (default), converts Org-mode LaTeX fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations). +- `removeHugoShortcode`: When `true` (default), removes Hugo shortcode syntax (`{{}}`) from the content. +- `replaceFigureWithMdImg`: When `true` (default), replaces `
` with `![]()`. +- `replaceOrgLatex`: When `true` (default), converts Org-mode [[features/Latex|Latex]] fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations). + +> [!warning] +> While you can use this together with [[ObsidianFlavoredMarkdown]], it's not recommended because it might mutate the file in unexpected ways. Use with caution. + +> [!warning] +> If you use toml frontmatter, make sure to configure the [[Frontmatter]] plugin accordingly. See [[OxHugo compatibility]] for an example. + ## Technical Details diff --git a/docs/plugins/RemoveDrafts.md b/docs/plugins/RemoveDrafts.md index 433ba35582165..ca7320128a8da 100644 --- a/docs/plugins/RemoveDrafts.md +++ b/docs/plugins/RemoveDrafts.md @@ -4,7 +4,7 @@ tags: - plugin/filter --- -This plugin is designed to filter out draft content from the publishing pipeline, so only finalized content is made available. It operates by checking the `draft` flag in the frontmatter of each file. When it's set to `true`, the content is filtered out. +This plugin is designed to filter out draft content from the publishing pipeline, so only finalized content is made available. It operates by checking the `draft` flag in the frontmatter of each file. See [[private pages]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/TableOfContents.md b/docs/plugins/TableOfContents.md index 466e09da85e4b..ea613cc1af673 100644 --- a/docs/plugins/TableOfContents.md +++ b/docs/plugins/TableOfContents.md @@ -17,7 +17,7 @@ This plugin accepts the following configuration options: - `collapseByDefault`: If `true`, the TOC will start in a collapsed state. Default is `false`. > [!warning] -> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. +> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. They should always be added or removed together. ## Technical Details diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md index 758dfab898c89..c06bfe31f87ad 100644 --- a/docs/plugins/TagPage.md +++ b/docs/plugins/TagPage.md @@ -4,13 +4,15 @@ tags: - plugin/emitter --- -This plugin creates dedicated pages for each tag used in the content. +This plugin creates dedicated pages for each tag used in the content. See [[folder and tag listings]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. This plugin has no configuration options. +The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `TagContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/TagContent.tsx`). + ## Technical Details - Category: Emitter From 6cd13d52bd59ef8c9a438e81938cc8deaf53a318 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 13:37:16 +0100 Subject: [PATCH 21/38] docs: run prettier --- docs/configuration.md | 2 +- docs/features/table of contents.md | 4 ++-- docs/plugins/ContentIndex.md | 1 - docs/plugins/CrawlLinks.md | 1 - docs/plugins/CreatedModifiedDate.md | 2 +- docs/plugins/Description.md | 4 ++-- docs/plugins/FolderPage.md | 2 +- docs/plugins/Frontmatter.md | 1 - docs/plugins/GitHubFlavoredMarkdown.md | 1 - docs/plugins/Latex.md | 2 +- docs/plugins/ObsidianFlavoredMarkdown.md | 3 +-- docs/plugins/OxHugoFlavoredMarkdown.md | 2 -- docs/plugins/SyntaxHighlighting.md | 1 - docs/plugins/TableOfContents.md | 1 - docs/plugins/TagPage.md | 2 +- 15 files changed, 10 insertions(+), 19 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 72ab3154287f5..9c5830adfa64d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -87,7 +87,7 @@ 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. +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: [ diff --git a/docs/features/table of contents.md b/docs/features/table of contents.md index aeae84e7a17d9..677cb243ca8c3 100644 --- a/docs/features/table of contents.md +++ b/docs/features/table of contents.md @@ -2,7 +2,7 @@ title: "Table of Contents" tags: - component - - feature/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. @@ -14,4 +14,4 @@ You can also hide the table of contents on a page by adding `enableToc: false` t 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`. \ No newline at end of file +It also needs the `TableOfContents` component. The component can be configured with the `layout` parameter, which can either be `modern` (default) or `legacy`. diff --git a/docs/plugins/ContentIndex.md b/docs/plugins/ContentIndex.md index fe4883120609f..6d3d8359400aa 100644 --- a/docs/plugins/ContentIndex.md +++ b/docs/plugins/ContentIndex.md @@ -22,4 +22,3 @@ This plugin accepts the following configuration options: - Category: Emitter - Function name: `Plugin.ContentIndex()`. - Source: [`quartz/plugins/emitters/contentIndex.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/emitters/contentIndex.ts). - diff --git a/docs/plugins/CrawlLinks.md b/docs/plugins/CrawlLinks.md index c8f56cc01dcf6..b4e5a13ffedef 100644 --- a/docs/plugins/CrawlLinks.md +++ b/docs/plugins/CrawlLinks.md @@ -25,4 +25,3 @@ This plugin accepts the following configuration options: - Category: Transformer - Function name: `Plugin.CrawlLinks()`. - Source: [`quartz/plugins/transformers/links.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/links.ts). - diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index 1684411848b12..730041a608f8b 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -20,4 +20,4 @@ This plugin accepts the following configuration options: - Category: Transformer - Function name: `Plugin.CreatedModifiedDate()`. -- Source: [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). \ No newline at end of file +- Source: [`quartz/plugins/transformers/lastmod.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/lastmod.ts). diff --git a/docs/plugins/Description.md b/docs/plugins/Description.md index e89bde1bbb70c..b4ef9f284f0b1 100644 --- a/docs/plugins/Description.md +++ b/docs/plugins/Description.md @@ -5,12 +5,13 @@ tags: --- This plugin generates descriptions that are used in various places: + - as metadata for the HTML `head` - in FolderContent.tsx (TODO: What does it do there?) - in TagContent.tsx (TODO: What does it do there?) - in contentIndex.ts (TODO: What does it do there?) -If the frontmatter contains a `description` property, it is used (see [[authoring content#Syntax]]). Otherwise, the full text of the file is used. +If the frontmatter contains a `description` property, it is used (see [[authoring content#Syntax]]). Otherwise, the full text of the file is used. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. @@ -27,4 +28,3 @@ This plugin accepts the following configuration options: - Category: Transformer - Function name: `Plugin.Description()`. - Source: [`quartz/plugins/transformers/description.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/description.ts). - diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md index 1cac6c85674c2..03d7b27503062 100644 --- a/docs/plugins/FolderPage.md +++ b/docs/plugins/FolderPage.md @@ -13,7 +13,7 @@ Example: [[folder/advanced]] This plugin has no configuration options. -The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `FolderContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/FolderContent.tsx`). +The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `FolderContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/FolderContent.tsx`). ## Technical Details diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md index 48b68684d2818..36a5900a08bde 100644 --- a/docs/plugins/Frontmatter.md +++ b/docs/plugins/Frontmatter.md @@ -22,4 +22,3 @@ This plugin accepts the following configuration options: - Category: Transformer - Function name: `Plugin.Frontmatter()`. - Source: [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/frontmatter.ts). - diff --git a/docs/plugins/GitHubFlavoredMarkdown.md b/docs/plugins/GitHubFlavoredMarkdown.md index 8d6128cff493c..f819b1265f63d 100644 --- a/docs/plugins/GitHubFlavoredMarkdown.md +++ b/docs/plugins/GitHubFlavoredMarkdown.md @@ -21,4 +21,3 @@ This plugin accepts the following configuration options: - Category: Transformer - Function name: `Plugin.GitHubFlavoredMarkdown()`. - Source: [`quartz/plugins/transformers/gfm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/gfm.ts). - diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md index 2e5a5c2a2f82b..b5b8d0e4ccb33 100644 --- a/docs/plugins/Latex.md +++ b/docs/plugins/Latex.md @@ -11,7 +11,7 @@ This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more This plugin accepts the following configuration options: - - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX. +- `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX. ## Technical Details diff --git a/docs/plugins/ObsidianFlavoredMarkdown.md b/docs/plugins/ObsidianFlavoredMarkdown.md index accce8b1b23b9..3fa4a3d9805bf 100644 --- a/docs/plugins/ObsidianFlavoredMarkdown.md +++ b/docs/plugins/ObsidianFlavoredMarkdown.md @@ -11,7 +11,7 @@ This plugin extends Markdown processing to include features commonly used in Obs This plugin accepts the following configuration options: -- `comments`: If `true` (default), enables parsing of `%%` style Obsidian comment blocks. +- `comments`: If `true` (default), enables parsing of `%%` style Obsidian comment blocks. - `highlight`: If `true` (default), enables parsing of `==` style highlights within content. - `wikilinks`:If `true` (default), turns [[wikilinks]] into regular links. - `callouts`: If `true` (default), adds support for [[callouts|callout]] blocks for emphasizing content. @@ -32,4 +32,3 @@ This plugin accepts the following configuration options: - Category: Transformer - Function name: `Plugin.ObsidianFlavoredMarkdown()`. - Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts). - diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md index 20d70df3f7a50..c1db3d81751d7 100644 --- a/docs/plugins/OxHugoFlavoredMarkdown.md +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -23,10 +23,8 @@ This plugin accepts the following configuration options: > [!warning] > If you use toml frontmatter, make sure to configure the [[Frontmatter]] plugin accordingly. See [[OxHugo compatibility]] for an example. - ## Technical Details - Category: Transformer - Function name: `Plugin.OxHugoFlavoredMarkdown()`. - Source: [`quartz/plugins/transformers/oxhugofm.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/oxhugofm.ts). - diff --git a/docs/plugins/SyntaxHighlighting.md b/docs/plugins/SyntaxHighlighting.md index b380911871798..cc9dc5e34e7ac 100644 --- a/docs/plugins/SyntaxHighlighting.md +++ b/docs/plugins/SyntaxHighlighting.md @@ -21,4 +21,3 @@ In addition, you can further override the colours in the `quartz/styles/syntax.s - Category: Transformer - Function name: `Plugin.SyntaxHighlighting()`. - Source: [`quartz/plugins/transformers/syntax.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/syntax.ts). - diff --git a/docs/plugins/TableOfContents.md b/docs/plugins/TableOfContents.md index ea613cc1af673..1b93d5bf0235f 100644 --- a/docs/plugins/TableOfContents.md +++ b/docs/plugins/TableOfContents.md @@ -24,4 +24,3 @@ This plugin accepts the following configuration options: - Category: Transformer - Function name: `Plugin.TableOfContents()`. - Source: [`quartz/plugins/transformers/toc.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/toc.ts). - diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md index c06bfe31f87ad..ef96a6b0ce036 100644 --- a/docs/plugins/TagPage.md +++ b/docs/plugins/TagPage.md @@ -11,7 +11,7 @@ This plugin creates dedicated pages for each tag used in the content. See [[fold This plugin has no configuration options. -The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `TagContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/TagContent.tsx`). +The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `TagContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/TagContent.tsx`). ## Technical Details From 8d4dff36d923fd9c72c4562ca456bcb1017b95ff Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 15:14:41 +0100 Subject: [PATCH 22/38] docs: remove comments in config file and add link to docs --- quartz.config.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/quartz.config.ts b/quartz.config.ts index 8c479ac789a77..82a8ea4abbcbe 100644 --- a/quartz.config.ts +++ b/quartz.config.ts @@ -1,6 +1,11 @@ import { QuartzConfig } from "./quartz/cfg" import * as Plugin from "./quartz/plugins" +/** + * Quartz 4.0 Configuration + * + * See https://quartz.jzhao.xyz/configuration for more information. + */ const config: QuartzConfig = { configuration: { pageTitle: "🪴 Quartz 4.0", @@ -48,19 +53,14 @@ const config: QuartzConfig = { transformers: [ Plugin.FrontMatter(), Plugin.CreatedModifiedDate({ - // you can add 'git' here for last modified from Git - // if you do rely on git for dates, ensure defaultDateType is 'modified' priority: ["frontmatter", "filesystem"], }), Plugin.Latex({ renderEngine: "katex" }), Plugin.SyntaxHighlighting({ - // uses themes bundled with Shikiji, see https://shikiji.netlify.app/themes theme: { light: "github-light", dark: "github-dark", }, - // set this to 'true' to use the background color of the Shikiji theme - // if set to 'false', will use Quartz theme colors for background keepBackground: false, }), Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }), From 9a29c7cc38db3427ef0da8bc41306801bc4f1455 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 15:14:53 +0100 Subject: [PATCH 23/38] docs: minor fixes --- docs/plugins/CreatedModifiedDate.md | 2 +- docs/plugins/Description.md | 3 --- docs/plugins/ObsidianFlavoredMarkdown.md | 2 +- docs/plugins/OxHugoFlavoredMarkdown.md | 5 ++--- 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index 730041a608f8b..be62ccfe8d79a 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -14,7 +14,7 @@ This plugin accepts the following configuration options: - `priority`: The data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. > [!warning] -> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. +> If you rely on git for dates, ensure `defaultDateType` is set to `modified` in `quartz.config.ts`. ## Technical Details diff --git a/docs/plugins/Description.md b/docs/plugins/Description.md index b4ef9f284f0b1..c4815fed2f8c8 100644 --- a/docs/plugins/Description.md +++ b/docs/plugins/Description.md @@ -20,9 +20,6 @@ This plugin accepts the following configuration options: - `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length. -> [!warning] -> This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. - ## Technical Details - Category: Transformer diff --git a/docs/plugins/ObsidianFlavoredMarkdown.md b/docs/plugins/ObsidianFlavoredMarkdown.md index 3fa4a3d9805bf..689266b3ae903 100644 --- a/docs/plugins/ObsidianFlavoredMarkdown.md +++ b/docs/plugins/ObsidianFlavoredMarkdown.md @@ -25,7 +25,7 @@ This plugin accepts the following configuration options: - `enableCheckbox`: If `true`, adds support for interactive checkboxes in content. Defaults to `false`. > [!warning] -> Don't remove this plugin if you're using Obsidian to author the content! +> Don't remove this plugin if you're using [[Obsidian compatibility|Obsidian]] to author the content! ## Technical Details diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md index c1db3d81751d7..2cf466ccb7c18 100644 --- a/docs/plugins/OxHugoFlavoredMarkdown.md +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -19,9 +19,8 @@ This plugin accepts the following configuration options: > [!warning] > While you can use this together with [[ObsidianFlavoredMarkdown]], it's not recommended because it might mutate the file in unexpected ways. Use with caution. - -> [!warning] -> If you use toml frontmatter, make sure to configure the [[Frontmatter]] plugin accordingly. See [[OxHugo compatibility]] for an example. +> +> If you use `toml` frontmatter, make sure to configure the [[Frontmatter]] plugin accordingly. See [[OxHugo compatibility]] for an example. ## Technical Details From 04a36bad7582fe9921e6637a97862265160389e6 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 15:16:13 +0100 Subject: [PATCH 24/38] docs: run prettier --- quartz.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quartz.config.ts b/quartz.config.ts index 82a8ea4abbcbe..2cdadb740483e 100644 --- a/quartz.config.ts +++ b/quartz.config.ts @@ -3,7 +3,7 @@ import * as Plugin from "./quartz/plugins" /** * Quartz 4.0 Configuration - * + * * See https://quartz.jzhao.xyz/configuration for more information. */ const config: QuartzConfig = { From 08e7180186cfc8e56deec2ff705e6cd9fe68e267 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 16:07:04 +0100 Subject: [PATCH 25/38] docs: spelling --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 9c5830adfa64d..a3fcfcb5843c6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -68,7 +68,7 @@ plugins: { - [[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) -You can customise the behaviour of Quartz by adding, removing and reordering plugins in the `transformers`, `filters` and `emitters` fields. +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 pay particular attention to whether they need to come before or after certain other plugins. From f777836f3ddc4886d6a23043c752556ef0bcfcc5 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 16:28:51 +0100 Subject: [PATCH 26/38] docs: update docs/plugins/AliasRedirects.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> --- docs/plugins/AliasRedirects.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/plugins/AliasRedirects.md b/docs/plugins/AliasRedirects.md index 586c6ccfc1d56..793fac4c60f96 100644 --- a/docs/plugins/AliasRedirects.md +++ b/docs/plugins/AliasRedirects.md @@ -4,7 +4,27 @@ tags: - plugin/emitter --- -This plugin generates HTML redirect pages for aliases and permalinks defined in the frontmatter of content files, so that alternative paths correctly lead to the intended content. +This plugin creates HTML redirect pages for aliases and permalinks defined in the frontmatter of content files. + +For example, A `foo.md` has the following frontmatter + +```md title="foo.md" +--- +title: "Foo" +alias: + - "bar" +--- +``` + +The target `host.me/bar` will be redirected to `host.me/foo` + +Note that these are permanent redirect. + +The emitter supports the following aliases: + +- `aliases` +- `alias` + > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. From 665d03f48f3200b8cafdeb5768abca8c46aa4c60 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 16:29:20 +0100 Subject: [PATCH 27/38] docs: update docs/plugins/Assets.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> --- docs/plugins/Assets.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index 5c614ca06070f..1ff5201432930 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -4,7 +4,9 @@ tags: - plugin/emitter --- -This plugin manages and emits non-Markdown assets (like images, scripts, stylesheets, etc.) from the content directory to the output directory. It ensures that all required static assets are available in the generated site. +This plugin emits all non-Markdown static assets (like images, scripts, stylesheets, etc.) from your vault content under the directory `content`. + +Note that all static assets will then be accessible through its path on your generated site, i.e: `host.me/path/to/static.pdf` > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. From 2b3e38db7a8de02656afec41d62c8a84b41aea9a Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 16:29:39 +0100 Subject: [PATCH 28/38] docs: update docs/plugins/CNAME.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> --- docs/plugins/CNAME.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/plugins/CNAME.md b/docs/plugins/CNAME.md index 2a02828105931..055832b5653b2 100644 --- a/docs/plugins/CNAME.md +++ b/docs/plugins/CNAME.md @@ -4,7 +4,11 @@ tags: - plugin/emitter --- -This plugin generates a `CNAME` file as part of the site's output. This is needed for configuring custom domain names on platforms like GitHub Pages. The domain name is extracted from the site's base URL, which is then written to a `CNAME` file in the root of the output directory. +This plugin emits a `CNAME` record that points your subdomain to the default domain of your site. + +If you want to use a custom domain name `quartz.example.com` for the site, then this is needed. + +See [[Hosting]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. From 4d293a8832b7b639bf761faa7cd3d96be9fa823e Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 16:29:59 +0100 Subject: [PATCH 29/38] docs: update docs/plugins/Static.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> --- docs/plugins/Static.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md index 01ea5f410b330..ce5584b741442 100644 --- a/docs/plugins/Static.md +++ b/docs/plugins/Static.md @@ -4,7 +4,10 @@ tags: - plugin/emitter --- -This plugin handles the static assets. It ensures that all necessary static files, such as images, scripts, and stylesheets, are included in the final build, ready for deployment. +This plugin emits all static resources required by Quartz. + +> [!important] +> This is different from [[Assets]], as these static resources is located under `quartz/static`. Whereas [[Assets]] renders all static resources under `content`. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. From 67837400bc22d4a64a9aa5ccf4cea1ecd7eeb290 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 16:40:00 +0100 Subject: [PATCH 30/38] docs: update docs --- docs/plugins/AliasRedirects.md | 7 +++---- docs/plugins/Assets.md | 2 +- docs/plugins/CNAME.md | 4 ++-- docs/plugins/ComponentResources.md | 2 +- docs/plugins/ContentIndex.md | 2 +- docs/plugins/ContentPage.md | 2 +- docs/plugins/CrawlLinks.md | 2 +- docs/plugins/CreatedModifiedDate.md | 2 +- docs/plugins/Description.md | 2 +- docs/plugins/ExplicitPublish.md | 2 +- docs/plugins/FolderPage.md | 2 +- docs/plugins/Frontmatter.md | 2 +- docs/plugins/GitHubFlavoredMarkdown.md | 2 +- docs/plugins/HardLineBreaks.md | 2 +- docs/plugins/Latex.md | 2 +- docs/plugins/NotFoundPage.md | 4 ++-- docs/plugins/ObsidianFlavoredMarkdown.md | 4 ++-- docs/plugins/OxHugoFlavoredMarkdown.md | 4 ++-- docs/plugins/RemoveDrafts.md | 4 ++-- docs/plugins/Static.md | 2 +- docs/plugins/SyntaxHighlighting.md | 2 +- docs/plugins/TableOfContents.md | 2 +- docs/plugins/TagPage.md | 2 +- 23 files changed, 30 insertions(+), 31 deletions(-) diff --git a/docs/plugins/AliasRedirects.md b/docs/plugins/AliasRedirects.md index 793fac4c60f96..24e424f8fb1ca 100644 --- a/docs/plugins/AliasRedirects.md +++ b/docs/plugins/AliasRedirects.md @@ -11,8 +11,8 @@ For example, A `foo.md` has the following frontmatter ```md title="foo.md" --- title: "Foo" -alias: - - "bar" +alias: + - "bar" --- ``` @@ -25,13 +25,12 @@ The emitter supports the following aliases: - `aliases` - `alias` - > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.AliasRedirects()`. diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index 1ff5201432930..b225b965ffa6a 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -13,7 +13,7 @@ Note that all static assets will then be accessible through its path on your gen This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.Assets()`. diff --git a/docs/plugins/CNAME.md b/docs/plugins/CNAME.md index 055832b5653b2..a6bff0dba537a 100644 --- a/docs/plugins/CNAME.md +++ b/docs/plugins/CNAME.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin emits a `CNAME` record that points your subdomain to the default domain of your site. +This plugin emits a `CNAME` record that points your subdomain to the default domain of your site. If you want to use a custom domain name `quartz.example.com` for the site, then this is needed. @@ -15,7 +15,7 @@ See [[Hosting]] for more information. This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.CNAME()`. diff --git a/docs/plugins/ComponentResources.md b/docs/plugins/ComponentResources.md index dc5e7e25af343..01f3da4caf66a 100644 --- a/docs/plugins/ComponentResources.md +++ b/docs/plugins/ComponentResources.md @@ -11,7 +11,7 @@ This plugin manages and emits the static resources required for the Quartz frame This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.ComponentResources()`. diff --git a/docs/plugins/ContentIndex.md b/docs/plugins/ContentIndex.md index 6d3d8359400aa..49bfc88041677 100644 --- a/docs/plugins/ContentIndex.md +++ b/docs/plugins/ContentIndex.md @@ -17,7 +17,7 @@ This plugin accepts the following configuration options: - `rssFullHtml`: When `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries. - `includeEmptyFiles`: When `true` (default), content files with no body text are included in the generated index and resources. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.ContentIndex()`. diff --git a/docs/plugins/ContentPage.md b/docs/plugins/ContentPage.md index 83b4efe563761..9ea64e0878922 100644 --- a/docs/plugins/ContentPage.md +++ b/docs/plugins/ContentPage.md @@ -11,7 +11,7 @@ This plugin is a core component of the Quartz framework. It generates the HTML p This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.ContentPage()`. diff --git a/docs/plugins/CrawlLinks.md b/docs/plugins/CrawlLinks.md index b4e5a13ffedef..e20634ef10fa1 100644 --- a/docs/plugins/CrawlLinks.md +++ b/docs/plugins/CrawlLinks.md @@ -20,7 +20,7 @@ This plugin accepts the following configuration options: > [!warning] > Removing this plugin is _not_ recommended and will likely break the page. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.CrawlLinks()`. diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index be62ccfe8d79a..8eb9e4eff7596 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -16,7 +16,7 @@ This plugin accepts the following configuration options: > [!warning] > If you rely on git for dates, ensure `defaultDateType` is set to `modified` in `quartz.config.ts`. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.CreatedModifiedDate()`. diff --git a/docs/plugins/Description.md b/docs/plugins/Description.md index c4815fed2f8c8..67e33d3b83fa8 100644 --- a/docs/plugins/Description.md +++ b/docs/plugins/Description.md @@ -20,7 +20,7 @@ This plugin accepts the following configuration options: - `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.Description()`. diff --git a/docs/plugins/ExplicitPublish.md b/docs/plugins/ExplicitPublish.md index cb74f9c2e8278..7ef2dd4d02e21 100644 --- a/docs/plugins/ExplicitPublish.md +++ b/docs/plugins/ExplicitPublish.md @@ -11,7 +11,7 @@ This plugin filters content based on an explicit `publish` flag in the frontmatt This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.ExplicitPublish()`. diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md index 03d7b27503062..11c335bdca7c1 100644 --- a/docs/plugins/FolderPage.md +++ b/docs/plugins/FolderPage.md @@ -15,7 +15,7 @@ This plugin has no configuration options. The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `FolderContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/FolderContent.tsx`). -## Technical Details +## API - Category: Emitter - Function name: `Plugin.FolderPage()`. diff --git a/docs/plugins/Frontmatter.md b/docs/plugins/Frontmatter.md index 36a5900a08bde..960417a804721 100644 --- a/docs/plugins/Frontmatter.md +++ b/docs/plugins/Frontmatter.md @@ -17,7 +17,7 @@ This plugin accepts the following configuration options: > [!warning] > This plugin must not be removed, otherwise Quartz will break. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.Frontmatter()`. diff --git a/docs/plugins/GitHubFlavoredMarkdown.md b/docs/plugins/GitHubFlavoredMarkdown.md index f819b1265f63d..2ea8f8d38beab 100644 --- a/docs/plugins/GitHubFlavoredMarkdown.md +++ b/docs/plugins/GitHubFlavoredMarkdown.md @@ -16,7 +16,7 @@ This plugin accepts the following configuration options: - `enableSmartyPants`: When true, enables typographic enhancements. Default is true. - `linkHeadings`: When true, automatically adds links to headings. Default is true. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.GitHubFlavoredMarkdown()`. diff --git a/docs/plugins/HardLineBreaks.md b/docs/plugins/HardLineBreaks.md index 1a05b6d0c008c..cfc9700cb8f61 100644 --- a/docs/plugins/HardLineBreaks.md +++ b/docs/plugins/HardLineBreaks.md @@ -11,7 +11,7 @@ This plugin automatically converts single line breaks in Markdown text into hard This plugin has no configuration options. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.HardLineBreaks()`. diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md index b5b8d0e4ccb33..f886153f955c6 100644 --- a/docs/plugins/Latex.md +++ b/docs/plugins/Latex.md @@ -13,7 +13,7 @@ This plugin accepts the following configuration options: - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.Latex()`. diff --git a/docs/plugins/NotFoundPage.md b/docs/plugins/NotFoundPage.md index 70595eae91e0f..082f864252a65 100644 --- a/docs/plugins/NotFoundPage.md +++ b/docs/plugins/NotFoundPage.md @@ -4,14 +4,14 @@ tags: - plugin/emitter --- -This plugin is designed to generate a custom 404 (Not Found) page for the website to handle broken or non-existent URLs. +This plugin emits a 404 (Not Found) page for broken or non-existent URLs. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.NotFoundPage()`. diff --git a/docs/plugins/ObsidianFlavoredMarkdown.md b/docs/plugins/ObsidianFlavoredMarkdown.md index 689266b3ae903..7700a5cfb08af 100644 --- a/docs/plugins/ObsidianFlavoredMarkdown.md +++ b/docs/plugins/ObsidianFlavoredMarkdown.md @@ -4,7 +4,7 @@ tags: - plugin/transformer --- -This plugin extends Markdown processing to include features commonly used in Obsidian, such as enhanced link handling, callouts, mermaid diagrams, checkboxes, and more. See [[Obsidian compatibility]], [[wikilinks]], [[Mermaid diagrams]] and [[callouts]] for more information. +This plugin provides support for [[Obsidian compatibility]]. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. @@ -27,7 +27,7 @@ This plugin accepts the following configuration options: > [!warning] > Don't remove this plugin if you're using [[Obsidian compatibility|Obsidian]] to author the content! -## Technical Details +## API - Category: Transformer - Function name: `Plugin.ObsidianFlavoredMarkdown()`. diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md index 2cf466ccb7c18..9531a2340d5b7 100644 --- a/docs/plugins/OxHugoFlavoredMarkdown.md +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -4,7 +4,7 @@ tags: - plugin/transformer --- -This plugin modifies Markdown content generated by [ox-hugo](https://github.com/kaushalmodi/ox-hugo) to make it compatible with Quartz, addressing specific formatting and syntax issues. See [[OxHugo compatibility]] for more information. +This plugin provides support for [ox-hugo](https://github.com/kaushalmodi/ox-hugo) compatibility. See [[OxHugo compatibility]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. @@ -22,7 +22,7 @@ This plugin accepts the following configuration options: > > If you use `toml` frontmatter, make sure to configure the [[Frontmatter]] plugin accordingly. See [[OxHugo compatibility]] for an example. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.OxHugoFlavoredMarkdown()`. diff --git a/docs/plugins/RemoveDrafts.md b/docs/plugins/RemoveDrafts.md index ca7320128a8da..7f0c2e26a3eba 100644 --- a/docs/plugins/RemoveDrafts.md +++ b/docs/plugins/RemoveDrafts.md @@ -4,14 +4,14 @@ tags: - plugin/filter --- -This plugin is designed to filter out draft content from the publishing pipeline, so only finalized content is made available. It operates by checking the `draft` flag in the frontmatter of each file. See [[private pages]] for more information. +This plugin filters out content from your vault, so that only finalized content is made available. This prevents [[private pages]] from being published. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. This plugin has no configuration options. -## Technical Details +## API - Category: Filter - Function name: `Plugin.RemoveDrafts()`. diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md index ce5584b741442..fa191c83091cd 100644 --- a/docs/plugins/Static.md +++ b/docs/plugins/Static.md @@ -14,7 +14,7 @@ This plugin emits all static resources required by Quartz. This plugin has no configuration options. -## Technical Details +## API - Category: Emitter - Function name: `Plugin.Static()`. diff --git a/docs/plugins/SyntaxHighlighting.md b/docs/plugins/SyntaxHighlighting.md index cc9dc5e34e7ac..8bf581eb48539 100644 --- a/docs/plugins/SyntaxHighlighting.md +++ b/docs/plugins/SyntaxHighlighting.md @@ -16,7 +16,7 @@ This plugin accepts the following configuration options: In addition, you can further override the colours in the `quartz/styles/syntax.scss` file. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.SyntaxHighlighting()`. diff --git a/docs/plugins/TableOfContents.md b/docs/plugins/TableOfContents.md index 1b93d5bf0235f..525fb8a1290fa 100644 --- a/docs/plugins/TableOfContents.md +++ b/docs/plugins/TableOfContents.md @@ -19,7 +19,7 @@ This plugin accepts the following configuration options: > [!warning] > This plugin needs the `Component.TableOfContents` component in `quartz.layout.ts` to determine where to display the TOC. Without it, nothing will be displayed. They should always be added or removed together. -## Technical Details +## API - Category: Transformer - Function name: `Plugin.TableOfContents()`. diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md index ef96a6b0ce036..caec710889db2 100644 --- a/docs/plugins/TagPage.md +++ b/docs/plugins/TagPage.md @@ -13,7 +13,7 @@ This plugin has no configuration options. The pages are displayed using the `defaultListPageLayout` in `quartz.layouts.ts`. For the content, the `TagContent` component is used. If you want to modify the layout, you must edit it directly (`quartz/components/pages/TagContent.tsx`). -## Technical Details +## API - Category: Emitter - Function name: `Plugin.AliasRedirects()`. From acc678ac00601b1d1da30658dbb51c568ea5d868 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Tue, 20 Feb 2024 22:29:19 +0100 Subject: [PATCH 31/38] docs: update docs/features/Mermaid diagrams.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> --- docs/features/Mermaid diagrams.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/features/Mermaid diagrams.md b/docs/features/Mermaid diagrams.md index fe96416fe63db..9cc408917c137 100644 --- a/docs/features/Mermaid diagrams.md +++ b/docs/features/Mermaid diagrams.md @@ -1,5 +1,7 @@ --- title: "Mermaid Diagrams" +tags: + - feature/transformer --- 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. From d4ad8e3a837218054194719bc5349064ce547a18 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Fri, 23 Feb 2024 20:07:51 +0100 Subject: [PATCH 32/38] docs: update docs/plugins/RemoveDrafts.md Co-authored-by: Jacky Zhao --- docs/plugins/RemoveDrafts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/RemoveDrafts.md b/docs/plugins/RemoveDrafts.md index 7f0c2e26a3eba..729ac86a77e8f 100644 --- a/docs/plugins/RemoveDrafts.md +++ b/docs/plugins/RemoveDrafts.md @@ -4,7 +4,7 @@ tags: - plugin/filter --- -This plugin filters out content from your vault, so that only finalized content is made available. This prevents [[private pages]] from being published. +This plugin filters out content from your vault, so that only finalized content is made available. This prevents [[private pages]] from being published. By default, it filters out all pages with `draft: true` in the frontmatter and leaves all other pages intact. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. From ef6fccea5e08e95eb58d980316af10c5f548c041 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Fri, 23 Feb 2024 20:08:31 +0100 Subject: [PATCH 33/38] docs: update docs/plugins/Assets.md Co-authored-by: Jacky Zhao --- docs/plugins/Assets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index b225b965ffa6a..67bb7485b0d90 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin emits all non-Markdown static assets (like images, scripts, stylesheets, etc.) from your vault content under the directory `content`. +This plugin emits all non-Markdown static assets in your content folder (like images, videos, HTML, etc). Note that all static assets will then be accessible through its path on your generated site, i.e: `host.me/path/to/static.pdf` From c57579068340a5f2f12643a3f20e4aaac80e48ef Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Fri, 23 Feb 2024 20:08:49 +0100 Subject: [PATCH 34/38] docs: update docs/configuration.md Co-authored-by: Jacky Zhao --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index a3fcfcb5843c6..5212849ece6fa 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -83,7 +83,7 @@ transformers: [ ], ``` -To remove a plugin, you remove all occurrences of it in the `quartz.config.ts`. +To remove a plugin, you should 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. From bc0784d240d7d3e8f36b9d811c8a54b3af24967f Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Fri, 23 Feb 2024 20:09:04 +0100 Subject: [PATCH 35/38] docs: update docs/configuration.md Co-authored-by: Jacky Zhao --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 5212849ece6fa..d7bc83d0a004b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -85,7 +85,7 @@ transformers: [ To remove a plugin, you should 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. +To customize plugins further, some 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. From d6c577cf9ffef522b1e3a6b25000301b42b8c6a8 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Fri, 23 Feb 2024 20:09:34 +0100 Subject: [PATCH 36/38] docs: update docs/configuration.md Co-authored-by: Jacky Zhao --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index d7bc83d0a004b..e65e2e2bdb086 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -73,7 +73,7 @@ You can customize the behaviour of Quartz by adding, removing and reordering plu > [!note] > 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. -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: +You should take care to add the plugin to the right entry corresponding to its plugin type. For example, to add the [[ExplicitPublish]] plugin (a [[tags/plugin/transformer|Transformer]], you would add the following line: ```ts title="quartz.config.ts" transformers: [ From 3ffd89c01026273fa85081854d670bf9ba1d9e54 Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Fri, 23 Feb 2024 20:10:41 +0100 Subject: [PATCH 37/38] docs: some updates --- docs/features/table of contents.md | 11 ++++++----- docs/plugins/Static.md | 6 +++--- docs/plugins/TableOfContents.md | 2 +- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/features/table of contents.md b/docs/features/table of contents.md index 677cb243ca8c3..4ecccc9340ede 100644 --- a/docs/features/table of contents.md +++ b/docs/features/table of contents.md @@ -5,13 +5,14 @@ tags: - 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. +Quartz can automatically generate a table of contents (TOC) from a list of headings on each page. It will also show you your current scrolling position on the page by highlighting headings you've scrolled through with a different color. -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. +You can hide the TOC on a page by adding `enableToc: false` to the frontmatter for that page. + +By default, the TOC shows all headings from H1 (`# Title`) to H3 (`### Title`) and is only displayed if there is more than one heading on the page. ## Customization -The table of contents is a functionality of the [[TableOfContents]] plugin. See the plugin page for customization options. +The table of contents is a functionality of the [[TableOfContents]] plugin. See the plugin page for more 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`. +It also needs the `TableOfContents` component, which is displayed in the right sidebar by default. You can change this by customizing the [[layout]]. The TOC component can be configured with the `layout` parameter, which can either be `modern` (default) or `legacy`. diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md index fa191c83091cd..3ba4b84a258fa 100644 --- a/docs/plugins/Static.md +++ b/docs/plugins/Static.md @@ -4,15 +4,15 @@ tags: - plugin/emitter --- -This plugin emits all static resources required by Quartz. +This plugin emits all static resources needed by Quartz. This is used, for example, for fonts and images that need a stable position, such as banners and icons. The plugin respects the `ignorePatterns` in the global [[configuration]]. > [!important] -> This is different from [[Assets]], as these static resources is located under `quartz/static`. Whereas [[Assets]] renders all static resources under `content`. +> This is different from [[Assets]]. The resources from the [[Static]] plugin are located under `quartz/static`, whereas [[Assets]] renders all static resources under `content` and is used for images, videos, audio, etc. that are directly referenced by your markdown content. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. -This plugin has no configuration options. +This plugin has no configuration options. ## API diff --git a/docs/plugins/TableOfContents.md b/docs/plugins/TableOfContents.md index 525fb8a1290fa..d443d0eaa04a1 100644 --- a/docs/plugins/TableOfContents.md +++ b/docs/plugins/TableOfContents.md @@ -4,7 +4,7 @@ tags: - plugin/transformer --- -This plugin generates a table of contents (TOC) for Markdown documents. By default it is displayed in the right sidebar. See [[table of contents]] for more information. +This plugin generates a table of contents (TOC) for Markdown documents. See [[table of contents]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. From c21db0ca7c8a2f3b3b03cb981fc7916f26d495ee Mon Sep 17 00:00:00 2001 From: Eiko Wagenknecht Date: Fri, 23 Feb 2024 20:52:10 +0100 Subject: [PATCH 38/38] docs: work in review comments --- docs/configuration.md | 4 ++-- docs/features/Latex.md | 3 +++ docs/features/RSS Feed.md | 2 +- docs/features/folder and tag listings.md | 14 +++++++++----- docs/plugins/AliasRedirects.md | 2 +- docs/plugins/Assets.md | 2 +- docs/plugins/CNAME.md | 2 +- docs/plugins/ComponentResources.md | 2 +- docs/plugins/ContentIndex.md | 12 +++++++----- docs/plugins/ContentPage.md | 2 +- docs/plugins/CrawlLinks.md | 11 +++++++---- docs/plugins/CreatedModifiedDate.md | 4 +++- docs/plugins/Description.md | 9 ++------- docs/plugins/FolderPage.md | 2 +- docs/plugins/HardLineBreaks.md | 2 +- docs/plugins/Latex.md | 2 +- docs/plugins/OxHugoFlavoredMarkdown.md | 10 +++++----- docs/plugins/Static.md | 2 +- docs/plugins/TagPage.md | 2 +- 19 files changed, 49 insertions(+), 40 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index e65e2e2bdb086..6c76654926105 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -30,12 +30,12 @@ This part of the configuration concerns anything that can affect the whole site. - `{ provider: 'umami', host: '', websiteId: '' }`: use [Umami](https://umami.is/); - `locale`: used for [[i18n]] and date formatting - `baseUrl`: this is used for sitemaps and RSS feeds that require an absolute URL to know where the canonical 'home' of your site lives. This is normally the deployed URL of your site (e.g. `quartz.jzhao.xyz` for this site). Do not include the protocol (i.e. `https://`) or any leading or trailing slashes. - - This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example, if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and the `baseUrl` would be `jackyzha0.github.io/quartz` + - This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example, if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and the `baseUrl` would be `jackyzha0.github.io/quartz`. - Note that Quartz 4 will avoid using this as much as possible and use relative URLs whenever it can to make sure your site works no matter _where_ you end up actually deploying it. - `ignorePatterns`: a list of [glob]() patterns that Quartz should ignore and not search through when looking for files inside the `content` folder. See [[private pages]] for more details. - `defaultDateType`: whether to use created, modified, or published as the default date to display on pages and page listings. - `theme`: configure how the site looks. - - `cdnCaching`: Whether to use Google CDN to cache the fonts (generally will be faster). Disable this if you want Quartz to be self-contained. Default to `true` + - `cdnCaching`: If `true` (default), use Google CDN to cache the fonts. This will generally will be faster. Disable (`false`) this if you want Quartz to download the fonts to be self-contained. - `typography`: what fonts to use. Any font available on [Google Fonts](https://fonts.google.com/) works here. - `header`: Font to use for headers - `code`: Font for inline and block quotes. diff --git a/docs/features/Latex.md b/docs/features/Latex.md index a701c0ddb35a8..e019190e1ac7b 100644 --- a/docs/features/Latex.md +++ b/docs/features/Latex.md @@ -39,6 +39,9 @@ a & b & c \end{bmatrix} $$ +> [!warn] +> Due to limitations in the [underlying parsing library](https://github.com/remarkjs/remark-math), block math in Quartz requires the `$$` delimiters to be on newlines like above. + ### Inline Math Similarly, inline math can be rendered by delimiting math expression with a single `$`. For example, `$e^{i\pi} = -1$` produces $e^{i\pi} = -1$ diff --git a/docs/features/RSS Feed.md b/docs/features/RSS Feed.md index b394ce8eaeccc..ed4138dfca3a8 100644 --- a/docs/features/RSS Feed.md +++ b/docs/features/RSS Feed.md @@ -1,4 +1,4 @@ -Quartz creates an RSS feed for all the content on your site by generating an `index.xml` file that RSS readers can subscribe to. Because of the RSS spec, this requires the `baseUrl` property in your [[configuration]] to be set properly for RSS readers to pick it up properly. +Quartz emits an RSS feed for all the content on your site by generating an `index.xml` file that RSS readers can subscribe to. Because of the RSS spec, this requires the `baseUrl` property in your [[configuration]] to be set properly for RSS readers to pick it up properly. ## Configuration diff --git a/docs/features/folder and tag listings.md b/docs/features/folder and tag listings.md index 11e3e520777ce..d330f14797133 100644 --- a/docs/features/folder and tag listings.md +++ b/docs/features/folder and tag listings.md @@ -4,15 +4,17 @@ tags: - feature/emitter --- -Quartz creates listing pages for any folders and tags you have. +Quartz emits listing pages for any folders and tags you have. ## Folder Listings Quartz will generate an index page for all the pages under that folder. This includes any content that is multiple levels deep. -Additionally, Quartz will also generate pages for subfolders. Say you have a note in a nested folder `content/abc/def/note.md`. Then, Quartz would generate a page for all the notes under `abc` _and_ a page for all the notes under `abc/def`. +Additionally, Quartz will also generate pages for subfolders. Say you have a note in a nested folder `content/abc/def/note.md`. Then Quartz would generate a page for all the notes under `abc` _and_ a page for all the notes under `abc/def`. -By default, Quartz will title the page `Folder: ` and no description. You can override this by creating an `index.md` file in the folder with the `title` [[authoring content#Syntax|frontmatter]] field. Any content you write in this file will also be used in the description of the folder. +You can link to the folder listing by referencing its name, plus a trailing slash, like this: `[[advanced/]]` (results in [[advanced/]]). + +By default, Quartz will title the page `Folder: ` and no description. You can override this by creating an `index.md` file in the folder with the `title` [[authoring content#Syntax|frontmatter]] field. Any content you write in this file will also be used in the folder description. For example, for the folder `content/posts`, you can add another file `content/posts/index.md` to add a specific description for it. @@ -20,9 +22,11 @@ For example, for the folder `content/posts`, you can add another file `content/p Quartz will also create an index page for each unique tag in your vault and render a list of all notes with that tag. -Quartz also supports tag hierarchies as well (e.g. `plugin/emitter`) and will also render a separate tag page for each layer of the tag hierarchy. It will also create a default global tag index page at `/tags` that displays a list of all the tags in your Quartz. +Quartz also supports tag hierarchies as well (e.g. `plugin/emitter`) and will also render a separate tag page for each level of the tag hierarchy. It will also create a default global tag index page at `/tags` that displays a list of all the tags in your Quartz. + +You can link to the tag listing by referencing its name with a `tag/` prefix, like this: `[[tags/plugin]]` (results in [[tags/plugin]]). -Like folder listings, you can also provide a description and title for a tag page by creating a file for each tag. For example, if you wanted to create a custom description for the #component tag, you would create a file at `content/tags/component.md` with a title and description. +As with folder listings, you can also provide a description and title for a tag page by creating a file for each tag. For example, if you wanted to create a custom description for the #component tag, you would create a file at `content/tags/component.md` with a title and description. ## Customization diff --git a/docs/plugins/AliasRedirects.md b/docs/plugins/AliasRedirects.md index 24e424f8fb1ca..3a33ce6490336 100644 --- a/docs/plugins/AliasRedirects.md +++ b/docs/plugins/AliasRedirects.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin creates HTML redirect pages for aliases and permalinks defined in the frontmatter of content files. +This plugin emits HTML redirect pages for aliases and permalinks defined in the frontmatter of content files. For example, A `foo.md` has the following frontmatter diff --git a/docs/plugins/Assets.md b/docs/plugins/Assets.md index 67bb7485b0d90..eb03994e1a505 100644 --- a/docs/plugins/Assets.md +++ b/docs/plugins/Assets.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin emits all non-Markdown static assets in your content folder (like images, videos, HTML, etc). +This plugin emits all non-Markdown static assets in your content folder (like images, videos, HTML, etc). The plugin respects the `ignorePatterns` in the global [[configuration]]. Note that all static assets will then be accessible through its path on your generated site, i.e: `host.me/path/to/static.pdf` diff --git a/docs/plugins/CNAME.md b/docs/plugins/CNAME.md index a6bff0dba537a..1cc0b5ccfe537 100644 --- a/docs/plugins/CNAME.md +++ b/docs/plugins/CNAME.md @@ -6,7 +6,7 @@ tags: This plugin emits a `CNAME` record that points your subdomain to the default domain of your site. -If you want to use a custom domain name `quartz.example.com` for the site, then this is needed. +If you want to use a custom domain name like `quartz.example.com` for the site, then this is needed. See [[Hosting]] for more information. diff --git a/docs/plugins/ComponentResources.md b/docs/plugins/ComponentResources.md index 01f3da4caf66a..739c170701939 100644 --- a/docs/plugins/ComponentResources.md +++ b/docs/plugins/ComponentResources.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin manages and emits the static resources required for the Quartz framework. This includes CSS stylesheets and JavaScript scripts that enhance the functionality and aesthetics of the generated site. +This plugin manages and emits the static resources required for the Quartz framework. This includes CSS stylesheets and JavaScript scripts that enhance the functionality and aesthetics of the generated site. See also the `cdnCaching` option in the `theme` section of the [[configuration]]. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/ContentIndex.md b/docs/plugins/ContentIndex.md index 49bfc88041677..af235b057806a 100644 --- a/docs/plugins/ContentIndex.md +++ b/docs/plugins/ContentIndex.md @@ -4,18 +4,20 @@ tags: - plugin/emitter --- -This plugin creates a comprehensive index of the site's content, generating additional resources like a sitemap and RSS feed. +This plugin emits both RSS and an XML sitemap for your site. The [[RSS Feed]] allows users to subscribe to content on your site and the sitemap allows search engines to better index your site. The plugin also emits a `contentIndex.json` file which is used by dynamic frontend components like search and graph. + +This plugin emits a comprehensive index of the site's content, generating additional resources such as a sitemap, an RSS feed, and a > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. This plugin accepts the following configuration options: -- `enableSiteMap`: When `true` (default), generates a sitemap XML file (`sitemap.xml`) listing all site URLs for search engines in content discovery. -- `enableRSS`: When `true` (default), produces an RSS feed (`index.xml`) with recent content updates. +- `enableSiteMap`: If `true` (default), generates a sitemap XML file (`sitemap.xml`) listing all site URLs for search engines in content discovery. +- `enableRSS`: If `true` (default), produces an RSS feed (`index.xml`) with recent content updates. - `rssLimit`: Defines the maximum number of entries to include in the RSS feed, helping to focus on the most recent or relevant content. Defaults to `10`. -- `rssFullHtml`: When `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries. -- `includeEmptyFiles`: When `true` (default), content files with no body text are included in the generated index and resources. +- `rssFullHtml`: If `true`, the RSS feed includes full HTML content. Otherwise it includes just summaries. +- `includeEmptyFiles`: If `true` (default), content files with no body text are included in the generated index and resources. ## API diff --git a/docs/plugins/ContentPage.md b/docs/plugins/ContentPage.md index 9ea64e0878922..5d9016f3c30a1 100644 --- a/docs/plugins/ContentPage.md +++ b/docs/plugins/ContentPage.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin is a core component of the Quartz framework. It generates the HTML pages for each piece of Markdown content. It creates the full-page layout, including headers, footers, and body content, among others. +This plugin is a core component of the Quartz framework. It generates the HTML pages for each piece of Markdown content. It emits the full-page [[layout]], including headers, footers, and body content, among others. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/CrawlLinks.md b/docs/plugins/CrawlLinks.md index e20634ef10fa1..15a0d660795d4 100644 --- a/docs/plugins/CrawlLinks.md +++ b/docs/plugins/CrawlLinks.md @@ -11,10 +11,13 @@ This plugin parses links and processes them to point to the right places. It is This plugin accepts the following configuration options: -- `markdownLinkResolution`: Defines the strategy for resolving Markdown paths, can be `"absolute"` (default), `"relative"` or `"shortest"`. -- `prettyLinks`: When `true` (default), simplifies links by removing folder paths, making them more user-friendly. -- `openLinksInNewTab`: When `true`, configures external links to open in a new tab. Defaults to `false`. -- `lazyLoad`: When `true`, adds lazy loading to resource elements (`img`, `video`, etc.) to improve page load performance. Defaults to `false`. +- `markdownLinkResolution`: Sets the strategy for resolving Markdown paths, can be `"absolute"` (default), `"relative"` or `"shortest"`. You should use the same setting here as in [[Obsidian compatibility|Obsidian]]. + - `absolute`: Path relative to the root of the content folder. + - `relative`: Path relative to the file you are linking from. + - `shortest`: Name of the file. If this isn't enough to identify the file, use the full absolute path. +- `prettyLinks`: If `true` (default), simplifies links by removing folder paths, making them more user friendly (e.g. `folder/deeply/nested/note` becomes `note`). +- `openLinksInNewTab`: If `true`, configures external links to open in a new tab. Defaults to `false`. +- `lazyLoad`: If `true`, adds lazy loading to resource elements (`img`, `video`, etc.) to improve page load performance. Defaults to `false`. - `externalLinkIcon`: Adds an icon next to external links when `true` (default) to visually distinguishing them from internal links. > [!warning] diff --git a/docs/plugins/CreatedModifiedDate.md b/docs/plugins/CreatedModifiedDate.md index 8eb9e4eff7596..6a0f1371a0730 100644 --- a/docs/plugins/CreatedModifiedDate.md +++ b/docs/plugins/CreatedModifiedDate.md @@ -14,7 +14,9 @@ This plugin accepts the following configuration options: - `priority`: The data sources to consult for date information. Highest priority first. Possible values are `"frontmatter"`, `"git"`, and `"filesystem"`. Defaults to `"frontmatter", "git", "filesystem"]`. > [!warning] -> If you rely on git for dates, ensure `defaultDateType` is set to `modified` in `quartz.config.ts`. +> If you rely on `git` for dates, make sure `defaultDateType` is set to `modified` in `quartz.config.ts`. +> +> Depending on how you [[hosting|host]] your Quartz, the `filesystem` dates of your local files may not match the final dates. In these cases, it may be better to use `git` or `frontmatter` to guarantee correct dates. ## API diff --git a/docs/plugins/Description.md b/docs/plugins/Description.md index 67e33d3b83fa8..6849b3ca42c60 100644 --- a/docs/plugins/Description.md +++ b/docs/plugins/Description.md @@ -4,14 +4,9 @@ tags: - plugin/transformer --- -This plugin generates descriptions that are used in various places: +This plugin generates descriptions that are used as metadata for the HTML `head`, the [[RSS Feed]] and in [[folder and tag listings]] if there is no main body content, the description is used as the text between the title and the listing. -- as metadata for the HTML `head` -- in FolderContent.tsx (TODO: What does it do there?) -- in TagContent.tsx (TODO: What does it do there?) -- in contentIndex.ts (TODO: What does it do there?) - -If the frontmatter contains a `description` property, it is used (see [[authoring content#Syntax]]). Otherwise, the full text of the file is used. +If the frontmatter contains a `description` property, it is used (see [[authoring content#Syntax]]). Otherwise, the plugin will do its best to use the first few sentences of the content to reach the target description length. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/FolderPage.md b/docs/plugins/FolderPage.md index 11c335bdca7c1..92a700ae97076 100644 --- a/docs/plugins/FolderPage.md +++ b/docs/plugins/FolderPage.md @@ -6,7 +6,7 @@ tags: This plugin generates index pages for folders, creating a listing page for each folder that contains multiple content files. See [[folder and tag listings]] for more information. -Example: [[folder/advanced]] +Example: [[advanced/|Advanced]] > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/HardLineBreaks.md b/docs/plugins/HardLineBreaks.md index cfc9700cb8f61..d35d74cf96ffc 100644 --- a/docs/plugins/HardLineBreaks.md +++ b/docs/plugins/HardLineBreaks.md @@ -4,7 +4,7 @@ tags: - plugin/transformer --- -This plugin automatically converts single line breaks in Markdown text into hard line breaks in the HTML output. This plugin is not enabled by default. +This plugin automatically converts single line breaks in Markdown text into hard line breaks in the HTML output. This plugin is not enabled by default as this doesn't follow the semantics of actual Markdown but you may enable it if you'd like parity with [[Obsidian compatibility|Obsidian]]. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. diff --git a/docs/plugins/Latex.md b/docs/plugins/Latex.md index f886153f955c6..8a8999e86c76f 100644 --- a/docs/plugins/Latex.md +++ b/docs/plugins/Latex.md @@ -11,7 +11,7 @@ This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more This plugin accepts the following configuration options: -- `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for KaTeX or `"mathjax"` for [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX. +- `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for [KaTeX](https://katex.org/) or `"mathjax"` for [MathJax](https://www.mathjax.org/) [SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX. ## API diff --git a/docs/plugins/OxHugoFlavoredMarkdown.md b/docs/plugins/OxHugoFlavoredMarkdown.md index 9531a2340d5b7..523a21589fb7d 100644 --- a/docs/plugins/OxHugoFlavoredMarkdown.md +++ b/docs/plugins/OxHugoFlavoredMarkdown.md @@ -11,11 +11,11 @@ This plugin provides support for [ox-hugo](https://github.com/kaushalmodi/ox-hug This plugin accepts the following configuration options: -- `wikilinks`: When `true` (default), converts Hugo `{{ relref }}` shortcodes to Quartz [[wikilinks]]. -- `removePredefinedAnchor`: When `true` (default), strips predefined anchors from headings. -- `removeHugoShortcode`: When `true` (default), removes Hugo shortcode syntax (`{{}}`) from the content. -- `replaceFigureWithMdImg`: When `true` (default), replaces `
` with `![]()`. -- `replaceOrgLatex`: When `true` (default), converts Org-mode [[features/Latex|Latex]] fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations). +- `wikilinks`: If `true` (default), converts Hugo `{{ relref }}` shortcodes to Quartz [[wikilinks]]. +- `removePredefinedAnchor`: If `true` (default), strips predefined anchors from headings. +- `removeHugoShortcode`: If `true` (default), removes Hugo shortcode syntax (`{{}}`) from the content. +- `replaceFigureWithMdImg`: If `true` (default), replaces `
` with `![]()`. +- `replaceOrgLatex`: If `true` (default), converts Org-mode [[features/Latex|Latex]] fragments to Quartz-compatible LaTeX wrapped in `$` (for inline) and `$$` (for block equations). > [!warning] > While you can use this together with [[ObsidianFlavoredMarkdown]], it's not recommended because it might mutate the file in unexpected ways. Use with caution. diff --git a/docs/plugins/Static.md b/docs/plugins/Static.md index 3ba4b84a258fa..c660eabf410d0 100644 --- a/docs/plugins/Static.md +++ b/docs/plugins/Static.md @@ -12,7 +12,7 @@ This plugin emits all static resources needed by Quartz. This is used, for examp > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page. -This plugin has no configuration options. +This plugin has no configuration options. ## API diff --git a/docs/plugins/TagPage.md b/docs/plugins/TagPage.md index caec710889db2..4dabfd06cdc0d 100644 --- a/docs/plugins/TagPage.md +++ b/docs/plugins/TagPage.md @@ -4,7 +4,7 @@ tags: - plugin/emitter --- -This plugin creates dedicated pages for each tag used in the content. See [[folder and tag listings]] for more information. +This plugin emits dedicated pages for each tag used in the content. See [[folder and tag listings]] for more information. > [!note] > For information on how to add, remove or configure plugins, see the [[Configuration#Plugins|Configuration]] page.