basic

Author: dnbln

.github/dependabot.yml

@@ -1,11 +1,20 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-
 version: 2
 updates:
   - package-ecosystem: "npm"
     directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      production-dependencies:
+        applies-to: "version-updates"
+        patterns:
+          - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      ci-dependencies:
+        applies-to: "version-updates"
+        patterns:
+          - "*"

.github/workflows/ci.yaml

@@ -0,0 +1,72 @@
+name: Build and Test
+
+on:
+  pull_request:
+    branches:
+      - v4
+  push:
+    branches:
+      - v4
+  workflow_dispatch:
+
+jobs:
+  build-and-test:
+    if: ${{ github.repository == 'jackyzha0/quartz' }}
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - run: npm ci
+
+      - name: Check types and style
+        run: npm run check
+
+      - name: Test
+        run: npm test
+
+      - name: Ensure Quartz builds, check bundle info
+        run: npx quartz build --bundleInfo
+
+  publish-tag:
+    if: ${{ github.repository == 'jackyzha0/quartz' && github.ref == 'refs/heads/v4' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Get package version
+        run: node -p -e '`PACKAGE_VERSION=${require("./package.json").version}`' >> $GITHUB_ENV
+      - name: Create release tag
+        uses: pkgdeps/git-tag-action@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          github_repo: ${{ github.repository }}
+          version: ${{ env.PACKAGE_VERSION }}
+          git_commit_sha: ${{ github.sha }}
+          git_tag_prefix: "v"

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

@@ -0,0 +1,88 @@
+name: Docker build & push image
+
+on:
+  push:
+    branches: [v4]
+    tags: ["v*"]
+  pull_request:
+    branches: [v4]
+    paths:
+      - .github/workflows/docker-build-push.yaml
+      - quartz/**
+  workflow_dispatch:
+
+jobs:
+  build:
+    if: ${{ github.repository == 'jackyzha0/quartz' }} # Comment this out if you want to publish your own images on a fork!
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set lowercase repository owner environment variable
+        run: |
+          echo "OWNER_LOWERCASE=${OWNER,,}" >> ${GITHUB_ENV}
+        env:
+          OWNER: "${{ github.repository_owner }}"
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Inject slug/short variables
+        uses: rlespinasse/[email protected]
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          install: true
+          driver-opts: |
+            image=moby/buildkit:master
+            network=host
+      - name: Install cosign
+        if: github.event_name != 'pull_request'
+        uses: sigstore/[email protected]
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        if: github.event_name != 'pull_request'
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata tags and labels on PRs
+        if: github.event_name == 'pull_request'
+        id: meta-pr
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ env.OWNER_LOWERCASE }}/quartz
+          tags: |
+            type=raw,value=sha-${{ env.GITHUB_SHA_SHORT }}
+          labels: |
+            org.opencontainers.image.source="https://github.com/${{ github.repository_owner }}/quartz"
+      - name: Extract metadata tags and labels for main, release or tag
+        if: github.event_name != 'pull_request'
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          flavor: |
+            latest=auto
+          images: ghcr.io/${{ env.OWNER_LOWERCASE }}/quartz
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}.{{minor}}.{{patch}}
+            type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+            type=raw,value=sha-${{ env.GITHUB_SHA_SHORT }}
+          labels: |
+            maintainer=${{ github.repository_owner }}
+            org.opencontainers.image.source="https://github.com/${{ github.repository_owner }}/quartz"
+
+      - name: Build and push Docker image
+        id: build-and-push
+        uses: docker/build-push-action@v6
+        with:
+          push: ${{ github.event_name != 'pull_request' }}
+          build-args: |
+            GIT_SHA=${{ env.GITHUB_SHA }}
+            DOCKER_LABEL=sha-${{ env.GITHUB_SHA_SHORT }}
+          tags: ${{ steps.meta.outputs.tags || steps.meta-pr.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels || steps.meta-pr.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha

.node-version

@@ -0,0 +1 @@
+v20.9.0

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-slim as builder
+FROM node:20-slim AS builder
 WORKDIR /usr/src/app
 COPY package.json .
 COPY package-lock.json* .

docs/advanced/creating components.md

@@ -129,11 +129,11 @@ export default (() => {
     return <button id="btn">Click me</button>
   }
 
-  YourComponent.beforeDOM = `
+  YourComponent.beforeDOMLoaded = `
   console.log("hello from before the page loads!")
   `
 
-  YourComponent.afterDOM = `
+  YourComponent.afterDOMLoaded = `
   document.getElementById('btn').onclick = () => {
     alert('button clicked!')
   }
@@ -180,7 +180,7 @@ export default (() => {
     return <button id="btn">Click me</button>
   }
 
-  YourComponent.afterDOM = script
+  YourComponent.afterDOMLoaded = script
   return YourComponent
 }) satisfies QuartzComponentConstructor
 ```

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: [
             {
@@ -260,19 +262,19 @@ export const ContentPage: QuartzEmitterPlugin = () => {
     ...defaultContentPageLayout,
     pageBody: Content(),
   }
-  const { head, header, beforeBody, pageBody, left, right, footer } = layout
+  const { head, header, beforeBody, pageBody, afterBody, left, right, footer } = layout
   return {
     name: "ContentPage",
     getQuartzComponents() {
-      return [head, ...header, ...beforeBody, pageBody, ...left, ...right, footer]
+      return [head, ...header, ...beforeBody, pageBody, ...afterBody, ...left, ...right, footer]
     },
     async emit(ctx, content, resources, emit): Promise<FilePath[]> {
       const cfg = ctx.cfg.configuration
       const fps: FilePath[] = []
       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/advanced/paths.md

@@ -48,4 +48,4 @@ Here are the main types of slugs with a rough description of each type of path:
 - `SimpleSlug`: cannot be relative and shouldn't have `/index` as an ending or a file extension. It _can_ however have a trailing slash to indicate a folder path.
 - `RelativeURL`: must start with `.` or `..` to indicate it's a relative URL. Shouldn't have `/index` as an ending or a file extension but can contain a trailing slash.
 
-To get a clearer picture of how these relate to each other, take a look at the path tests in `quartz/path.test.ts`.
+To get a clearer picture of how these relate to each other, take a look at the path tests in `quartz/util/path.test.ts`.

docs/authoring content.md

@@ -29,6 +29,7 @@ Some common frontmatter fields that are natively supported by Quartz:
 
 - `title`: Title of the page. If it isn't provided, Quartz will use the name of the file as the title.
 - `description`: Description of the page used for link previews.
+- `permalink`: A custom URL for the page that will remain constant even if the path to the file changes.
 - `aliases`: Other names for this note. This is a list of strings.
 - `tags`: Tags for this note.
 - `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz.

docs/build.md

@@ -21,3 +21,7 @@ This will start a local web server to run your Quartz on your computer. Open a w
 > - `--serve`: run a local hot-reloading server to preview your Quartz
 > - `--port`: what port to run the local preview server on
 > - `--concurrency`: how many threads to use to parse notes
+
+> [!warning] Not to be used for production
+> Serve mode is intended for local previews only.
+> For production workloads, see the page on [[hosting]].