diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md index d0934ad81..fcc88a7bc 100644 --- a/docs/advanced/making plugins.md +++ b/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: { diff --git a/docs/features/table of contents.md b/docs/features/table of contents.md new file mode 100644 index 000000000..f169b22d2 --- /dev/null +++ b/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` diff --git a/docs/hosting.md b/docs/hosting.md index 01d130fd3..a4ca1ea98 100644 --- a/docs/hosting.md +++ b/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`. diff --git a/docs/showcase.md b/docs/showcase.md index 3774fe3b6..ed9df9f57 100644 --- a/docs/showcase.md +++ b/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)! diff --git a/quartz/components/TableOfContents.tsx b/quartz/components/TableOfContents.tsx index 384772684..1c55f0740 100644 --- a/quartz/components/TableOfContents.tsx +++ b/quartz/components/TableOfContents.tsx @@ -20,7 +20,7 @@ function TableOfContents({ fileData, displayClass }: QuartzComponentProps) { return (
-