mirror of
https://github.com/alrayyes/wiki.git
synced 2025-05-02 23:08:14 +00:00
docs: update plugin documentation (#888)
* docs: first few plugins documented * docs: move plugin info * docs: move plugin docs to tag based system * docs: update latex example code snippet * docs: fix spelling of latex in title * docs: add missing linebreak * docs: remove plugin tag from feature pages * docs: shorten titles * docs: refine wording * docs: move plugin details for frontmatter * docs: add features/* tags * docs: update latex example * docs: make references more explicit * docs: add stubs for the remaining plugins * docs: more descriptions * docs: fix feature tags * docs: descriptions * docs: new plugin pages * docs: update configuration page * docs: more plugin work * docs: run prettier * docs: remove comments in config file and add link to docs * docs: minor fixes * docs: run prettier * docs: spelling * docs: update docs/plugins/AliasRedirects.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> * docs: update docs/plugins/Assets.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> * docs: update docs/plugins/CNAME.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> * docs: update docs/plugins/Static.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> * docs: update docs * docs: update docs/features/Mermaid diagrams.md Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> * docs: update docs/plugins/RemoveDrafts.md Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * docs: update docs/plugins/Assets.md Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * docs: update docs/configuration.md Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * docs: update docs/configuration.md Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * docs: update docs/configuration.md Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * docs: some updates * docs: work in review comments --------- Signed-off-by: Eiko Wagenknecht <git@eiko-wagenknecht.de> Co-authored-by: Aaron Pham <29749331+aarnphm@users.noreply.github.com> Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com>
This commit is contained in:
Eiko Wagenknecht
GitHub
parent
421718958f
commit
1929241a62
41 changed files with 641 additions and 108 deletions
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
title: LaTeX
|
||||
tags:
|
||||
- plugin/transformer
|
||||
- feature/transformer
|
||||
---
|
||||
|
||||
Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time.
|
||||
|
|
@ -38,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$
|
||||
|
|
@ -53,11 +57,6 @@ For example:
|
|||
- Incorrect: `I have $1 and you have $2` produces I have $1 and you have $2
|
||||
- Correct: `I have \$1 and you have \$2` produces I have \$1 and you have \$2
|
||||
|
||||
## MathJax
|
||||
|
||||
In `quartz.config.ts`, you can configure Quartz to use [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html) by replacing `Plugin.Latex({ renderEngine: 'katex' })` with `Plugin.Latex({ renderEngine: 'mathjax' })`
|
||||
|
||||
## Customization
|
||||
|
||||
- Removing Latex support: remove all instances of `Plugin.Latex()` from `quartz.config.ts`.
|
||||
- Plugin: `quartz/plugins/transformers/latex.ts`
|
||||
Latex parsing is a functionality of the [[plugins/Latex|Latex]] plugin. See the plugin page for customization options.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,15 @@
|
|||
---
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,33 +1,17 @@
|
|||
---
|
||||
title: "Obsidian Compatibility"
|
||||
tags:
|
||||
- plugin/transformer
|
||||
- feature/transformer
|
||||
---
|
||||
|
||||
Quartz was originally designed as a tool to publish Obsidian vaults as websites. Even as the scope of Quartz has widened over time, it hasn't lost the ability to seamlessly interoperate with Obsidian.
|
||||
|
||||
By default, Quartz ships with `Plugin.ObsidianFlavoredMarkdown` which is a transformer plugin that adds support for [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown). This includes support for features like [[wikilinks]] and [[Mermaid diagrams]].
|
||||
By default, Quartz ships with the [[ObsidianFlavoredMarkdown]] plugin, which is a transformer plugin that adds support for [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown). This includes support for features like [[wikilinks]] and [[Mermaid diagrams]].
|
||||
|
||||
It also ships with support for [frontmatter parsing](https://help.obsidian.md/Editing+and+formatting/Properties) with the same fields that Obsidian uses through the `Plugin.FrontMatter` transformer plugin.
|
||||
It also ships with support for [frontmatter parsing](https://help.obsidian.md/Editing+and+formatting/Properties) with the same fields that Obsidian uses through the [[Frontmatter]] transformer plugin.
|
||||
|
||||
Finally, Quartz also provides `Plugin.CrawlLinks` which allows you to customize Quartz's link resolution behaviour to match Obsidian.
|
||||
Finally, Quartz also provides [[CrawlLinks]] plugin, which allows you to customize Quartz's link resolution behaviour to match Obsidian.
|
||||
|
||||
## Configuration
|
||||
|
||||
- Frontmatter parsing:
|
||||
- Disabling: remove all instances of `Plugin.FrontMatter()` from `quartz.config.ts`.
|
||||
- Customize default values for frontmatter: edit `quartz/plugins/transformers/frontmatter.ts`
|
||||
- Obsidian Flavored Markdown:
|
||||
- Disabling: remove all instances of `Plugin.ObsidianFlavoredMarkdown()` from `quartz.config.ts`
|
||||
- Customizing features: `Plugin.ObsidianFlavoredMarkdown` has several other options to toggle on and off:
|
||||
- `comments`: whether to enable `%%` style Obsidian comments. Defaults to `true`
|
||||
- `highlight`: whether to enable `==` style highlights. Defaults to `true`
|
||||
- `wikilinks`: whether to enable turning [[wikilinks]] into regular links. Defaults to `true`
|
||||
- `callouts`: whether to enable [[callouts]]. Defaults to `true`
|
||||
- `mermaid`: whether to enable [[Mermaid diagrams]]. Defaults to `true`
|
||||
- `parseTags`: whether to try and parse tags in the content body. Defaults to `true`
|
||||
- `parseArrows`: whether to try and parse arrows in the content body. Defaults to `true`.
|
||||
- `enableInHtmlEmbed`: whether to try and parse Obsidian flavoured markdown in raw HTML. Defaults to `false`
|
||||
- `enableYouTubeEmbed`: whether to enable embedded YouTube videos using external image Markdown syntax. Defaults to `false`
|
||||
- Link resolution behaviour:
|
||||
- Disabling: remove all instances of `Plugin.CrawlLinks()` from `quartz.config.ts`
|
||||
- Changing link resolution preference: set `markdownLinkResolution` to one of `absolute`, `relative` or `shortest`
|
||||
This functionality is provided by the [[ObsidianFlavoredMarkdown]], [[Frontmatter]] and [[CrawlLinks]] plugins. See the plugin pages for customization options.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,12 @@
|
|||
---
|
||||
title: "OxHugo Compatibility"
|
||||
tags:
|
||||
- plugin/transformer
|
||||
- feature/transformer
|
||||
---
|
||||
|
||||
[org-roam](https://www.orgroam.com/) is a plain-text personal knowledge management system for [emacs](https://en.wikipedia.org/wiki/Emacs). [ox-hugo](https://github.com/kaushalmodi/ox-hugo) is org exporter backend that exports `org-mode` files to [Hugo](https://gohugo.io/) compatible Markdown.
|
||||
|
||||
Because the Markdown generated by ox-hugo is not pure Markdown but Hugo specific, we need to transform it to fit into Quartz. This is done by `Plugin.OxHugoFlavouredMarkdown`. Even though this [[making plugins|plugin]] was written with `ox-hugo` in mind, it should work for any Hugo specific Markdown.
|
||||
Because the Markdown generated by ox-hugo is not pure Markdown but Hugo specific, we need to transform it to fit into Quartz. This is done by the [[OxHugoFlavoredMarkdown]] plugin. Even though this plugin was written with `ox-hugo` in mind, it should work for any Hugo specific Markdown.
|
||||
|
||||
```typescript title="quartz.config.ts"
|
||||
plugins: {
|
||||
|
|
@ -25,15 +26,4 @@ Quartz by default doesn't understand `org-roam` files as they aren't Markdown. Y
|
|||
|
||||
## Configuration
|
||||
|
||||
- Link resolution
|
||||
- `wikilinks`: Whether to replace `{{ relref }}` with Quartz [[wikilinks]]
|
||||
- `removePredefinedAnchor`: Whether to remove [pre-defined anchor set by ox-hugo](https://ox-hugo.scripter.co/doc/anchors/).
|
||||
- Image handling
|
||||
- `replaceFigureWithMdImg`: Whether to replace `<figure/>` with `![]()`
|
||||
- Formatting
|
||||
- `removeHugoShortcode`: Whether to remove hugo shortcode syntax (`{{}}`)
|
||||
- `replaceOrgLatex`: Whether to replace org-mode formatting for latex fragments with what `Plugin.Latex` supports.
|
||||
|
||||
> [!warning]
|
||||
>
|
||||
> While you can use `Plugin.OxHugoFlavoredMarkdown` and `Plugin.ObsidianFlavoredMarkdown` together, it's not recommended because it might mutate the file in unexpected ways. Use with caution.
|
||||
This functionality is provided by the [[OxHugoFlavoredMarkdown]] plugin. See the plugin page for customization options.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
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
|
||||
|
||||
- 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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Callouts
|
||||
tags:
|
||||
- plugin/transformer
|
||||
- feature/transformer
|
||||
---
|
||||
|
||||
Quartz supports the same Admonition-callout syntax as Obsidian.
|
||||
|
|
@ -19,12 +19,13 @@ This includes
|
|||
See [documentation on supported types and syntax here](https://help.obsidian.md/Editing+and+formatting/Callouts).
|
||||
|
||||
> [!warning]
|
||||
> Wondering why callouts may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is _after_ `Plugin.SyntaxHighlighting()`.
|
||||
> Wondering why callouts may not be showing up even if you have them enabled? You may need to reorder your plugins so that [[ObsidianFlavoredMarkdown]] is _after_ [[SyntaxHighlighting]].
|
||||
|
||||
## Customization
|
||||
|
||||
- Disable callouts: simply pass `callouts: false` to the plugin: `Plugin.ObsidianFlavoredMarkdown({ callouts: false })`
|
||||
- Editing icons: `quartz/styles/callouts.scss`
|
||||
The callouts are a functionality of the [[ObsidianFlavoredMarkdown]] plugin. See the plugin page for how to enable or disable them.
|
||||
|
||||
You can edit the icons by customizing `quartz/styles/callouts.scss`.
|
||||
|
||||
### Add custom callouts
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,20 @@
|
|||
---
|
||||
title: Folder and Tag Listings
|
||||
tags:
|
||||
- plugin/emitter
|
||||
- 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: <name of 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: <folder name>` 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,13 +22,12 @@ 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.
|
||||
|
||||
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.
|
||||
You can link to the tag listing by referencing its name with a `tag/` prefix, like this: `[[tags/plugin]]` (results in [[tags/plugin]]).
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
---
|
||||
title: Private Pages
|
||||
tags:
|
||||
- plugin/filter
|
||||
- feature/filter
|
||||
---
|
||||
|
||||
There may be some notes you want to avoid publishing as a website. Quartz supports this through two mechanisms which can be used in conjunction:
|
||||
|
||||
## Filter Plugins
|
||||
|
||||
[[making plugins#Filters|Filter plugins]] are plugins that filter out content based off of certain criteria. By default, Quartz uses the `Plugin.RemoveDrafts` plugin which filters out any note that has `draft: true` in the frontmatter.
|
||||
[[making plugins#Filters|Filter plugins]] are plugins that filter out content based off of certain criteria. By default, Quartz uses the [[RemoveDrafts]] plugin which filters out any note that has `draft: true` in the frontmatter.
|
||||
|
||||
If you'd like to only publish a select number of notes, you can instead use `Plugin.ExplicitPublish` which will filter out all notes except for any that have `publish: true` in the frontmatter.
|
||||
If you'd like to only publish a select number of notes, you can instead use [[ExplicitPublish]] which will filter out all notes except for any that have `publish: true` in the frontmatter.
|
||||
|
||||
> [!warning]
|
||||
> Regardless of the filter plugin used, **all non-markdown files will be emitted and available publically in the final build.** This includes files such as images, voice recordings, PDFs, etc. One way to prevent this and still be able to embed local images is to create a folder specifically for public media and add the following two patterns to the ignorePatterns array.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Syntax Highlighting
|
||||
tags:
|
||||
- plugin/transformer
|
||||
- feature/transformer
|
||||
---
|
||||
|
||||
Syntax highlighting in Quartz is completely done at build-time. This means that Quartz only ships pre-calculated CSS to highlight the right words so there is no heavy client-side bundle that does the syntax highlighting.
|
||||
|
|
@ -130,6 +130,4 @@ const [name, setName] = useState('Taylor');
|
|||
|
||||
## Customization
|
||||
|
||||
- Removing syntax highlighting: delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`.
|
||||
- Style: By default, Quartz uses derivatives of the GitHub light and dark themes. You can customize the colours in the `quartz/styles/syntax.scss` file.
|
||||
- Plugin: `quartz/plugins/transformers/syntax.ts`
|
||||
Syntax highlighting is a functionality of the [[SyntaxHighlighting]] plugin. See the plugin page for customization options.
|
||||
|
|
|
|||
|
|
@ -2,25 +2,17 @@
|
|||
title: "Table of Contents"
|
||||
tags:
|
||||
- component
|
||||
- plugin/transformer
|
||||
- feature/transformer
|
||||
---
|
||||
|
||||
Quartz can automatically generate a table of contents from a list of headings on each page. It will also show you your current scroll position on the site by marking headings you've scrolled through with a different colour.
|
||||
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 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.
|
||||
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.
|
||||
|
||||
> [!info]
|
||||
> This feature requires both `Plugin.TableOfContents` in your `quartz.config.ts` and `Component.TableOfContents` in your `quartz.layout.ts` to function correctly.
|
||||
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
|
||||
|
||||
- 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 more customization options.
|
||||
|
||||
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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue