mirror of
https://github.com/jackyzha0/quartz.git
synced 2026-03-21 21:45:42 -05:00
docs: Quartz v5
This commit is contained in:
saberzero1
parent
65eca6ca52
commit
e6255b24be
@ -1,3 +1,10 @@
|
||||
---
|
||||
title: "Advanced"
|
||||
---
|
||||
|
||||
This section covers advanced topics for users who want to extend or deeply customize Quartz.
|
||||
|
||||
- **[[architecture]]** — How Quartz works under the hood: the parse, filter, and emit pipeline
|
||||
- **[[making plugins]]** — Build your own transformer, filter, emitter, or component plugin
|
||||
- **[[creating components]]** — Create custom layout components with JSX
|
||||
- **[[paths]]** — How Quartz resolves and transforms file paths
|
||||
|
||||
@ -1,27 +0,0 @@
|
||||
---
|
||||
title: "Building your Quartz"
|
||||
---
|
||||
|
||||
Once you've [[index#🪴 Get Started|initialized]] Quartz, let's see what it looks like locally:
|
||||
|
||||
```bash
|
||||
npx quartz build --serve
|
||||
```
|
||||
|
||||
This will start a local web server to run your Quartz on your computer. Open a web browser and visit `http://localhost:8080/` to view it.
|
||||
|
||||
> [!hint] Flags and options
|
||||
> For full help options, you can run `npx quartz build --help`.
|
||||
>
|
||||
> Most of these have sensible defaults but you can override them if you have a custom setup:
|
||||
>
|
||||
> - `-d` or `--directory`: the content folder. This is normally just `content`
|
||||
> - `-v` or `--verbose`: print out extra logging information
|
||||
> - `-o` or `--output`: the output folder. This is normally just `public`
|
||||
> - `--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]].
|
||||
65
docs/cli/build.md
Normal file
65
docs/cli/build.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: quartz build
|
||||
aliases:
|
||||
- build
|
||||
---
|
||||
|
||||
The `build` command transforms your Markdown content into a static HTML website. It processes your files through the configured plugins and outputs the final site to a directory of your choice.
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Shorthand | Description | Default |
|
||||
| ----------------- | --------- | --------------------------------------------------------- | ----------------- |
|
||||
| `--directory` | `-d` | The directory containing your Quartz project | Current directory |
|
||||
| `--verbose` | `-v` | Enable detailed logging for debugging | `false` |
|
||||
| `--output` | `-o` | The directory where the built site will be saved | `public` |
|
||||
| `--serve` | | Start a local development server | `false` |
|
||||
| `--watch` | | Rebuild the site when files change | `false` |
|
||||
| `--port` | | The port for the development server | `8080` |
|
||||
| `--wsPort` | | The port for the WebSocket hot-reload server | `3001` |
|
||||
| `--baseDir` | | Set a base directory for the site (e.g. for GitHub Pages) | `/` |
|
||||
| `--remoteDevHost` | | The hostname to use for the development server | `localhost` |
|
||||
| `--bundleInfo` | | Output a JSON file with bundle size information | `false` |
|
||||
| `--concurrency` | | Number of worker threads to use for building | CPU core count |
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Build
|
||||
|
||||
Generate your site into the `public` folder.
|
||||
|
||||
```shell
|
||||
npx quartz build
|
||||
```
|
||||
|
||||
### Development Mode
|
||||
|
||||
Start a local server and watch for changes. This is the most common way to preview your site while writing.
|
||||
|
||||
```shell
|
||||
npx quartz build --serve
|
||||
```
|
||||
|
||||
### Custom Output and Port
|
||||
|
||||
Build to a specific folder and run the server on a different port.
|
||||
|
||||
```shell
|
||||
npx quartz build --serve --output dist --port 3000
|
||||
```
|
||||
|
||||
### Performance Tuning
|
||||
|
||||
If you have a very large vault, you can limit the number of concurrent workers to save memory.
|
||||
|
||||
```shell
|
||||
npx quartz build --concurrency 2
|
||||
```
|
||||
|
||||
## Development Server
|
||||
|
||||
The `--serve` flag starts a local web server. This server is intended for development and previewing only. It is not designed for production use. For information on how to deploy your site, see [[hosting]].
|
||||
|
||||
### Hot Reloading
|
||||
|
||||
When running with `--serve`, Quartz automatically enables `--watch`. It uses a WebSocket connection (on the port specified by `--wsPort`) to notify your browser when a file has changed. The browser will then automatically refresh to show the latest version of your content.
|
||||
51
docs/cli/create.md
Normal file
51
docs/cli/create.md
Normal file
@ -0,0 +1,51 @@
|
||||
---
|
||||
title: quartz create
|
||||
---
|
||||
|
||||
The `create` command initializes a new Quartz project. It helps you set up your content folder and choose how Quartz should handle your Markdown files.
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Shorthand | Description |
|
||||
| ------------- | --------- | --------------------------------------------------------------------- |
|
||||
| `--directory` | `-d` | The directory where Quartz will be initialized |
|
||||
| `--source` | `-s` | The source directory of your Markdown files |
|
||||
| `--strategy` | `-X` | How to handle the source files (`new`, `copy`, or `symlink`) |
|
||||
| `--links` | `-l` | How to resolve internal links (`absolute`, `shortest`, or `relative`) |
|
||||
| `--verbose` | `-v` | Enable detailed logging |
|
||||
|
||||
## Strategies
|
||||
|
||||
When you run `quartz create`, you must choose a strategy for your content:
|
||||
|
||||
- **new**: Creates a fresh, empty content folder. Use this if you are starting a new project from scratch.
|
||||
- **copy**: Copies all files from your source directory into the Quartz content folder. This is the safest option for existing vaults as it doesn't touch your original files.
|
||||
- **symlink**: Creates a symbolic link from the Quartz content folder to your source directory. Any changes you make in your source directory (e.g. in Obsidian) will be immediately reflected in Quartz.
|
||||
- **move**: Moves your files from the source directory into the Quartz content folder.
|
||||
|
||||
## Link Resolution
|
||||
|
||||
Quartz needs to know how to interpret the internal links in your Markdown files:
|
||||
|
||||
- **shortest**: Resolves links to the closest matching file name. This is the default for Obsidian.
|
||||
- **absolute**: Resolves links relative to the root of your content folder.
|
||||
- **relative**: Resolves links relative to the current file's location.
|
||||
|
||||
## Interactive Walkthrough
|
||||
|
||||
If you run `npx quartz create` without any arguments, it will guide you through an interactive setup:
|
||||
|
||||
1. **Choose a name**: Enter the name of your project.
|
||||
2. **Select a strategy**: Choose between `new`, `copy`, or `symlink`.
|
||||
3. **Select link resolution**: Choose how your links are formatted.
|
||||
4. **Finish**: Quartz will set up the directory structure and install necessary dependencies.
|
||||
|
||||
## Example: Importing an Obsidian Vault
|
||||
|
||||
To create a Quartz project that links directly to an existing Obsidian vault:
|
||||
|
||||
```shell
|
||||
npx quartz create --strategy symlink --source ~/Documents/MyVault --links shortest
|
||||
```
|
||||
|
||||
This command tells Quartz to look at your vault in `~/Documents/MyVault`, use symbolic links so changes are synced, and use the `shortest` link resolution that Obsidian expects.
|
||||
44
docs/cli/index.md
Normal file
44
docs/cli/index.md
Normal file
@ -0,0 +1,44 @@
|
||||
---
|
||||
title: CLI Reference
|
||||
---
|
||||
|
||||
The Quartz CLI is the primary way to interact with your Quartz project. It provides commands for creating new projects, building static sites, syncing with GitHub, and managing plugins.
|
||||
|
||||
You can run the CLI using `npx quartz`.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Description | Example |
|
||||
| -------- | ------------------------------------- | ------------------------ |
|
||||
| `create` | Initialize a new Quartz project | `npx quartz create` |
|
||||
| `build` | Generate static HTML files | `npx quartz build` |
|
||||
| `sync` | Sync content with GitHub | `npx quartz sync` |
|
||||
| `update` | Update Quartz to the latest version | `npx quartz update` |
|
||||
| `plugin` | Manage Quartz plugins | `npx quartz plugin list` |
|
||||
| `tui` | Launch the interactive plugin manager | `npx quartz tui` |
|
||||
|
||||
## Commands
|
||||
|
||||
- [[cli/create|create]]: Initialize a new Quartz project from scratch or an existing vault.
|
||||
- [[cli/build|build]]: Build your Quartz site into static HTML. Includes a development server.
|
||||
- [[cli/sync|sync]]: Push and pull changes between your local machine and GitHub.
|
||||
- [[cli/update|update]]: Pull the latest changes from the official Quartz repository.
|
||||
- [[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, and configure plugins from the command line.
|
||||
- [[cli/tui|tui]]: Use a terminal interface to manage plugins and layout.
|
||||
|
||||
## Help and Versioning
|
||||
|
||||
To see a full list of available flags for any command, use the `--help` flag.
|
||||
|
||||
```shell
|
||||
npx quartz --help
|
||||
npx quartz build --help
|
||||
```
|
||||
|
||||
To check which version of Quartz you are currently running, use the `--version` flag.
|
||||
|
||||
```shell
|
||||
npx quartz --version
|
||||
```
|
||||
32
docs/cli/migrate.md
Normal file
32
docs/cli/migrate.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
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]].
|
||||
120
docs/cli/plugin.md
Normal file
120
docs/cli/plugin.md
Normal file
@ -0,0 +1,120 @@
|
||||
---
|
||||
title: quartz plugin
|
||||
---
|
||||
|
||||
The `plugin` command is the heart of the Quartz v5 plugin management system. it allows you to install, configure, and update plugins directly from the command line.
|
||||
|
||||
All plugins are stored in the `.quartz/plugins/` directory, and their versions are tracked in `quartz.lock.json`.
|
||||
|
||||
## Subcommands
|
||||
|
||||
### list
|
||||
|
||||
List all currently installed plugins and their versions.
|
||||
|
||||
```shell
|
||||
npx quartz plugin list
|
||||
```
|
||||
|
||||
### add
|
||||
|
||||
Add a new plugin from a Git repository.
|
||||
|
||||
```shell
|
||||
npx quartz plugin add github:username/repo
|
||||
```
|
||||
|
||||
### remove
|
||||
|
||||
Remove an installed plugin.
|
||||
|
||||
```shell
|
||||
npx quartz plugin remove plugin-name
|
||||
```
|
||||
|
||||
### install
|
||||
|
||||
Install all plugins listed in your `quartz.lock.json` file. This is useful when setting up the project on a new machine.
|
||||
|
||||
```shell
|
||||
npx quartz plugin install
|
||||
```
|
||||
|
||||
### update
|
||||
|
||||
Update specific plugins or all plugins to their latest versions.
|
||||
|
||||
```shell
|
||||
npx quartz plugin update plugin-name
|
||||
npx quartz plugin update # updates all
|
||||
```
|
||||
|
||||
### restore
|
||||
|
||||
Restore plugins to the exact versions specified in the lockfile. Unlike `install`, this will downgrade plugins if the lockfile specifies an older version. This is recommended for CI/CD environments.
|
||||
|
||||
```shell
|
||||
npx quartz plugin restore
|
||||
```
|
||||
|
||||
### enable / disable
|
||||
|
||||
Toggle a plugin's status in your `quartz.config.yaml` without removing its files.
|
||||
|
||||
```shell
|
||||
npx quartz plugin enable plugin-name
|
||||
npx quartz plugin disable plugin-name
|
||||
```
|
||||
|
||||
### config
|
||||
|
||||
View or modify the configuration for a specific plugin.
|
||||
|
||||
```shell
|
||||
# View config
|
||||
npx quartz plugin config plugin-name
|
||||
|
||||
# Set a value
|
||||
npx quartz plugin config plugin-name --set key=value
|
||||
```
|
||||
|
||||
### check
|
||||
|
||||
Check if any of your installed plugins have updates available.
|
||||
|
||||
```shell
|
||||
npx quartz plugin check
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Adding and Enabling a Plugin
|
||||
|
||||
To add a new plugin and start using it:
|
||||
|
||||
1. Add the plugin: `npx quartz plugin add github:quartz-community/example`
|
||||
2. Enable it: `npx quartz plugin enable example`
|
||||
|
||||
### Updating Everything
|
||||
|
||||
To keep your plugins fresh:
|
||||
|
||||
```shell
|
||||
npx quartz plugin update
|
||||
```
|
||||
|
||||
### Managing Configuration
|
||||
|
||||
If you want to change a plugin setting without opening the YAML file:
|
||||
|
||||
```shell
|
||||
npx quartz plugin config explorer --set useSavedState=true
|
||||
```
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
Running the plugin command without any subcommand will launch the [[cli/tui|TUI]], which provides a visual interface for all these operations.
|
||||
|
||||
```shell
|
||||
npx quartz plugin
|
||||
```
|
||||
29
docs/cli/restore.md
Normal file
29
docs/cli/restore.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: quartz restore
|
||||
---
|
||||
|
||||
The `restore` command is a safety mechanism that allows you to recover your content folder from a local cache.
|
||||
|
||||
## When to Use
|
||||
|
||||
You should use `restore` if:
|
||||
|
||||
- A `quartz update` failed and corrupted your content.
|
||||
- You accidentally deleted files in your content folder.
|
||||
- You encountered complex merge conflicts that you want to undo.
|
||||
|
||||
## How it Works
|
||||
|
||||
Quartz maintains a hidden cache of your content folder. Every time you run certain commands, Quartz ensures that a backup of your Markdown files exists. The `restore` command simply copies these files back into your main content directory.
|
||||
|
||||
```shell
|
||||
npx quartz restore
|
||||
```
|
||||
|
||||
## Example Workflow
|
||||
|
||||
If an update fails and leaves your project in a broken state:
|
||||
|
||||
1. **Restore**: Run `npx quartz restore` to bring back your content.
|
||||
2. **Clean**: Use Git to reset any other broken code files.
|
||||
3. **Retry**: Attempt the update again or manually apply the changes you need.
|
||||
74
docs/cli/sync.md
Normal file
74
docs/cli/sync.md
Normal file
@ -0,0 +1,74 @@
|
||||
---
|
||||
title: quartz sync
|
||||
---
|
||||
|
||||
The `sync` command automates the process of pushing your local changes to GitHub and pulling updates from your remote repository. It simplifies the Git workflow for users who want to keep their site updated without running manual Git commands.
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Shorthand | Description | Default |
|
||||
| ------------- | --------- | ------------------------------------ | ----------------- |
|
||||
| `--directory` | `-d` | The directory of your Quartz project | Current directory |
|
||||
| `--verbose` | `-v` | Enable detailed logging | `false` |
|
||||
| `--commit` | | Whether to commit changes | `true` |
|
||||
| `--no-commit` | | Skip committing changes | `false` |
|
||||
| `--message` | `-m` | Custom commit message | `update content` |
|
||||
| `--push` | | Whether to push changes to remote | `true` |
|
||||
| `--no-push` | | Skip pushing changes | `false` |
|
||||
| `--pull` | | Whether to pull changes from remote | `true` |
|
||||
| `--no-pull` | | Skip pulling changes | `false` |
|
||||
|
||||
## Workflow
|
||||
|
||||
When you run `npx quartz sync`, Quartz performs the following steps:
|
||||
|
||||
1. **Pull**: It fetches and merges changes from your remote GitHub repository.
|
||||
2. **Add**: It stages all new and modified files in your project.
|
||||
3. **Commit**: It creates a new commit with your changes.
|
||||
4. **Push**: It sends your new commit to GitHub.
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Regular Sync
|
||||
|
||||
The most common usage is to simply run the command with no flags. This pulls, commits, and pushes everything.
|
||||
|
||||
```shell
|
||||
npx quartz sync
|
||||
```
|
||||
|
||||
### First Sync
|
||||
|
||||
If you have just set up a new repository and haven't pushed anything yet, you might want to skip the pull step.
|
||||
|
||||
```shell
|
||||
npx quartz sync --no-pull
|
||||
```
|
||||
|
||||
### Custom Commit Message
|
||||
|
||||
You can provide a more descriptive message for your changes.
|
||||
|
||||
```shell
|
||||
npx quartz sync --message "add new notes about gardening"
|
||||
```
|
||||
|
||||
### Sync from Another Device
|
||||
|
||||
If you are working on a different computer and just want to get the latest changes without pushing anything back yet.
|
||||
|
||||
```shell
|
||||
npx quartz sync --no-push --no-commit
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Git Buffer
|
||||
|
||||
If you have a very large number of changes, Git might occasionally fail due to buffer limits. If this happens, try syncing smaller batches of files or increasing your Git post buffer size.
|
||||
|
||||
### Autostash
|
||||
|
||||
Quartz uses `git pull --rebase --autostash` internally. This means if you have unstaged changes when you run `sync`, Quartz will temporarily hide them, pull the remote changes, and then bring your changes back. If a conflict occurs during this process, you will need to resolve it manually using standard Git tools.
|
||||
|
||||
For more information on initial setup, see [[getting-started/installation]].
|
||||
64
docs/cli/tui.md
Normal file
64
docs/cli/tui.md
Normal file
@ -0,0 +1,64 @@
|
||||
---
|
||||
title: quartz tui
|
||||
---
|
||||
|
||||
The `tui` command launches an interactive terminal user interface for managing your Quartz project. It provides a visual way to manage plugins, arrange your site layout, and edit general settings.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To use the TUI, you must have the following:
|
||||
|
||||
1. **Bun**: The TUI requires the Bun runtime. You can find installation instructions at [bun.sh](https://bun.sh/docs/installation).
|
||||
2. **TUI Plugin**: You must install the TUI plugin in your Quartz project.
|
||||
|
||||
### Installation
|
||||
|
||||
Run the following command to add the TUI plugin:
|
||||
|
||||
```shell
|
||||
npx quartz plugin add github:quartz-community/tui
|
||||
```
|
||||
|
||||
## Interface Panels
|
||||
|
||||
The TUI is divided into three main panels that you can navigate between.
|
||||
|
||||
### Plugins Panel
|
||||
|
||||
This panel allows you to browse all available and installed plugins. You can:
|
||||
|
||||
- Enable or disable plugins with a single keystroke.
|
||||
- Configure plugin-specific settings.
|
||||
- Install new plugins from the community or remove existing ones.
|
||||
|
||||
### Layout Panel
|
||||
|
||||
The Layout panel is where you define where components appear on your site. You can:
|
||||
|
||||
- Move components between different sections (e.g. `left`, `right`, `beforeBody`).
|
||||
- Reorder components within a section to change their vertical stack.
|
||||
- Set priorities for components to control their placement.
|
||||
|
||||
### Settings Panel
|
||||
|
||||
This panel provides a central place to edit your `quartz.config.yaml` settings. You can update:
|
||||
|
||||
- `pageTitle`
|
||||
- Theme colors and fonts
|
||||
- Analytics configuration
|
||||
- Deployment settings
|
||||
|
||||
## Navigation
|
||||
|
||||
The TUI uses standard terminal navigation keys:
|
||||
|
||||
- **Arrow Keys**: Move between items and panels.
|
||||
- **Enter**: Select an item or confirm a change.
|
||||
- **Esc**: Go back or cancel an action.
|
||||
- **Tab**: Cycle through different interface elements.
|
||||
|
||||
## Important Note
|
||||
|
||||
All changes made within the TUI are written directly to your `quartz.config.yaml` file. It is a good practice to have a clean Git state before using the TUI so you can easily review and undo any changes it makes.
|
||||
|
||||
For command-line based plugin management, see [[cli/plugin|quartz plugin]].
|
||||
29
docs/cli/update.md
Normal file
29
docs/cli/update.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: quartz update
|
||||
---
|
||||
|
||||
The `update` command keeps your Quartz installation up to date with the latest features and bug fixes from the official repository.
|
||||
|
||||
## How it Works
|
||||
|
||||
When you run `npx quartz update`, Quartz attempts to pull the latest code from the upstream Quartz repository. It uses Git to merge these changes into your local project.
|
||||
|
||||
```shell
|
||||
npx quartz update
|
||||
```
|
||||
|
||||
## Handling Conflicts
|
||||
|
||||
Because Quartz allows you to customize almost every part of the code, updates can sometimes result in merge conflicts. This happens if you have modified a file that the Quartz team has also updated.
|
||||
|
||||
If a conflict occurs:
|
||||
|
||||
1. Git will mark the conflicting sections in the affected files.
|
||||
2. You will need to open these files and manually choose which changes to keep.
|
||||
3. After resolving the conflicts, you can commit the changes.
|
||||
|
||||
## Recovery
|
||||
|
||||
If an update goes wrong or leaves your project in an unusable state, you can use the [[cli/restore|restore]] command to recover your content from the local cache.
|
||||
|
||||
For a more detailed guide on the upgrading process, see [[getting-started/upgrading]].
|
||||
60
docs/community.md
Normal file
60
docs/community.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Community
|
||||
---
|
||||
|
||||
Quartz has a vibrant community of users and contributors. This page highlights community-created plugins, tools, and resources that extend Quartz.
|
||||
|
||||
> [!tip] Contributing
|
||||
> Know of a great community resource? Submit a pull request to add it to this page!
|
||||
|
||||
## Community Plugins
|
||||
|
||||
Third-party plugins that extend Quartz functionality. Install them with the [[cli/plugin|plugin CLI]]:
|
||||
|
||||
```bash
|
||||
npx quartz plugin install <github-url>
|
||||
```
|
||||
|
||||
<!-- Add community plugins here as they become available -->
|
||||
<!-- Format: - **[Plugin Name](link)** — Brief description -->
|
||||
|
||||
_No community plugins listed yet. Be the first to share yours!_
|
||||
|
||||
## Tools & Integrations
|
||||
|
||||
Tools, scripts, and integrations built by the community to work with Quartz.
|
||||
|
||||
<!-- Add tools here -->
|
||||
<!-- Format: - **[Tool Name](link)** — Brief description -->
|
||||
|
||||
_No community tools listed yet._
|
||||
|
||||
## Templates & Themes
|
||||
|
||||
Custom themes, CSS snippets, and starter templates for Quartz sites.
|
||||
|
||||
<!-- Add templates/themes here -->
|
||||
<!-- Format: - **[Name](link)** — Brief description -->
|
||||
|
||||
_No community templates listed yet._
|
||||
|
||||
## Guides & Tutorials
|
||||
|
||||
Community-written guides, blog posts, and tutorials about using Quartz.
|
||||
|
||||
<!-- Add guides here -->
|
||||
<!-- Format: - **[Title](link)** by Author — Brief description -->
|
||||
|
||||
_No community guides listed yet._
|
||||
|
||||
## Related Projects
|
||||
|
||||
Projects and tools in the digital garden / PKM ecosystem that pair well with Quartz.
|
||||
|
||||
- **[Obsidian](https://obsidian.md/)** — Knowledge base and note-taking app (recommended editor for Quartz content)
|
||||
|
||||
---
|
||||
|
||||
Looking to see sites built with Quartz? Check out the [[showcase|Quartz Showcase]].
|
||||
|
||||
Want to chat with other Quartz users? [Join the Discord community](https://discord.gg/cRFFHYye7t).
|
||||
@ -131,14 +131,6 @@ npx quartz plugin add github:quartz-community/explorer
|
||||
|
||||
This adds the plugin to `quartz.config.yaml` and installs it to `.quartz/plugins/`.
|
||||
|
||||
To install a community plugin, you can use the following command:
|
||||
|
||||
```shell
|
||||
npx quartz plugin add github:quartz-community/explorer
|
||||
```
|
||||
|
||||
This adds the plugin to `externalPlugins` and installs it to `.quartz/plugins/`.
|
||||
|
||||
### Usage
|
||||
|
||||
You can customize the behaviour of Quartz by adding, removing and reordering plugins in `quartz.config.yaml`. Each plugin entry specifies its source, whether it's enabled, execution order, and any options:
|
||||
|
||||
@ -1,3 +1,44 @@
|
||||
---
|
||||
title: Feature List
|
||||
---
|
||||
|
||||
Quartz comes with a wide variety of features out of the box. Most features are powered by [[configuration#Plugins|plugins]] that can be configured, enabled, or disabled via `quartz.config.yaml`.
|
||||
|
||||
## Content Features
|
||||
|
||||
- [[Obsidian compatibility]] — Full support for Obsidian-flavored Markdown
|
||||
- [[wikilinks]] — Link between notes using `[[wikilinks]]` syntax
|
||||
- [[callouts]] — Obsidian-style callout blocks
|
||||
- [[Latex]] — LaTeX math rendering
|
||||
- [[Mermaid diagrams]] — Diagram support via Mermaid
|
||||
- [[syntax highlighting]] — Code block highlighting with themes
|
||||
- [[OxHugo compatibility]] — Support for ox-hugo Markdown
|
||||
- [[Roam Research compatibility]] — Support for Roam Research syntax
|
||||
- [[Citations]] — Academic citation support
|
||||
|
||||
## Navigation & Discovery
|
||||
|
||||
- [[full-text search]] — Search across all your notes
|
||||
- [[graph view]] — Interactive graph visualization of note connections
|
||||
- [[backlinks]] — See which notes link to the current page
|
||||
- [[explorer]] — File tree sidebar for browsing notes
|
||||
- [[breadcrumbs]] — Breadcrumb navigation trail
|
||||
- [[table of contents]] — Per-page table of contents
|
||||
- [[folder and tag listings]] — Browse notes by folder or tag
|
||||
- [[recent notes]] — Display recently modified notes
|
||||
- [[popover previews]] — Hover previews for internal links
|
||||
|
||||
## Appearance & Reading
|
||||
|
||||
- [[darkmode]] — Light and dark mode toggle
|
||||
- [[reader mode]] — Distraction-free reading experience
|
||||
- [[comments]] — Add comments via Giscus, Utterances, or other providers
|
||||
- [[social images]] — Auto-generated Open Graph images for social sharing
|
||||
|
||||
## Publishing & Deployment
|
||||
|
||||
- [[RSS Feed]] — RSS feed generation for content syndication
|
||||
- [[private pages]] — Control which pages are published
|
||||
- [[SPA Routing]] — Single-page app navigation
|
||||
- [[Docker Support]] — Build and deploy with Docker
|
||||
- [[i18n]] — Internationalization with 30+ supported locales
|
||||
|
||||
@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Authoring Content
|
||||
aliases:
|
||||
- "authoring content"
|
||||
---
|
||||
|
||||
All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've [[index#🪴 Get Started|setup Quartz]] already, this folder should already be initialized. Any Markdown in this folder will get processed by Quartz.
|
||||
All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've [[index#🪴 Get Started|setup Quartz]] already, this folder should already be initialized. Any Markdown in this folder will get processed by Quartz.
|
||||
|
||||
It is recommended that you use [Obsidian](https://obsidian.md/) as a way to edit and maintain your Quartz. It comes with a nice editor and graphical interface to preview, edit, and link your local files and attachments.
|
||||
|
||||
@ -40,7 +42,7 @@ See [[Frontmatter]] for a complete list of frontmatter.
|
||||
## Syncing your Content
|
||||
|
||||
When your Quartz is at a point you're happy with, you can save your changes to GitHub.
|
||||
First, make sure you've [[setting up your GitHub repository|already setup your GitHub repository]] and then do `npx quartz sync`.
|
||||
First, make sure you've [[getting-started/installation|already setup your GitHub repository]] and then do `npx quartz sync`.
|
||||
|
||||
## Customization
|
||||
|
||||
17
docs/getting-started/index.md
Normal file
17
docs/getting-started/index.md
Normal file
@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
Welcome to Quartz! This section will walk you through setting up your digital garden from scratch.
|
||||
|
||||
## Setup
|
||||
|
||||
1. **[[getting-started/installation|Installation]]** — Clone Quartz, create your repository, and push your first sync
|
||||
2. **[[getting-started/authoring-content|Authoring Content]]** — Write and organize your notes in the `content` folder
|
||||
3. **[[build|Building]]** — Preview your site locally with `npx quartz build --serve`
|
||||
4. **[[hosting|Hosting]]** — Deploy your Quartz site to the web
|
||||
|
||||
## Upgrading & Migrating
|
||||
|
||||
- **[[getting-started/upgrading|Upgrading Quartz]]** — Keep your Quartz installation up to date
|
||||
- **[[getting-started/migrating|Migrating to Quartz 5]]** — Migrate from Quartz 4 or Quartz 3
|
||||
@ -1,5 +1,7 @@
|
||||
---
|
||||
title: Setting up your GitHub repository
|
||||
title: "Installation"
|
||||
aliases:
|
||||
- "setting up your GitHub repository"
|
||||
---
|
||||
|
||||
First, make sure you have Quartz [[index#🪴 Get Started|cloned and setup locally]].
|
||||
@ -8,7 +10,7 @@ Then, create a new repository on GitHub.com. Do **not** initialize the new repos
|
||||
|
||||
![[github-init-repo-options.png]]
|
||||
|
||||
At the top of your repository on GitHub.com's Quick Setup page, click the clipboard to copy the remote repository URL.
|
||||
At the top of your repository on GitHub.com's Quick Setup page, click the clipboard to copy the remote repository URL.
|
||||
|
||||
![[github-quick-setup.png]]
|
||||
|
||||
@ -1,14 +1,19 @@
|
||||
---
|
||||
title: "Migrating from Quartz 4"
|
||||
title: "Migrating to Quartz 5"
|
||||
aliases:
|
||||
- "migrating from Quartz 3"
|
||||
- "migrating from Quartz 4"
|
||||
---
|
||||
|
||||
## Overview
|
||||
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
|
||||
|
||||
### Overview
|
||||
|
||||
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.
|
||||
|
||||
## What Changed
|
||||
|
||||
List the key architectural changes:
|
||||
### What Changed
|
||||
|
||||
- **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`)
|
||||
@ -16,9 +21,9 @@ List the key architectural changes:
|
||||
- **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`)
|
||||
|
||||
## Step-by-Step Migration
|
||||
### Step-by-Step Migration
|
||||
|
||||
### 1. Install Community Plugins
|
||||
#### 1. Install Community Plugins
|
||||
|
||||
Run the following commands to install the default set of community plugins:
|
||||
|
||||
@ -67,9 +72,7 @@ npx quartz plugin add github:quartz-community/roam
|
||||
npx quartz plugin add github:quartz-community/explicit-publish
|
||||
```
|
||||
|
||||
### 2. Update quartz.config.yaml
|
||||
|
||||
Show before (v4) and after (v5) comparison:
|
||||
#### 2. Update quartz.config.yaml
|
||||
|
||||
**Before (v4):**
|
||||
|
||||
@ -152,9 +155,7 @@ Key changes:
|
||||
- Each plugin entry has `enabled`, `options`, `order`, and optionally `layout` fields
|
||||
- Install community plugins with `npx quartz plugin add github:quartz-community/<name>`
|
||||
|
||||
### 3. Update layout configuration
|
||||
|
||||
Show before (v4) and after (v5):
|
||||
#### 3. Update layout configuration
|
||||
|
||||
**Before (v4):**
|
||||
|
||||
@ -264,20 +265,20 @@ Key changes:
|
||||
- Empty arrays (`[]`) clear a position for that page type
|
||||
- The `exclude` field removes specific plugins from a page type
|
||||
|
||||
### 4. Update CI/CD
|
||||
#### 4. Update CI/CD
|
||||
|
||||
Add `npx quartz plugin restore` to your build pipeline, before `npx quartz build`. See [[ci-cd]] for detailed examples.
|
||||
|
||||
### 5. Commit and Deploy
|
||||
#### 5. Commit and Deploy
|
||||
|
||||
```shell
|
||||
git add quartz.ts quartz.lock.json
|
||||
git commit -m "chore: migrate to Quartz 5 plugin system"
|
||||
```
|
||||
|
||||
## Plugin Reference Table
|
||||
### Plugin Reference Table
|
||||
|
||||
Show a table mapping v4 Plugin names to v5 equivalents:
|
||||
Mapping v4 plugin names to v5 equivalents:
|
||||
|
||||
| v4 | v5 | Type |
|
||||
| ----------------------------------- | ------------------------------------------- | --------------------- |
|
||||
@ -300,7 +301,7 @@ Show a table mapping v4 Plugin names to v5 equivalents:
|
||||
| `Plugin.AliasRedirects()` | `ExternalPlugin.AliasRedirects()` | Community |
|
||||
| `Plugin.ContentIndex()` | `ExternalPlugin.ContentIndex()` | Community |
|
||||
|
||||
And for components in layout:
|
||||
Component layout mapping:
|
||||
|
||||
| v4 Layout | v5 Layout |
|
||||
| ----------------------------- | ------------------------------------------ |
|
||||
@ -313,3 +314,45 @@ And for components in layout:
|
||||
| `Component.TableOfContents()` | `Plugin.TableOfContents()` |
|
||||
| `Component.Head()` | `Component.Head()` (unchanged, internal) |
|
||||
| `Component.Spacer()` | `Component.Spacer()` (unchanged, internal) |
|
||||
|
||||
---
|
||||
|
||||
## Migrating from Quartz 3
|
||||
|
||||
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, and import your old vault. Then follow the [Quartz 4 migration steps above](#migrating-from-quartz-4) to get to v5.
|
||||
|
||||
```bash
|
||||
git fetch
|
||||
git checkout v4
|
||||
git pull upstream v4
|
||||
npm i
|
||||
npx quartz create
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
git remote add upstream https://github.com/jackyzha0/quartz.git
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
> [!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.
|
||||
|
||||
### 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 4 now uses a Node-based static-site generation process which should lead to a 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 4 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 4 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 4's configuration and plugin system is designed to be extended by users while making updating to new versions of Quartz easy.
|
||||
|
||||
### 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 `v4`.
|
||||
- [[folder and tag listings|Folder and tag listings]] have also changed.
|
||||
- Folder descriptions should go under `content/<folder-name>/index.md` where `<folder-name>` is the name of the folder.
|
||||
- Tag descriptions should go under `content/tags/<tag-name>.md` where `<tag-name>` is the name of the tag.
|
||||
- Some HTML layout may not be the same between Quartz 3 and Quartz 4. 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 4 no longer uses Hugo. For components, check out the guide on [[creating components]] for more details on this.
|
||||
@ -1,9 +1,11 @@
|
||||
---
|
||||
title: "Upgrading Quartz"
|
||||
aliases:
|
||||
- upgrading
|
||||
---
|
||||
|
||||
> [!note]
|
||||
> This is specifically a guide for upgrading Quartz 4 version to a more recent update. If you are coming from Quartz 3, check out the [[migrating from Quartz 3|migration guide]] for more info.
|
||||
> This is specifically a guide for upgrading your Quartz to a more recent update. If you are coming from Quartz 4 or Quartz 3, check out the [[getting-started/migrating|migration guide]] for more info.
|
||||
|
||||
To fetch the latest Quartz updates, simply run
|
||||
|
||||
@ -42,6 +42,6 @@ For a comprehensive list of features, visit the [features page](./features/). Yo
|
||||
|
||||
### 🚧 Troubleshooting + Updating
|
||||
|
||||
Having trouble with Quartz? Try searching for your issue using the search feature. If you haven't already, [[upgrading|upgrade]] to the newest version of Quartz to see if this fixes your issue.
|
||||
Having trouble with Quartz? Try searching for your issue using the search feature or check the [[troubleshooting]] page. If you haven't already, [[upgrading|upgrade]] to the newest version of Quartz to see if this fixes your issue.
|
||||
|
||||
If you're still having trouble, feel free to [submit an issue](https://github.com/jackyzha0/quartz/issues) if you feel you found a bug or ask for help in our [Discord Community](https://discord.gg/cRFFHYye7t).
|
||||
If you're still having trouble, feel free to [submit an issue](https://github.com/jackyzha0/quartz/issues) if you feel you found a bug or ask for help in our [Discord Community](https://discord.gg/cRFFHYye7t). You can also browse the [[community]] page for third-party plugins and resources.
|
||||
|
||||
@ -1,41 +0,0 @@
|
||||
---
|
||||
title: "Migrating from Quartz 3"
|
||||
---
|
||||
|
||||
As you already have Quartz locally, you don't need to fork or clone it again. Simply just checkout the alpha branch, install the dependencies, and import your old vault.
|
||||
|
||||
```bash
|
||||
git fetch
|
||||
git checkout v4
|
||||
git pull upstream v4
|
||||
npm i
|
||||
npx quartz create
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```shell
|
||||
git remote add upstream https://github.com/jackyzha0/quartz.git
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
> [!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.
|
||||
|
||||
## Key changes
|
||||
|
||||
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 4 now uses a Node-based static-site generation process which should lead to a 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 4 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 4 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 4's configuration and plugin system is designed to be extended by users while making updating to new versions of Quartz easy.
|
||||
|
||||
## 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 `v4`.
|
||||
- [[folder and tag listings|Folder and tag listings]] have also changed.
|
||||
- Folder descriptions should go under `content/<folder-name>/index.md` where `<folder-name>` is the name of the folder.
|
||||
- Tag descriptions should go under `content/tags/<tag-name>.md` where `<tag-name>` is the name of the tag.
|
||||
- Some HTML layout may not be the same between Quartz 3 and Quartz 4. 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 4 no longer uses Hugo. For components, check out the guide on [[creating components]] for more details on this.
|
||||
@ -9,13 +9,17 @@ formulas:
|
||||
if(file.hasTag("component"), "component",
|
||||
if(file.inFolder("features"), "feature",
|
||||
if(file.inFolder("advanced"), "advanced",
|
||||
if(file.inFolder("plugins"), "plugin", "guide")))))))
|
||||
if(file.inFolder("plugins"), "plugin",
|
||||
if(file.inFolder("getting-started"), "getting-started",
|
||||
if(file.inFolder("cli"), "cli", "guide")))))))))
|
||||
last_modified: file.mtime.relative()
|
||||
section: |
|
||||
if(file.inFolder("plugins"), "plugins",
|
||||
if(file.inFolder("features"), "features",
|
||||
if(file.inFolder("advanced"), "advanced",
|
||||
if(file.inFolder("tags"), "tags", "core"))))
|
||||
if(file.inFolder("getting-started"), "getting-started",
|
||||
if(file.inFolder("cli"), "cli",
|
||||
if(file.inFolder("tags"), "tags", "core"))))))
|
||||
properties:
|
||||
title:
|
||||
displayName: Title
|
||||
@ -86,6 +90,8 @@ views:
|
||||
- file.inFolder("plugins")
|
||||
- file.inFolder("features")
|
||||
- file.inFolder("advanced")
|
||||
- file.inFolder("getting-started")
|
||||
- file.inFolder("cli")
|
||||
- file.inFolder("tags")
|
||||
order:
|
||||
- file.name
|
||||
|
||||
34
docs/plugins/Backlinks.md
Normal file
34
docs/plugins/Backlinks.md
Normal file
@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Backlinks
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Shows pages that link to the current page.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[backlinks]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `hideWhenEmpty`: Hide the backlinks section if the current page has no backlinks. Defaults to `true`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/backlinks
|
||||
enabled: true
|
||||
options:
|
||||
hideWhenEmpty: true
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.Backlinks()`.
|
||||
- Source: [`quartz-community/backlinks`](https://github.com/quartz-community/backlinks)
|
||||
- Install: `npx quartz plugin add github:quartz-community/backlinks`
|
||||
40
docs/plugins/Breadcrumbs.md
Normal file
40
docs/plugins/Breadcrumbs.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Breadcrumbs
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Navigation breadcrumb trail.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[breadcrumbs]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `spacerSymbol`: The symbol to use between breadcrumb items. Defaults to `"❯"`.
|
||||
- `rootName`: The name of the root page. Defaults to `Home`.
|
||||
- `resolveFrontmatterTitle`: Whether to use the `title` frontmatter field for breadcrumb items. Defaults to `true`.
|
||||
- `showCurrentPage`: Whether to show the current page in the breadcrumb trail. Defaults to `true`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/breadcrumbs
|
||||
enabled: true
|
||||
options:
|
||||
spacerSymbol: "❯"
|
||||
rootName: Home
|
||||
resolveFrontmatterTitle: true
|
||||
showCurrentPage: true
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.Breadcrumbs()`.
|
||||
- Source: [`quartz-community/breadcrumbs`](https://github.com/quartz-community/breadcrumbs)
|
||||
- Install: `npx quartz plugin add github:quartz-community/breadcrumbs`
|
||||
53
docs/plugins/Comments.md
Normal file
53
docs/plugins/Comments.md
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Comments
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Comment system (giscus, utterances, etc.).
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[comments]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `provider`: The comment provider to use. Currently only `giscus` is supported.
|
||||
- `options`: Provider-specific options.
|
||||
- `repo`: The GitHub repository to use for comments.
|
||||
- `repoId`: The ID of the GitHub repository.
|
||||
- `category`: The discussion category to use.
|
||||
- `categoryId`: The ID of the discussion category.
|
||||
- `lang`: The language for the comment system. Defaults to `en`.
|
||||
- `themeUrl`: URL to a folder with custom themes.
|
||||
- `lightTheme`: Filename for the light theme CSS file. Defaults to `light`.
|
||||
- `darkTheme`: Filename for the dark theme CSS file. Defaults to `dark`.
|
||||
- `mapping`: How to map pages to discussions. Defaults to `url`.
|
||||
- `strict`: Use strict title matching. Defaults to `true`.
|
||||
- `reactionsEnabled`: Whether to enable reactions for the main post. Defaults to `true`.
|
||||
- `inputPosition`: Where to put the comment input box relative to the comments. Defaults to `bottom`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/comments
|
||||
enabled: true
|
||||
options:
|
||||
provider: giscus
|
||||
options:
|
||||
repo: jackyzha0/quartz
|
||||
repoId: MDEwOlJlcG9zaXRvcnkzODcyMTMyMDg
|
||||
category: Announcements
|
||||
categoryId: DIC_kwDOFxRnmM4B-Xg6
|
||||
lang: en
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.Comments()`.
|
||||
- Source: [`quartz-community/comments`](https://github.com/quartz-community/comments)
|
||||
- Install: `npx quartz plugin add github:quartz-community/comments`
|
||||
32
docs/plugins/Darkmode.md
Normal file
32
docs/plugins/Darkmode.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Darkmode
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Dark mode toggle.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[darkmode]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `enabled`: Whether to enable the dark mode toggle. Defaults to `true`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/darkmode
|
||||
enabled: true
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.Darkmode()`.
|
||||
- Source: [`quartz-community/darkmode`](https://github.com/quartz-community/darkmode)
|
||||
- Install: `npx quartz plugin add github:quartz-community/darkmode`
|
||||
40
docs/plugins/Explorer.md
Normal file
40
docs/plugins/Explorer.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Explorer
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
File tree explorer sidebar.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[explorer]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `title`: The title of the explorer. Defaults to `Explorer`.
|
||||
- `folderClickBehavior`: The behavior when a folder is clicked. Can be `"link"` to navigate or `"collapse"` to toggle. Defaults to `collapse`.
|
||||
- `folderDefaultState`: The default state of folders. Can be `"collapsed"` or `"open"`. Defaults to `collapsed`.
|
||||
- `useSavedState`: Whether to use local storage to save the state of the explorer. Defaults to `true`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/explorer
|
||||
enabled: true
|
||||
options:
|
||||
title: Explorer
|
||||
folderClickBehavior: collapse
|
||||
folderDefaultState: collapsed
|
||||
useSavedState: true
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.Explorer()`.
|
||||
- Source: [`quartz-community/explorer`](https://github.com/quartz-community/explorer)
|
||||
- Install: `npx quartz plugin add github:quartz-community/explorer`
|
||||
77
docs/plugins/Graph.md
Normal file
77
docs/plugins/Graph.md
Normal file
@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Graph
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Interactive graph visualization.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[graph view]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `localGraph`: Options for the local graph view.
|
||||
- `globalGraph`: Options for the global graph view.
|
||||
|
||||
Both `localGraph` and `globalGraph` accept the following options:
|
||||
|
||||
- `drag`: Enable dragging nodes. Defaults to `true`.
|
||||
- `zoom`: Enable zooming. Defaults to `true`.
|
||||
- `depth`: The depth of the graph. Defaults to `1` for local and `-1` for global.
|
||||
- `scale`: The initial scale of the graph.
|
||||
- `repelForce`: The force that pushes nodes apart.
|
||||
- `centerForce`: The force that pulls nodes to the center.
|
||||
- `linkDistance`: The distance between linked nodes.
|
||||
- `fontSize`: The font size of node labels.
|
||||
- `opacityScale`: The scale of node opacity.
|
||||
- `removeTags`: Tags to exclude from the graph.
|
||||
- `showTags`: Whether to show tags in the graph.
|
||||
- `enableRadial`: Whether to enable radial layout.
|
||||
- `focusOnHover`: Whether to focus on the hovered node (global only).
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/graph
|
||||
enabled: true
|
||||
options:
|
||||
localGraph:
|
||||
drag: true
|
||||
zoom: true
|
||||
depth: 1
|
||||
scale: 1.1
|
||||
repelForce: 0.5
|
||||
centerForce: 0.3
|
||||
linkDistance: 30
|
||||
fontSize: 0.6
|
||||
opacityScale: 1
|
||||
removeTags: []
|
||||
showTags: true
|
||||
enableRadial: false
|
||||
globalGraph:
|
||||
drag: true
|
||||
zoom: true
|
||||
depth: -1
|
||||
scale: 0.9
|
||||
repelForce: 0.5
|
||||
centerForce: 0.3
|
||||
linkDistance: 30
|
||||
fontSize: 0.6
|
||||
opacityScale: 1
|
||||
removeTags: []
|
||||
showTags: true
|
||||
focusOnHover: true
|
||||
enableRadial: true
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.Graph()`.
|
||||
- Source: [`quartz-community/graph`](https://github.com/quartz-community/graph)
|
||||
- Install: `npx quartz plugin add github:quartz-community/graph`
|
||||
17
docs/plugins/NoteProperties.md
Normal file
17
docs/plugins/NoteProperties.md
Normal file
@ -0,0 +1,17 @@
|
||||
---
|
||||
title: NoteProperties
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
The NoteProperties plugin is documented under [[Frontmatter]].
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.NoteProperties()`.
|
||||
- Source: [`quartz-community/note-properties`](https://github.com/quartz-community/note-properties)
|
||||
- Install: `npx quartz plugin add github:quartz-community/note-properties`
|
||||
32
docs/plugins/ReaderMode.md
Normal file
32
docs/plugins/ReaderMode.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
title: ReaderMode
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Distraction-free reading mode.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[reader mode]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `enabled`: Whether to enable reader mode. Defaults to `true`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/reader-mode
|
||||
enabled: true
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.ReaderMode()`.
|
||||
- Source: [`quartz-community/reader-mode`](https://github.com/quartz-community/reader-mode)
|
||||
- Install: `npx quartz plugin add github:quartz-community/reader-mode`
|
||||
40
docs/plugins/RecentNotes.md
Normal file
40
docs/plugins/RecentNotes.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
title: RecentNotes
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Shows recently modified notes.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[recent notes]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `title`: The title of the recent notes section. Defaults to `Recent notes`.
|
||||
- `limit`: The maximum number of recent notes to display. Defaults to `5`.
|
||||
- `showTags`: Whether to display the tags for each note. Defaults to `true`.
|
||||
- `linkToMore`: A slug to a page that shows more notes. Defaults to `""`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/recent-notes
|
||||
enabled: true
|
||||
options:
|
||||
title: Recent notes
|
||||
limit: 5
|
||||
showTags: true
|
||||
linkToMore: ""
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.RecentNotes()`.
|
||||
- Source: [`quartz-community/recent-notes`](https://github.com/quartz-community/recent-notes)
|
||||
- Install: `npx quartz plugin add github:quartz-community/recent-notes`
|
||||
32
docs/plugins/Search.md
Normal file
32
docs/plugins/Search.md
Normal file
@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Search
|
||||
tags:
|
||||
- plugin/component
|
||||
---
|
||||
|
||||
Full-text search functionality.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
See [[full-text search]] for detailed usage information.
|
||||
|
||||
## Configuration
|
||||
|
||||
This plugin accepts the following configuration options:
|
||||
|
||||
- `enabled`: Whether to enable full-text search. Defaults to `true`.
|
||||
|
||||
### Default options
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
- source: github:quartz-community/search
|
||||
enabled: true
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- Category: Component
|
||||
- Function name: `ExternalPlugin.Search()`.
|
||||
- Source: [`quartz-community/search`](https://github.com/quartz-community/search)
|
||||
- Install: `npx quartz plugin add github:quartz-community/search`
|
||||
128
docs/troubleshooting.md
Normal file
128
docs/troubleshooting.md
Normal file
@ -0,0 +1,128 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
---
|
||||
|
||||
Common issues and solutions when working with Quartz.
|
||||
|
||||
## Build Errors
|
||||
|
||||
### `Could not resolve ...` or missing module errors
|
||||
|
||||
This usually means a plugin is not installed. Run:
|
||||
|
||||
```bash
|
||||
npx quartz plugin restore
|
||||
```
|
||||
|
||||
This restores all plugins from your `quartz.lock.json` to `.quartz/plugins/`.
|
||||
|
||||
### `tsc` type errors after updating
|
||||
|
||||
After running `npx quartz update`, type errors can occur if the update changed internal APIs that your `quartz.ts` overrides depend on. Check the changelog for breaking changes and update your overrides accordingly.
|
||||
|
||||
### Build is slow
|
||||
|
||||
Try increasing concurrency:
|
||||
|
||||
```bash
|
||||
npx quartz build --concurrency 8
|
||||
```
|
||||
|
||||
The default uses all available CPU cores. If you're on a memory-constrained environment (CI), reducing concurrency may actually help.
|
||||
|
||||
## Plugin Issues
|
||||
|
||||
### Plugin not loading after installation
|
||||
|
||||
1. Verify the plugin appears in `quartz.config.yaml` under `plugins:`
|
||||
2. Check that `enabled: true` is set
|
||||
3. Run `npx quartz plugin list` to confirm it's installed
|
||||
4. Run `npx quartz plugin check` to verify plugin health
|
||||
|
||||
### Plugin options not taking effect
|
||||
|
||||
Make sure your YAML indentation is correct. Options must be nested under the plugin entry:
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/some-plugin
|
||||
enabled: true
|
||||
options:
|
||||
myOption: value # correct: nested under options
|
||||
```
|
||||
|
||||
A common mistake is putting options at the wrong indentation level.
|
||||
|
||||
### `ExternalPlugin.X is not a function`
|
||||
|
||||
This means the plugin is referenced in `quartz.ts` but not installed. Either:
|
||||
|
||||
- Install it: `npx quartz plugin add github:quartz-community/plugin-name`
|
||||
- Or remove the reference from `quartz.ts`
|
||||
|
||||
## Content Issues
|
||||
|
||||
### Notes not showing up
|
||||
|
||||
- Check that the file is in the `content/` folder
|
||||
- Check that `draft: true` is not set in the frontmatter (the [[RemoveDrafts]] plugin filters these out)
|
||||
- If using [[ExplicitPublish]], make sure `publish: true` is set in frontmatter
|
||||
- Check your [[configuration]] `ignorePatterns` to make sure the file path is not excluded
|
||||
|
||||
### Wikilinks not resolving
|
||||
|
||||
- Make sure the [[ObsidianFlavoredMarkdown]] plugin is enabled
|
||||
- Verify the target note exists in your content folder
|
||||
- Check for case sensitivity issues in filenames
|
||||
|
||||
### Images not displaying
|
||||
|
||||
- Ensure images are in a folder that Quartz processes (typically `content/` or a subfolder)
|
||||
- Check that the image path in your Markdown matches the actual file location
|
||||
- The [[Assets]] emitter must be enabled (it is by default)
|
||||
|
||||
## GitHub Sync Issues
|
||||
|
||||
### `fatal: --[no-]autostash option is only valid with --rebase`
|
||||
|
||||
You may have an outdated version of `git`. Update git to resolve this.
|
||||
|
||||
### `fatal: The remote end hung up unexpectedly`
|
||||
|
||||
This is usually due to Git's default buffer size being too small for your content. Increase it:
|
||||
|
||||
```bash
|
||||
git config http.postBuffer 524288000
|
||||
```
|
||||
|
||||
### Merge conflicts during sync
|
||||
|
||||
If `npx quartz sync` encounters merge conflicts:
|
||||
|
||||
1. Resolve the conflicts in your editor
|
||||
2. Run `git add .` and `git commit` to complete the merge
|
||||
3. Run `npx quartz sync --no-pull` to push
|
||||
|
||||
If you want to start over, run `npx quartz restore` to recover your content from the cache.
|
||||
|
||||
## Development Server Issues
|
||||
|
||||
### Hot reload not working
|
||||
|
||||
- Make sure you're using `--serve` mode: `npx quartz build --serve`
|
||||
- Check that port 3001 (WebSocket) is not blocked — this is the default `--wsPort` used for hot reload notifications
|
||||
- If developing remotely, use `--remoteDevHost` to set the correct WebSocket URL
|
||||
|
||||
### Port already in use
|
||||
|
||||
Change the port:
|
||||
|
||||
```bash
|
||||
npx quartz build --serve --port 3000
|
||||
```
|
||||
|
||||
## Still stuck?
|
||||
|
||||
- Check the [GitHub Issues](https://github.com/jackyzha0/quartz/issues) for similar problems
|
||||
- Ask in the [Discord Community](https://discord.gg/cRFFHYye7t)
|
||||
- Run your command with `--verbose` for more detailed error output
|
||||
Loading…
Reference in New Issue
Block a user