diff --git a/docs/cli/index.md b/docs/cli/index.md index 6b654b9..6b0ad92 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -24,7 +24,6 @@ You can run the CLI using `npx quartz`. - [[cli/sync|sync]]: Push and pull changes between your local machine and GitHub. - [[cli/upgrade|upgrade]]: Upgrade the Quartz framework to the latest version. Also available as `npx quartz update`. - [[cli/restore|restore]]: Recover your content folder from the local cache. -- [[cli/migrate|migrate]]: Convert older configuration files to the new YAML format. - [[cli/plugin|plugin]]: Install, add, remove, prune, and configure plugins. Use `plugin install` with flags for lockfile/config sync, updates, and checks. - [[cli/tui|tui]]: Use a terminal interface to manage plugins and layout. diff --git a/docs/cli/migrate.md b/docs/cli/migrate.md deleted file mode 100644 index b44b210..0000000 --- a/docs/cli/migrate.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: quartz migrate ---- - -The `migrate` command helps you transition your project from Quartz 4 to Quartz v5 by converting your configuration files. - -## When to Use - -Use this command if you have an existing Quartz 4 project and want to upgrade to the new YAML-based configuration system introduced in v5. - -## What it Does - -When you run `npx quartz migrate`, the CLI performs several automated steps: - -1. **Read Configuration**: It parses your existing `quartz.config.ts` and `quartz.layout.ts` files. -2. **Map Plugins**: It identifies the plugins you are using and maps them to their v5 equivalents. -3. **Generate YAML**: It creates a new `quartz.config.yaml` file that contains all your settings, theme colors, and plugin configurations. -4. **Backup**: It keeps your old `.ts` files so you can refer back to them if needed. - -```shell -npx quartz migrate -``` - -## Verification - -After running the migration, you should check the following: - -- **Theme Colors**: Ensure your custom colors were correctly transferred to the `theme` section of `quartz.config.yaml`. -- **Plugin Options**: Verify that any custom options you passed to plugins (like `linkClickBehavior`) are present in the new config. -- **Layout**: Check that your component order in the `layout` section matches your previous setup. - -For a comprehensive guide on the entire migration process, including manual steps, see [[getting-started/migrating]]. diff --git a/docs/getting-started/migrating.md b/docs/getting-started/migrating.md index 6b50cbc..555b3ff 100644 --- a/docs/getting-started/migrating.md +++ b/docs/getting-started/migrating.md @@ -7,274 +7,71 @@ aliases: This guide covers migrating to Quartz 5 from previous versions. If you're already on Quartz 5 and want to update to the latest version, see [[getting-started/upgrading|Upgrading Quartz]] instead. -## Migrating from Quartz 4 +If you're new to Quartz entirely, skip this guide and follow the [[getting-started/installation|Installation guide]] instead. -### Overview +## Getting the v5 Branch -Quartz 5 introduces a community plugin system that fundamentally changes how plugins and components are managed. Most plugins that were built into Quartz 4 are now standalone community plugins maintained under the [quartz-community](https://github.com/quartz-community) organization. This guide walks through the changes needed to migrate your configuration. +Whether you're coming from Quartz 4 or Quartz 3, the first step is the same: get the v5 branch onto your machine and push it to your repository. -### What Changed +```bash +# Add the official Quartz repository as a remote called "upstream" (skip if already set) +git remote add upstream https://github.com/jackyzha0/quartz.git -- **Plugin system**: Plugins are now standalone Git repositories, installed via `npx quartz plugin add` -- **Import pattern**: Community plugins use `ExternalPlugin.X()` (from `.quartz/plugins`) instead of `Plugin.X()` (from `./quartz/plugins`) -- **Layout structure**: `quartz.layout.ts` is gone — layout position is now a per-plugin property in `quartz.config.yaml`, with `layout.groups` for flex containers (e.g. toolbar) and `layout.byPageType` for per-page-type overrides -- **Page Types**: A new plugin category for page rendering (content, folder, tag pages) -- **Component references**: In layout files, community components use `Plugin.X()` (from `.quartz/plugins`) instead of `Component.X()` (from `./quartz/components`) +# Fetch the v5 branch from the official repository +git fetch upstream v5 -### Step-by-Step Migration +# Create a local v5 branch from the official one +git checkout -b v5 upstream/v5 -#### 1. Set Up Quartz 5 with a Template +# Install dependencies +npm i -The easiest way to migrate is to use `npx quartz create`, which generates a complete `quartz.config.yaml` from a template with all default plugins pre-configured: - -```shell -npx quartz create --template default --strategy copy --source /path/to/your/content +# Push v5 to your GitHub repository +git push -u origin v5 ``` -Available templates: `default`, `obsidian`, `ttrpg`, `blog`. Pick the one closest to your setup — `obsidian` is recommended if you use an Obsidian vault. +> [!tip] Keeping your old branch +> This does **not** delete your existing v4 (or v3/hugo) branch. You can always switch back with `git checkout v4` if you need to reference your old configuration or content. -> [!tip] Choosing a template -> Each template comes with all 30+ default plugins pre-configured. The main differences are content strategy (OFM support, link resolution) and optional plugins (comments, maps). You can customize everything in `quartz.config.yaml` afterward. +## Setting Up Your Site -After running `create`, install all the plugins referenced in the generated config: +Once you're on v5, run the interactive setup to configure your site and import your content: -```shell +```bash +npx quartz create +``` + +This will prompt you for: + +- A **template** (`default`, `obsidian`, `ttrpg`, `blog`) — pick the one closest to your old setup. `obsidian` is recommended if you use an Obsidian vault. +- A **content strategy** — choose "Copy" and point it to your existing content folder (e.g. your old `content/` directory from v4, or your vault folder). + +> [!hint] Where is my old content? +> If your content was in the `content/` folder on your v4 branch, you can either: +> +> - Copy it somewhere outside the repo **before** switching branches: `cp -r content /tmp/quartz-content` +> - Or reference it from the other branch after switching: the `create` command will copy files from wherever you point it. + +After running `create`, install all plugins referenced in the generated config: + +```bash npx quartz plugin install --from-config ``` -This reads your `quartz.config.yaml` and installs every plugin listed in it. No need to run 30 individual `npx quartz plugin add` commands. +## What Changed in v5 -> [!note] Custom or optional plugins -> If you used optional plugins in v4 (comments, reader-mode, breadcrumbs, recent-notes, citations, etc.), add them after the initial setup: -> -> ```shell -> npx quartz plugin add github:quartz-community/comments -> npx quartz plugin add github:quartz-community/reader-mode -> npx quartz plugin add github:quartz-community/breadcrumbs -> npx quartz plugin add github:quartz-community/recent-notes -> ``` -> -> See [[plugins/index|Plugins]] for the full list of available community plugins. - -> [!info] Alternative: Use `npx quartz migrate` -> If you have an existing `quartz.config.ts` and `quartz.layout.ts` from v4, you can run `npx quartz migrate` instead. This reads your old config files and generates `quartz.config.yaml` with your existing settings. You'll still need to run `npx quartz plugin install --from-config` afterward to install the plugins. See [[cli/migrate|quartz migrate]] for details. - -#### 2. Update quartz.config.yaml - -**Before (v4):** - -```ts title="quartz.config.ts" -import * as Plugin from "./quartz/plugins" - -plugins: { - transformers: [ - Plugin.FrontMatter(), - Plugin.CreatedModifiedDate({ priority: ["frontmatter", "git", "filesystem"] }), - Plugin.Latex({ renderEngine: "katex" }), - ], - filters: [Plugin.RemoveDrafts()], - emitters: [ - Plugin.AliasRedirects(), - Plugin.ComponentResources(), - Plugin.ContentPage(), - Plugin.FolderPage(), - Plugin.TagPage(), - Plugin.ContentIndex({ enableSiteMap: true, enableRSS: true }), - Plugin.Assets(), - Plugin.Static(), - Plugin.NotFoundPage(), - ], -} -``` - -**After (v5):** - -```yaml title="quartz.config.yaml" -plugins: - - source: github:quartz-community/note-properties - enabled: true - options: - delimiters: "---" - language: yaml - order: 5 - - source: github:quartz-community/created-modified-date - enabled: true - options: - priority: - - frontmatter - - git - - filesystem - order: 10 - - source: github:quartz-community/latex - enabled: true - options: - renderEngine: katex - order: 80 - - source: github:quartz-community/remove-draft - enabled: true - - source: github:quartz-community/alias-redirects - enabled: true - - source: github:quartz-community/content-index - enabled: true - options: - enableSiteMap: true - enableRSS: true - - source: github:quartz-community/favicon - enabled: true - - source: github:quartz-community/og-image - enabled: true - - source: github:quartz-community/cname - enabled: true - - source: github:quartz-community/content-page - enabled: true - - source: github:quartz-community/folder-page - enabled: true - - source: github:quartz-community/tag-page - enabled: true - # ... more plugins -``` +Quartz 5 introduces a community plugin system that fundamentally changes how plugins and components are managed. Most plugins that were built into Quartz 4 are now standalone community plugins maintained under the [quartz-community](https://github.com/quartz-community) organization. Key changes: -- Plugins are now referenced by their GitHub source (`github:org/repo`) -- Plugin type (transformer, filter, emitter, pageType) is determined by the plugin's manifest, not by which array you place it in -- Execution order is controlled by the `order` field (lower numbers run first) -- Each plugin entry has `enabled`, `options`, `order`, and optionally `layout` fields -- Install community plugins with `npx quartz plugin add github:quartz-community/` +- **Configuration format**: TypeScript (`quartz.config.ts`, `quartz.layout.ts`) → YAML (`quartz.config.yaml`) +- **Plugin system**: Plugins are now standalone Git repositories, installed via `npx quartz plugin add` +- **Import pattern**: Community plugins use `ExternalPlugin.X()` (from `.quartz/plugins`) instead of `Plugin.X()` (from `./quartz/plugins`) +- **Layout structure**: `quartz.layout.ts` is gone — layout position is now a per-plugin property in `quartz.config.yaml` +- **Page types**: A new plugin category for page rendering (content, folder, tag pages) -#### 3. Update layout configuration - -**Before (v4):** - -```ts title="quartz.layout.ts" -import * as Component from "./quartz/components" - -export const sharedPageComponents: SharedLayout = { - head: Component.Head(), - header: [], - afterBody: [], - footer: Component.Footer({ links: { ... } }), -} - -export const defaultContentPageLayout: PageLayout = { - beforeBody: [Component.Breadcrumbs(), Component.ArticleTitle(), Component.ContentMeta(), Component.TagList()], - left: [Component.PageTitle(), Component.Search(), Component.Darkmode(), Component.Explorer()], - right: [Component.Graph(), Component.TableOfContents(), Component.Backlinks()], -} -``` - -**After (v5):** - -```yaml title="quartz.config.yaml" -plugins: - - source: github:quartz-community/breadcrumbs - enabled: true - layout: - position: beforeBody - priority: 5 - - source: github:quartz-community/article-title - enabled: true - layout: - position: beforeBody - priority: 10 - - source: github:quartz-community/content-meta - enabled: true - layout: - position: beforeBody - priority: 20 - - source: github:quartz-community/tag-list - enabled: true - layout: - position: beforeBody - priority: 30 - - source: github:quartz-community/page-title - enabled: true - layout: - position: left - priority: 10 - - source: github:quartz-community/search - enabled: true - layout: - position: left - priority: 20 - - source: github:quartz-community/darkmode - enabled: true - layout: - position: left - priority: 30 - - source: github:quartz-community/explorer - enabled: true - layout: - position: left - priority: 50 - - source: github:quartz-community/graph - enabled: true - layout: - position: right - priority: 10 - - source: github:quartz-community/backlinks - enabled: true - layout: - position: right - priority: 30 - - source: github:quartz-community/footer - enabled: true - options: - links: - GitHub: https://github.com/jackyzha0/quartz - Discord Community: https://discord.gg/cRFFHYye7t - -layout: - byPageType: - content: {} - folder: - exclude: - - reader-mode - positions: - right: [] - tag: - exclude: - - reader-mode - positions: - right: [] - "404": - positions: - beforeBody: [] - left: [] - right: [] -``` - -Key changes: - -- Layout position is now a property on each plugin entry (`layout.position`, `layout.priority`) -- `sharedPageComponents` is gone — all layout is plugin-driven -- Per-page-type overrides live in the `layout.byPageType` section -- Empty arrays (`[]`) clear a position for that page type -- The `exclude` field removes specific plugins from a page type - -#### 4. Update CI/CD - -Add `npx quartz plugin install` to your build pipeline, before `npx quartz build`. This installs plugins from the lockfile at their pinned versions. - -If your CI uses `quartz.config.default.yaml` (or contributors may add plugins to config without updating the lockfile), also run `npx quartz plugin install --from-config` to install any config-referenced plugins that are missing from the lockfile: - -```shell -npx quartz plugin install # install pinned plugins from lockfile -npx quartz plugin install --from-config # install any config-referenced plugins not yet in lockfile -npx quartz build -``` - -See [[hosting]] for detailed CI/CD examples and [[ci-cd]] for advanced configuration. - -#### 5. Commit and Deploy - -```shell -git add quartz.config.yaml quartz.lock.json -git commit -m "chore: migrate to Quartz 5 plugin system" -``` - -> [!tip] Cleaning up leftover plugins -> After migrating, you may have plugins installed from v4 that are no longer in your v5 config. Run `npx quartz plugin prune` to remove them. Use `--dry-run` first to preview what would be removed. +> [!note] Most users don't need to worry about these details +> If you used the default Quartz 4 configuration (or only changed settings that `npx quartz create` prompts for), the setup wizard handles everything. The details below are for users who had custom plugin configurations. ### Plugin Reference Table @@ -315,45 +112,79 @@ Component layout mapping: | `Component.Head()` | `Component.Head()` (unchanged, internal) | | `Component.Spacer()` | `Plugin.Spacer()` | ---- +## Updating Your CI/CD -## Migrating from Quartz 3 +Quartz 5 requires plugins to be installed before building. Add a plugin install step and (optionally) caching to your CI pipeline. -As you already have Quartz locally, you don't need to fork or clone it again. Simply just checkout the v4 branch, install the dependencies, restore plugins, and import your old vault. Then follow the [Quartz 4 migration steps above](#migrating-from-quartz-4) to get to v5. +Here's the recommended pattern, based on the project's own GitHub Actions: -```bash -git fetch -git checkout v4 -git pull upstream v4 -npm i -npx quartz plugin install -npx quartz create +```yaml +- name: Cache dependencies + uses: actions/cache@v5 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + +- name: Cache Quartz plugins + uses: actions/cache@v5 + with: + path: .quartz/plugins + key: ${{ runner.os }}-plugins-${{ hashFiles('quartz.lock.json') }} + restore-keys: | + ${{ runner.os }}-plugins- + +- run: npm ci + +- name: Install Quartz plugins + run: npx quartz plugin install + +- name: Build Quartz + run: npx quartz build ``` -If you get an error like `fatal: 'upstream' does not appear to be a git repository`, make sure you add `upstream` as a remote origin: +The plugin cache uses `quartz.lock.json` as the cache key, so plugins are only re-downloaded when the lockfile changes. + +For non-GitHub CI providers (Cloudflare, Vercel, Netlify), the build command should be: ```shell -git remote add upstream https://github.com/jackyzha0/quartz.git +npx quartz plugin install && npx quartz build ``` -When running `npx quartz create`, you will be prompted as to how to initialize your content folder. Here, you can choose to import or link your previous content folder and Quartz should work just as you expect it to. +See [[hosting]] for provider-specific setup details. -> [!note] -> If the existing content folder you'd like to use is at the _same_ path on a different branch, clone the repo again somewhere at a _different_ path in order to use it. +## Setting Your Default Branch to v5 + +After verifying your site builds and deploys correctly, update your repository's default branch to `v5`: + +1. Go to your repository on GitHub +2. Navigate to **Settings** → **General** +3. Under **Default branch**, click the switch icon next to your current default branch +4. Select `v5` from the dropdown and click **Update** +5. Confirm the change + +This ensures that new clones, pull requests, and GitHub Pages deployments all target v5 by default. Your old v4 branch remains available for reference. + +> [!warning] Update your CI triggers +> If your CI workflow triggers on a specific branch (e.g. `branches: [v4]`), make sure to update it to `v5`. See the [[hosting]] guide for examples. + +## Notes for Quartz 3 Users + +If you're coming from Quartz 3 (the Hugo-based version), follow the same steps above — get the v5 branch, run `npx quartz create`, and import your content. There is no need to go through Quartz 4 first. ### Key changes from Quartz 3 -1. **Removing Hugo and `hugo-obsidian`**: Hugo worked well for earlier versions of Quartz but it also made it hard for people outside of the Golang and Hugo communities to fully understand what Quartz was doing under the hood and be able to properly customize it to their needs. Quartz now uses a Node-based static-site generation process which should lead to much more helpful error messages and an overall smoother user experience. -2. **Full-hot reload**: The many rough edges of how `hugo-obsidian` integrated with Hugo meant that watch mode didn't re-trigger `hugo-obsidian` to update the content index. This lead to a lot of weird cases where the watch mode output wasn't accurate. Quartz now uses a cohesive parse, filter, and emit pipeline which gets run on every change so hot-reloads are always accurate. -3. **Replacing Go template syntax with JSX**: Quartz 3 used [Go templates](https://pkg.go.dev/text/template) to create layouts for pages. However, the syntax isn't great for doing any sort of complex rendering (like [text processing](https://github.com/jackyzha0/quartz/blob/hugo/layouts/partials/textprocessing.html)) and it got very difficult to make any meaningful layout changes to Quartz 3. Quartz now uses an extension of JavaScript syntax called JSX which allows you to write layout code that looks like HTML in JavaScript which is significantly easier to understand and maintain. -4. **A new extensible [[configuration]] and [[configuration#Plugins|plugin]] system**: Quartz 3 was hard to configure without technical knowledge of how Hugo's partials worked. Extensions were even hard to make. Quartz 5's configuration and plugin system is designed to be extended by users while making updating to new versions of Quartz easy. +1. **Hugo is gone**: Quartz now uses a Node-based static-site generation process. No more Go templates or `hugo-obsidian`. +2. **Full hot-reload**: The development server (`npx quartz build --serve`) re-processes all content on every change. +3. **JSX instead of Go templates**: Layout components are written in JSX (JavaScript XML), which is significantly easier to customize. +4. **New plugin system**: See [[configuration#Plugins|Plugins]] for details on the extensible plugin architecture. ### Things to update -- You will need to update your deploy scripts. See the [[hosting]] guide for more details. -- Ensure that your default branch on GitHub is updated from `hugo` to `v5`. -- [[folder and tag listings|Folder and tag listings]] have also changed. - - Folder descriptions should go under `content//index.md` where `` is the name of the folder. - - Tag descriptions should go under `content/tags/.md` where `` is the name of the tag. -- Some HTML layout may not be the same between Quartz 3 and Quartz 5. If you depended on a particular HTML hierarchy or class names, you may need to update your custom CSS to reflect these changes. -- If you customized the layout of Quartz 3, you may need to translate these changes from Go templates back to JSX as Quartz 5 no longer uses Hugo. For components, check out the guide on [[creating components]] for more details on this. +- Update your deploy scripts — see the [[hosting]] guide. +- Ensure your default branch on GitHub is updated to `v5`. +- [[folder and tag listings|Folder and tag listings]] have changed: + - Folder descriptions go under `content//index.md` + - Tag descriptions go under `content/tags/.md` +- Custom CSS may need updates if you depended on specific HTML hierarchy or class names from Quartz 3. diff --git a/docs/hosting.md b/docs/hosting.md index a3ebe99..4cf55d4 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -61,17 +61,31 @@ concurrency: jobs: build: - runs-on: ubuntu-22.04 + runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 with: fetch-depth: 0 # Fetch all history for git info - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v6 with: - node-version: 22 + node-version: 24 + - name: Cache dependencies + uses: actions/cache@v5 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- + - name: Cache Quartz plugins + uses: actions/cache@v5 + with: + path: .quartz/plugins + key: ${{ runner.os }}-plugins-${{ hashFiles('quartz.lock.json') }} + restore-keys: | + ${{ runner.os }}-plugins- - name: Install Dependencies run: npm ci - - name: Restore Quartz plugins + - name: Install Quartz plugins run: npx quartz plugin install - name: Build Quartz run: npx quartz build