Merge branch 'v4' of https://github.com/jackyzha0/quartz into v4

.github/workflows/ci.yaml

@@ -46,8 +46,26 @@ jobs:
       - name: Ensure Quartz builds, check bundle info
         run: npx quartz build --bundleInfo
 
+  publish-tag:
+    if: ${{ github.repository == 'jackyzha0/quartz' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Get package version
+        run: node -p -e '`PACKAGE_VERSION=${require("./package.json").version}`' >> $GITHUB_ENV
       - name: Create release tag
-        uses: Klemensas/action-autotag@stable
+        uses: pkgdeps/git-tag-action@v2
         with:
-          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
-          tag_prefix: "v"
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          github_repo: ${{ github.repository }}
+          version: ${{ env.PACKAGE_VERSION }}
+          git_commit_sha: ${{ github.sha }}
+          git_tag_prefix: "v"

docs/advanced/making plugins.md

@@ -53,12 +53,12 @@ All transformer plugins must define at least a `name` field to register the plug
 
 Normally for both `remark` and `rehype`, you can find existing plugins that you can use to . If you'd like to create your own `remark` or `rehype` plugin, checkout the [guide to creating a plugin](https://unifiedjs.com/learn/guide/create-a-plugin/) using `unified` (the underlying AST parser and transformer library).
 
-A good example of a transformer plugin that borrows from the `remark` and `rehype` ecosystems is the [[Latex]] plugin:
+A good example of a transformer plugin that borrows from the `remark` and `rehype` ecosystems is the [[plugins/Latex|Latex]] plugin:
 
 ```ts title="quartz/plugins/transformers/latex.ts"
 import remarkMath from "remark-math"
 import rehypeKatex from "rehype-katex"
-import rehypeMathjax from "rehype-mathjax/svg.js"
+import rehypeMathjax from "rehype-mathjax/svg"
 import { QuartzTransformerPlugin } from "../types"
 
 interface Options {
@@ -84,10 +84,14 @@ export const Latex: QuartzTransformerPlugin<Options> = (opts?: Options) => {
     externalResources() {
       if (engine === "katex") {
         return {
-          css: ["https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css"],
+          css: [
+            // base css
+            "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css",
+          ],
           js: [
             {
-              src: "https://cdn.jsdelivr.net/npm/katex@0.16.7/dist/contrib/copy-tex.min.js",
+              // fix copy behaviour: https://github.com/KaTeX/KaTeX/blob/main/contrib/copy-tex/README.md
+              src: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/copy-tex.min.js",
               loadTime: "afterDOMReady",
               contentType: "external",
             },

docs/authoring content.md

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

docs/configuration.md

@@ -28,14 +28,16 @@ This part of the configuration concerns anything that can affect the whole site.
   - `{ provider: 'google', tagId: '<your-google-tag>' }`: use Google Analytics;
   - `{ provider: 'plausible' }` (managed) or `{ provider: 'plausible', host: '<your-plausible-host>' }` (self-hosted): use [Plausible](https://plausible.io/);
   - `{ provider: 'umami', host: '<your-umami-host>', websiteId: '<your-umami-website-id>' }`: use [Umami](https://umami.is/);
+  - `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id' }` (managed) or `{ provider: 'goatcounter', websiteId: 'my-goatcounter-id', host: 'my-goatcounter-domain.com', scriptSrc: 'https://my-url.to/counter.js' }` (self-hosted) use [GoatCounter](https://goatcounter.com)
+  - `{ provider: 'posthog', apiKey: '<your-posthog-project-apiKey>', host: '<your-posthog-host>' }`: use [Posthog](https://posthog.com/);
 - `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](<https://en.wikipedia.org/wiki/Glob_(programming)>) 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.
@@ -56,30 +58,48 @@ You can think of Quartz plugins as a series of transformations over content.
 
 ![[quartz transform pipeline.png]]
 
-```ts
+```ts title="quartz.config.ts"
 plugins: {
   transformers: [...],
   filters: [...],
   emitters: [...],
 }
 ```
 
-- [[making plugins#Transformers|Transformers]] **map** over content (e.g. parsing frontmatter, generating a description)
-- [[making plugins#Filters|Filters]] **filter** content (e.g. filtering out drafts)
-- [[making plugins#Emitters|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with a specific tag)
+- [[tags/plugin/transformer|Transformers]] **map** over content (e.g. parsing frontmatter, generating a description)
+- [[tags/plugin/filter|Filters]] **filter** content (e.g. filtering out drafts)
+- [[tags/plugin/emitter|Emitters]] **reduce** over content (e.g. creating an RSS feed or pages that list all files with a specific tag)
 
-By adding, removing, and reordering plugins from the `tranformers`, `filters`, and `emitters` fields, you can customize the behaviour of Quartz.
+You can customize the behaviour of Quartz by adding, removing and reordering plugins in the `transformers`, `filters` and `emitters` fields.
 
 > [!note]
-> Each node is modified by every transformer _in order_. Some transformers are position-sensitive so you may need to take special note of whether it needs come before or after any other particular plugins.
+> Each node is modified by every transformer _in order_. Some transformers are position sensitive, so you may need to pay particular attention to whether they need to come before or after certain other plugins.
+
+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/filter|Filter]]), you would add the following line:
+
+```ts title="quartz.config.ts"
+filters: [
+  ...
+  Plugin.ExplicitPublish(),
+  ...
+],
+```
 
-Additionally, plugins may also have their own configuration settings that you can pass in. For example, the [[Latex]] plugin allows you to pass in a field specifying the `renderEngine` to choose between Katex and MathJax.
+To remove a plugin, you should remove all occurrences of it in the `quartz.config.ts`.
 
-```ts
+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.
+
+```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
 ]
 ```
 
-If you'd like to make your own plugins, read the guide on [[making plugins]] for more information.
+Some plugins are included by default in the[ `quartz.config.ts`](https://github.com/jackyzha0/quartz/blob/v4/quartz.config.ts), but there are more available.
+
+You can see a list of all plugins and their configuration options [[tags/plugin|here]].
+
+If you'd like to make your own plugins, see the [[making plugins|making custom plugins]] guide.

docs/features/Latex.md

@@ -1,6 +1,7 @@
 ---
+title: LaTeX
 tags:
-  - plugin/transformer
+  - feature/transformer
 ---
 
 Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time.
@@ -38,6 +39,20 @@ a & b & c
 \end{bmatrix}
 $$
 
+$$
+\begin{array}{rll}
+E \psi &= H\psi & \text{Expanding the Hamiltonian Operator} \\
+&= -\frac{\hbar^2}{2m}\frac{\partial^2}{\partial x^2} \psi + \frac{1}{2}m\omega x^2 \psi & \text{Using the ansatz $\psi(x) = e^{-kx^2}f(x)$, hoping to cancel the $x^2$ term} \\
+&= -\frac{\hbar^2}{2m} [4k^2x^2f(x)+2(-2kx)f'(x) + f''(x)]e^{-kx^2} + \frac{1}{2}m\omega x^2 f(x)e^{-kx^2} &\text{Removing the $e^{-kx^2}$ term from both sides} \\
+& \Downarrow \\
+Ef(x) &= -\frac{\hbar^2}{2m} [4k^2x^2f(x)-4kxf'(x) + f''(x)] + \frac{1}{2}m\omega x^2 f(x) & \text{Choosing $k=\frac{im}{2}\sqrt{\frac{\omega}{\hbar}}$ to cancel the $x^2$ term, via $-\frac{\hbar^2}{2m}4k^2=\frac{1}{2}m \omega$} \\
+&= -\frac{\hbar^2}{2m} [-4kxf'(x) + f''(x)] \\
+\end{array}
+$$
+
+> [!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 +68,15 @@ 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
+### Using mhchem
+
+Add the following import to the top of `quartz/plugins/transformers/latex.ts` (before all the other
+imports):
 
-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' })`
+```ts title="quartz/plugins/transformers/latex.ts"
+import "katex/contrib/mhchem"
+```
 
 ## Customization
 
-- Removing Latex support: remove all instances of `Plugin.Latex()` from `quartz.config.ts`.
-- Plugin: `quartz/plugins/transformers/latex.ts`
+Latex parsing is a functionality of the [[plugins/Latex|Latex]] plugin. See the plugin page for customization options.

docs/features/Mermaid diagrams.md

@@ -1,9 +1,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
 

docs/features/Obsidian compatibility.md

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

docs/features/OxHugo compatibility.md

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

docs/features/RSS Feed.md

@@ -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.