Quartz sync: Nov 6, 2023, 12:56 PM

docs/advanced/making plugins.md

@@ -228,7 +228,7 @@ export type QuartzEmitterPluginInstance = {
 
 An emitter plugin must define a `name` field an `emit` function and a `getQuartzComponents` function. `emit` is responsible for looking at all the parsed and filtered content and then appropriately creating files and returning a list of paths to files the plugin created.
 
-Creating new files can be done via regular Node [fs module](https://nodejs.org/api/fs.html) (i.e. `fs.cp` or `fs.writeFile`) or via the `emitCallback` if you are creating files that contain text. The `emitCallback` function is the 4th argument of the emit function. It's interface looks something like this:
+Creating new files can be done via regular Node [fs module](https://nodejs.org/api/fs.html) (i.e. `fs.cp` or `fs.writeFile`) or via the `emitCallback` if you are creating files that contain text. The `emitCallback` function is the 4th argument of the emit function. Its interface looks something like this:
 
 ```ts
 export type EmitCallback = (data: {

docs/features/table of contents.md

@@ -0,0 +1,26 @@
+---
+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.
+
+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 `showToc: 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`

docs/hosting.md

@@ -166,3 +166,56 @@ Using `docs.example.com` is an example of a subdomain. They're a simple way of c
 3. Go to the [Vercel Dashboard](https://vercel.com/dashboard) and select your Quartz project.
 4. Go to the Settings tab and then click Domains in the sidebar
 5. Enter your subdomain into the field and press Add
+
+## GitLab Pages
+
+You can configure GitLab CI to build and deploy a Quartz 4 project.
+
+In your local Quartz, create a new file `.gitlab-ci.yaml`.
+
+```yaml title=".gitlab-ci.yaml"
+stages:
+  - build
+  - deploy
+
+variables:
+  NODE_VERSION: "18.14"
+
+build:
+  stage: build
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == "v4"'
+  before_script:
+    - apt-get update -q && apt-get install -y nodejs npm
+    - npm install -g n
+    - n $NODE_VERSION
+    - hash -r
+    - npm ci
+  script:
+    - npx prettier --write .
+    - npm run check
+    - npx quartz build
+  artifacts:
+    paths:
+      - public
+  cache:
+    paths:
+      - ~/.npm/
+    key: "${CI_COMMIT_REF_SLUG}-node-${CI_COMMIT_REF_NAME}"
+  tags:
+    - docker
+
+pages:
+  stage: deploy
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == "v4"'
+  script:
+    - echo "Deploying to GitLab Pages..."
+  artifacts:
+    paths:
+      - public
+```
+
+When `.gitlab-ci.yaml` is commited, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy` -> `Pages` in the sidebar.
+
+By default, the page is private and only visible when logged in to a GitLab account with access to the repository but can be opened in the settings under `Deploy` -> `Pages`.

docs/showcase.md

@@ -19,5 +19,6 @@ Want to see what Quartz can do? Here are some cool community gardens:
 - [Vince Imbat's Talahardin](https://vinceimbat.com/)
 - [🧠🌳 Chad's Mind Garden](https://www.chadly.net/)
 - [Pedro MC Fernandes's Topo da Mente](https://www.pmcf.xyz/topo-da-mente/)
+- [Mau Camargo's Notkesto](https://notes.camargomau.com/)
 
 If you want to see your own on here, submit a [Pull Request adding yourself to this file](https://github.com/jackyzha0/quartz/blob/v4/docs/showcase.md)!

quartz/components/TableOfContents.tsx

@@ -20,7 +20,7 @@ function TableOfContents({ fileData, displayClass }: QuartzComponentProps) {
 
   return (
     <div class={`toc ${displayClass ?? ""}`}>
-      <button type="button" id="toc">
+      <button type="button" id="toc" class={fileData.collapseToc ? "collapsed" : ""}>
         <h3>Table of Contents</h3>
         <svg
           xmlns="http://www.w3.org/2000/svg"
@@ -60,7 +60,7 @@ function LegacyTableOfContents({ fileData }: QuartzComponentProps) {
   }
 
   return (
-    <details id="toc" open>
+    <details id="toc" open={!fileData.collapseToc}>
       <summary>
         <h3>Table of Contents</h3>
       </summary>

quartz/components/scripts/toc.inline.ts

@@ -24,8 +24,9 @@ function toggleToc(this: HTMLElement) {
 function setupToc() {
   const toc = document.getElementById("toc")
   if (toc) {
+    const collapsed = toc.classList.contains("collapsed")
     const content = toc.nextElementSibling as HTMLElement
-    content.style.maxHeight = content.scrollHeight + "px"
+    content.style.maxHeight = collapsed ? "0px" : content.scrollHeight + "px"
     toc.removeEventListener("click", toggleToc)
     toc.addEventListener("click", toggleToc, {passive: true})
   }

quartz/plugins/transformers/toc.ts

@@ -8,12 +8,14 @@ export interface Options {
   maxDepth: 1 | 2 | 3 | 4 | 5 | 6
   minEntries: 1
   showByDefault: boolean
+  collapseByDefault: boolean
 }
 
 const defaultOptions: Options = {
   maxDepth: 3,
   minEntries: 1,
   showByDefault: true,
+  collapseByDefault: false,
 }
 
 interface TocEntry {
@@ -54,6 +56,7 @@ export const TableOfContents: QuartzTransformerPlugin<Partial<Options> | undefin
                   ...entry,
                   depth: entry.depth - highestDepth,
                 }))
+                file.data.collapseToc = opts.collapseByDefault
               }
             }
           }
@@ -66,5 +69,6 @@ export const TableOfContents: QuartzTransformerPlugin<Partial<Options> | undefin
 declare module "vfile" {
   interface DataMap {
     toc: TocEntry[]
+    collapseToc: boolean
   }
 }