Merge branch 'v4' into explorer

.github/dependabot.yml

@@ -9,3 +9,12 @@ updates:
         applies-to: "version-updates"
         patterns:
           - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      ci-dependencies:
+        applies-to: "version-updates"
+        patterns:
+          - "*"

.github/workflows/docker-build-push.yaml

@@ -25,7 +25,7 @@ jobs:
         with:
           fetch-depth: 1
       - name: Inject slug/short variables
-        uses: rlespinasse/github-slug-action@v4.4.1
+        uses: rlespinasse/github-slug-action@v5.0.0
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
       - name: Set up Docker Buildx

docs/advanced/making plugins.md

@@ -27,7 +27,7 @@ The following sections will go into detail for what methods can be implemented f
   - `cfg`: The full Quartz [[configuration]]
   - `allSlugs`: a list of all the valid content slugs (see [[paths]] for more information on what a `ServerSlug` is)
 - `StaticResources` is defined in `quartz/resources.tsx`. It consists of
-  - `css`: a list of URLs for stylesheets that should be loaded
+  - `css`: a list of CSS style definitions that should be loaded. A CSS style is described with the `CSSResource` type which is also defined in `quartz/resources.tsx`. It accepts either a source URL or the inline content of the stylesheet.
   - `js`: a list of scripts that should be loaded. A script is described with the `JSResource` type which is also defined in `quartz/resources.tsx`. It allows you to define a load time (either before or after the DOM has been loaded), whether it should be a module, and either the source URL or the inline content of the script.
 
 ## Transformers
@@ -85,8 +85,10 @@ export const Latex: QuartzTransformerPlugin<Options> = (opts?: Options) => {
       if (engine === "katex") {
         return {
           css: [
-            // base css
-            "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css",
+            {
+              // base css
+              content: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css",
+            },
           ],
           js: [
             {
@@ -272,7 +274,7 @@ export const ContentPage: QuartzEmitterPlugin = () => {
       const allFiles = content.map((c) => c[1].data)
       for (const [tree, file] of content) {
         const slug = canonicalizeServer(file.data.slug!)
-        const externalResources = pageResources(slug, resources)
+        const externalResources = pageResources(slug, file.data, resources)
         const componentData: QuartzComponentProps = {
           fileData: file.data,
           externalResources,

docs/features/backlinks.md

@@ -9,6 +9,7 @@ A backlink for a note is a link from another note to that note. Links in the bac
 ## Customization
 
 - Removing backlinks: delete all usages of `Component.Backlinks()` from `quartz.layout.ts`.
+- Hide when empty: hide `Backlinks` if given page doesn't contain any backlinks (default to `true`). To disable this, use `Component.Backlinks({ hideWhenEmpty: false })`.
 - Component: `quartz/components/Backlinks.tsx`
 - Style: `quartz/components/styles/backlinks.scss`
 - Script: `quartz/components/scripts/search.inline.ts`

docs/features/comments.md

@@ -63,6 +63,18 @@ type Options = {
     category: string
     categoryId: string
 
+    // Url to folder with custom themes
+    // defaults to 'https://${cfg.baseUrl}/static/giscus'
+    themeUrl?: string
+
+    // filename for light theme .css file
+    // defaults to 'light'
+    lightTheme?: string
+
+    // filename for dark theme .css file
+    // defaults to 'dark'
+    darkTheme?: string
+
     // how to map pages -> discussions
     // defaults to 'url'
     mapping?: "url" | "title" | "og:title" | "specific" | "number" | "pathname"
@@ -81,3 +93,35 @@ type Options = {
   }
 }
 ```
+
+#### Custom CSS theme
+
+Quartz supports custom theme for Giscus. To use a custom CSS theme, place the `.css` file inside the `quartz/static` folder and set the configuration values.
+
+For example, if you have a light theme `light-theme.css`, a dark theme `dark-theme.css`, and your Quartz site is hosted at `https://example.com/`:
+
+```ts
+afterBody: [
+  Component.Comments({
+    provider: 'giscus',
+    options: {
+      // Other options
+
+      themeUrl: "https://example.com/static/giscus", // corresponds to quartz/static/giscus/
+      lightTheme: "light-theme", // corresponds to light-theme.css in quartz/static/giscus/
+      darkTheme: "dark-theme", // corresponds to dark-theme.css quartz/static/giscus/
+    }
+  }),
+],
+```
+
+#### Conditionally display comments
+
+Quartz can conditionally display the comment box based on a field `comments` in the frontmatter. By default, all pages will display comments, to disable it for a specific page, set `comments` to `false`.
+
+```
+---
+title: Comments disabled here!
+comments: false
+---
+```