mirror of
https://github.com/jackyzha0/quartz.git
synced 2026-03-21 21:45:42 -05:00
docs: updated cli commands
This commit is contained in:
saberzero1
parent
c82f845a40
commit
f1fea423ed
@ -2,18 +2,37 @@
|
||||
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.
|
||||
The `create` command initializes a new Quartz project. It helps you set up your content folder, choose a configuration template, set your site's base URL, and configure how Quartz should handle your Markdown files.
|
||||
|
||||
## Flags
|
||||
|
||||
| Flag | Shorthand | Description |
|
||||
| ------------- | --------- | --------------------------------------------------------------------- |
|
||||
| `--template` | `-t` | Configuration template (`default`, `obsidian`, `ttrpg`, or `blog`) |
|
||||
| `--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`) |
|
||||
| `--baseUrl` | `-b` | Base URL for your site (e.g. `mysite.github.io/quartz`) |
|
||||
| `--verbose` | `-v` | Enable detailed logging |
|
||||
|
||||
## Templates
|
||||
|
||||
When you run `quartz create`, you can choose a configuration template that pre-configures Quartz for your use case:
|
||||
|
||||
- **Default**: A clean Quartz setup with sensible defaults. Best for starting from scratch.
|
||||
- **Obsidian**: Optimized for Obsidian vaults with full Obsidian Flavored Markdown support (wikilinks, callouts, mermaid diagrams, etc.). Automatically sets link resolution to `shortest` and skips the link resolution prompt.
|
||||
- **TTRPG**: Builds on the Obsidian template with the addition of the [Leaflet map plugin](https://github.com/quartz-community/external-quartz-leaflet-map-plugin) and [ITS Theme](https://github.com/saberzero1/quartz-themes) (`its-theme.ttrpg-dnd`). Great for D&D and TTRPG wikis. Also skips the link resolution prompt.
|
||||
- **Blog**: A blog-focused setup with [recent notes](https://github.com/quartz-community/recent-notes) enabled (showing the 5 most recent posts with tags) and [comments](https://github.com/quartz-community/comments) enabled via giscus. You'll need to fill in the `TODO:` placeholder values in `quartz.config.yaml` with your own giscus repository details.
|
||||
|
||||
## Base URL
|
||||
|
||||
During setup, Quartz will ask for the base URL of your site. This is the URL where your site will be deployed (e.g. `mysite.github.io/quartz`).
|
||||
|
||||
- Do **not** include the protocol (`https://`) — if you do, it will be automatically stripped.
|
||||
- Trailing slashes are also removed automatically.
|
||||
- See [[configuration]] for more details on how `baseUrl` is used.
|
||||
|
||||
## Strategies
|
||||
|
||||
When you run `quartz create`, you must choose a strategy for your content:
|
||||
@ -31,21 +50,35 @@ Quartz needs to know how to interpret the internal links in your Markdown files:
|
||||
- **absolute**: Resolves links relative to the root of your content folder.
|
||||
- **relative**: Resolves links relative to the current file's location.
|
||||
|
||||
> [!note]
|
||||
> When using the **Obsidian** or **TTRPG** templates, link resolution is automatically set to `shortest` and the prompt is skipped.
|
||||
|
||||
## 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.
|
||||
1. **Choose a template**: Select a configuration template (`Default`, `Obsidian`, `TTRPG`, or `Blog`).
|
||||
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.
|
||||
3. **Enter base URL**: Provide the URL where your site will be hosted.
|
||||
4. **Select link resolution**: Choose how your links are formatted (skipped for Obsidian and TTRPG templates).
|
||||
5. **Finish**: Quartz will set up the directory structure and create your configuration.
|
||||
|
||||
## 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
|
||||
npx quartz create --template obsidian --strategy symlink --source ~/Documents/MyVault
|
||||
```
|
||||
|
||||
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.
|
||||
This command tells Quartz to use the Obsidian template (with full OFM support and shortest link resolution), look at your vault in `~/Documents/MyVault`, and use symbolic links so changes are synced.
|
||||
|
||||
## Example: Setting Up a Blog
|
||||
|
||||
To quickly set up a blog with recent notes and comments:
|
||||
|
||||
```shell
|
||||
npx quartz create --template blog --strategy new --baseUrl myblog.github.io
|
||||
```
|
||||
|
||||
After setup, edit `quartz.config.yaml` to fill in your giscus repository details in the comments plugin section.
|
||||
|
||||
@ -8,19 +8,19 @@ 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` |
|
||||
| `upgrade` | Upgrade Quartz to the latest version | `npx quartz upgrade` |
|
||||
| `update` | Update installed plugins | `npx quartz update` |
|
||||
| `plugin` | Manage Quartz plugins | `npx quartz plugin list` |
|
||||
| `tui` | Launch the interactive plugin manager | `npx quartz tui` |
|
||||
| Command | Description | Example |
|
||||
| --------- | ------------------------------------------------------- | ------------------------ |
|
||||
| `create` | Initialize a new Quartz project with template selection | `npx quartz create` |
|
||||
| `build` | Generate static HTML files | `npx quartz build` |
|
||||
| `sync` | Sync content with GitHub | `npx quartz sync` |
|
||||
| `upgrade` | Upgrade Quartz to the latest version | `npx quartz upgrade` |
|
||||
| `update` | Update installed plugins | `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/create|create]]: Initialize a new Quartz project with a choice of templates (default, obsidian, ttrpg, blog) and base URL configuration.
|
||||
- [[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/upgrade|upgrade]]: Upgrade the Quartz framework to the latest version.
|
||||
|
||||
@ -42,6 +42,7 @@ This part of the configuration concerns anything that can affect the whole site.
|
||||
- `{ provider: 'rybbit', siteId: 'my-rybbit-id' }` (managed) or `{ provider: 'rybbit', siteId: 'my-rybbit-id', host: 'my-rybbit-domain.com' }` (self-hosted) use [Rybbit](https://rybbit.com);
|
||||
- `locale`: used for [[i18n]] and date formatting
|
||||
- `baseUrl`: this is used for sitemaps and RSS feeds that require an absolute URL to know where the canonical 'home' of your site lives. This is normally the deployed URL of your site (e.g. `quartz.jzhao.xyz` for this site). Do not include the protocol (i.e. `https://`) or any leading or trailing slashes.
|
||||
- You will be prompted to set this during [[cli/create|`npx quartz create`]]. The CLI automatically strips any `https://` or `http://` protocol prefixes and trailing slashes for you.
|
||||
- This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example, if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and the `baseUrl` would be `jackyzha0.github.io/quartz`.
|
||||
- Note that Quartz 5 will avoid using this as much as possible and use relative URLs whenever it can to make sure your site works no matter _where_ you end up actually deploying it.
|
||||
- `ignorePatterns`: a list of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that Quartz should ignore and not search through when looking for files inside the `content` folder. See [[private pages]] for more details.
|
||||
|
||||
@ -18,7 +18,7 @@ npx quartz plugin restore
|
||||
npx quartz create
|
||||
```
|
||||
|
||||
This will guide you through initializing your Quartz with content. Once you've done so, see how to:
|
||||
This will guide you through initializing your Quartz with content, including choosing a [[cli/create#templates|project template]] and configuring your site's base URL. Once you've done so, see how to:
|
||||
|
||||
1. [[authoring content|Writing content]] in Quartz
|
||||
2. [[configuration|Configure]] Quartz's behaviour
|
||||
|
||||
Loading…
Reference in New Issue
Block a user