feat(v5): add plugin system (#2295)
* feat(plugins): v5 plugin system * feat(plugins): explorer as community plugin * feat(plugins): graph as community plugin * chore: update package-lock.json * chore: update package-lock.json * docs: updated plugin-specific docs * chore: update package-lock.json * chore: update package-lock.json * chore: update package-lock.json * Implement Git-based plugin system with dogfooding for community plugins - Remove npm dependencies for @quartz-community/* plugins - Add gitLoader.ts for installing plugins from GitHub - Update quartz.layout.ts to import from .quartz/plugins/ - Add install-plugins.ts script for prebuild hook - Add .quartz/ to .gitignore * Add comprehensive Git-based plugin CLI with lockfile support - Create quartz.lock.json format for tracking exact plugin commits - Add 'npx quartz plugin' commands: install, add, remove, update, list, restore - Plugin state is fully reproducible via lockfile - No npm dependencies required for community plugins * Fix TypeScript errors in git-installed plugins - Install @quartz-community/types as devDependency - Fix plugin imports to define types locally - Fix search inline script fetchData bug - Format code with prettier * fix(types): install types from github * docs: updated plugin-specific docs * Update Dockerfile and add CI/CD documentation - Add plugin install step to Dockerfile - Create docs/ci-cd.md with pipeline configuration guide * Update GitHub Actions workflows for v5 branch and Git-based plugins - Change branch references from v4 to v5 - Add plugin caching to speed up builds - Use 'npx quartz plugin install' instead of 'restore' - Update Docker workflow branch trigger * Update quartz.lock.json with fixed plugin versions * fix(docker): install command * docs: add plugin migration analysis document Comprehensive analysis of which Quartz v4 components and plugins can be migrated to separate repositories, including: - Component analysis (25 components) - Plugin analysis (transformers, emitters, filters) - Migration strategies for different plugin types - Lessons learned from Explorer/Graph/Search migrations - Recommended migration order * chore: updated plugins * chore: updated plugins * chore: updated dependencies * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: tsconfig * feat: build installed plugins * chore: updated plugins * chore: updated plugins * chore: update explorer plugin with duplication fix * docs: Quartz v5 * chore: update graph plugin with navigation fix * fix: update explorer plugin with toggle fix * fix: update explorer plugin - ensure toggle buttons always work * fix: create plugin components once to prevent duplicate script registration * chore: updated plugins * chore: updated plugins * feat: migrate 7 feature components to community plugins (Phase B) Migrate ArticleTitle, TagList, PageTitle, Darkmode, ReaderMode, ContentMeta, and Footer from internal components to community plugins. Update layout to use Plugin.X() pattern, remove internal component files and their styles/scripts. Add MIGRATION_TASKS.md documenting the full migration roadmap. * chore: updated plugins * refactor: delete 6 internal component duplicates (Phase A) Remove Backlinks, Breadcrumbs, RecentNotes, Search, TableOfContents, Comments, and OverflowList — all replaced by community plugins. Delete associated styles (6) and scripts (3). Switch layout to use Plugin.Breadcrumbs() instead of Component.Breadcrumbs(). * refactor: unify QuartzComponent type to structural interface (Phase C) - Changed QuartzComponent from ComponentType<QuartzComponentProps> to callable type ((props: QuartzComponentProps) => any) - Added optional displayName property for better debugging - Removed ComponentType import from preact - Removed all 13 'as QuartzComponent' type casts from quartz.layout.ts - Community plugin components now directly assignable without casts * feat: add PageType plugin infrastructure (Phase D Step 4) * feat: add PageTypePluginEntry for cross-boundary type compatibility Introduce PageTypePluginEntry with never[] parameter types to accept both internal and community PageType plugins in config arrays without casts, working around branded FullSlug contravariance mismatch. * refactor: update dispatcher to cast PageTypePluginEntry at boundary Add getPageTypes() helper that casts config's PageTypePluginEntry[] to QuartzPageTypePluginInstance[] in one place. Cast VirtualPage.slug to FullSlug at emitPage/defaultProcessedContent call sites. * feat: integrate community PageType plugins (Phase D Step 6) Replace old page-rendering emitters with PageTypeDispatcher emitter and pageTypes array. Restructure quartz.layout.ts from three separate exports to unified layout object with defaults and byPageType record. Install content-page, folder-page, tag-page community plugins. * refactor: delete old page-rendering emitters Remove ContentPage, FolderPage, TagPage, and NotFoundPage emitters now replaced by community PageType plugins and the PageTypeDispatcher. * refactor: remove migrated page body components Delete Content, FolderContent, TagContent page components now provided by community PageType plugins. Update components barrel export. * fix: update lockfile to fixed folder-page and tag-page commits Points to commits that remove duplicate PageList/SortFn re-exports, fixing TS2300 duplicate identifier errors in generated plugin index. * chore: updated plugins * fix: populate ctx.trie in PageTypeDispatcher before rendering Components like FolderContent depend on ctx.trie for folder hierarchy. The dispatcher now lazily initializes it via trieFromAllFiles in emit and force-rebuilds it in partialEmit to reflect file changes. * chore: update lockfile to fixed folder-page commit * chore: updated plugins * chore: update explorer plugin to fix SPA folder navigation * feat: extract transformers to community plugins and fix type compatibility - Delete 12 internal transformer files (keep FrontMatter as internal) - Switch quartz.config.ts to use ExternalPlugin.* for all transformers - Align branded types with @quartz-community/types (_brand, FullSlug etc.) - Add vfile DataMap augmentations for fields from extracted transformers - Update all 29 plugins to @quartz-community/types v0.2.1 * Migrate filters to external plugins (remove-draft, explicit-publish) Delete internal RemoveDrafts and ExplicitPublish filter implementations, install them as community plugins, and update quartz.config.ts to use ExternalPlugin.RemoveDrafts(). * Migrate emitters to external plugins (alias-redirects, cname, favicon, content-index, og-image) * refactor: remove inline scripts/styles migrated to plugins Delete dead code: callout, checkbox, mermaid inline scripts and styles are now bundled by the obsidian-flavored-markdown plugin. Clipboard script and styles moved to the syntax-highlighting plugin. listPage.scss was unreferenced. Body.tsx simplified to a pure layout wrapper. * refactor: consolidate utils to re-export from @quartz-community/utils * fix: use dangerouslySetInnerHTML for inline CSS to prevent HTML-escaping Preact was escaping & characters in SCSS-compiled CSS (e.g. & nesting) into &, breaking CSS rules. Using dangerouslySetInnerHTML bypasses the escaping, matching how browsers expect style element content. * chore: update plugins with inline script transpilation fix * chore: updated plugins * docs: update plugin API sections for v5 community plugins * docs: rewrite documentation for v5 plugin system Update feature docs, hosting, CI/CD, getting started, configuration, layout, architecture, creating components, making plugins, and migration guide to reflect the v5 community plugin architecture. * docs: fix outdated v4 references in documentation * chore: remove completed migration planning docs * chore: updated plugins * chore: cleanup * chore: cleanup * chore: bump version to 5.0.0 * chore: updated dependencies * feat: integrate CanvasPage plugin with types, assets, config, layout, and documentation * chore: updated dependencies * chore: updated dependencies * chore: updated linter * chore: update canvas-page plugin to c942fcb * chore: updated plugins * chore: update canvas-page plugin to f88f1b9 * chore: updated plugins * chore: update canvas-page plugin to 079304c * chore: updated plugins * chore: canvas layout * chore: update canvas-page plugin to 38d49e1 * chore: updated plugins * chore: update canvas-page plugin to 505c099 * chore: updated plugins * chore: updated plugins * fix: Obsidian flavored markdown * fix: Obsidian flavored markdown * fix: Obsidian flavored markdown * chore: cleanup * chore: updated plugins * feat: configuration files * feat: Quartz TUI * feat(tui): YAML configuration * chore: tsup * chore: tsup * feat: support array categories in plugin manifests Plugins like note-properties export both transformer and component functionality. Allow PluginManifest.category to be a single value or an array, with config-loader resolving to the first processing category (transformer/filter/emitter/pageType) for dispatch. * refactor: remove built-in FrontMatter transformer Frontmatter processing is now handled by the note-properties plugin, which provides the same YAML/TOML parsing plus link extraction and a visual properties panel. The built-in transformer is no longer needed. * feat: add note-properties plugin to default configuration Register note-properties as the first plugin (order 5) in both the user config and the default config. Placed in beforeBody layout zone with priority 15 (between article-title at 10 and content-meta at 20). * docs: add plugin management strategy and syncer v5 notes Document the plugin management system design decisions and provide implementation guidance for the Quartz Syncer v5 integration. * feat: add bases-page plugin to default configuration Enable Obsidian Bases (.base) file support with bases page type and layout entry in both user and default config. * docs: update syncer notes with bases-page, note-properties, and spacer Add all three new plugins to the quick reference table (40 total). Add content, canvas, and bases page types to byPageType documentation. * chore: updated plugins * fix: update CI to Node 24 and regenerate lockfiles for clean install * fix: resolve type errors for CI checks * chore: updated plugins * chore: updated plugins * fix: plugin mapping from configuration * fix: CI * fix: CI * docs: rewrite Frontmatter documentation for note-properties plugin * chore: updated plugins * docs: Quartz v5 * chore: updated plugins * chore: updated plugins * refactor: extract TUI to standalone plugin repository * chore: linting * docs: Quartz v5 * feat: update and upgrade commands * chore: updated plugins * chore: updated plugins * chore: cleanup * chore: cleanup * chore: cleanup * chore: cleanup * chore: cleanup * fix: layout group priority * fix: view classes * fix: include virtual pages in content index for explorer visibility * docs: add board, gallery, and cards view examples to navigation page * chore: updated plugins * fix: include virtualPages in worker serializable build context * fix: set relativePath on virtual pages to prevent explorer crash * fix: exclude 404 * fix(links): virtual page links * fix(links): virtual page transclusion * docs: architecture overview * fix: only call scripts one per page * fix: type error in component registry instantiate method * fix: left layout order * fix(layout): remove tag-list by default * docs(plugins): updated plugin list defaults * fix(layout): priorities * feat: add PageFrame system for custom page layouts * feat: integrate PageFrame into rendering pipeline * feat: add frame resolution to page type dispatcher and config loader * style: add CSS grid overrides for full-width and minimal page frames * feat: set minimal frame for 404 and update canvas-page plugin * docs: add PageFrame system to architecture overview * fix: wrap frame.render() in array to satisfy Body children type * chore: format * fix: use absolute asset paths for 404 page so it works in subdirectories * fix(layout): priorities * docs: page frames * feat: add FrameRegistry for plugin-provided page frames Plugins can now register custom page frames via their manifest's 'frames' field. Frames are loaded alongside components during plugin initialization and resolved by name at render time with fallback to built-in frames. * feat(layout): page frames * fix(layout): linting * fix: inject frame CSS into page so plugin-provided frames render correctly * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * docs: canvas * chore: updated plugins * chore: updated plugins * chore: updated plugins * feat: add TreeTransform hook, fix multi-category plugins, and resolve cross-plugin dependencies - Add TreeTransform type and treeTransforms hook to pageType plugins, enabling render-time HAST tree mutations (e.g. bases-page inline codeblock resolution) - Fix config-loader to push multi-category plugins into ALL matching processing buckets instead of only the first match - Add side-effect import for component-only plugins so view registrations (e.g. leaflet-map via globalThis ViewRegistry) execute at load time - Add npm prune --omit=dev and cross-plugin peer dependency symlinking to buildPlugin() to prevent duplicate-singleton issues from nested node_modules * chore: format * chore: test docs * chore: updated plugins * fix: prevent HTML-escaping of inline style and script content in htmlToJsx Add dangerouslySetInnerHTML overrides for <style> and <script> elements so that CSS/JS injected by tree transforms is not HTML-escaped during preact-render-to-string serialization. * chore: update plugin lockfile for htmlToJsx migration * chore: update leaflet-map plugin (fix deferred L.Control) * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: updated plugins * chore: test npx quartz upgrade * feat(templates): add obsidian, ttrpg, blog templates * docs: move bases * docs: removed leaflet demo * feat(cli): configure baseUrl during create * docs: updated cli commands * docs: updated documentation for v5 * feat(cli): prune and resolve * chore: rebuild lockfile * docs: cli documentation * docs: plugin development and setup guide * chore: deleted redundant files * fix(build): fallback config * chore: updated lockfile * docs: removed outdated v3 setup * feat(cli): allow non-default branch plugins * docs: install branch commands * feat(cli): allow local plugins * docs: install local commands * feat: add render event type and listener for in-place DOM re-initialization * docs: add EncryptedPages plugin documentation * docs: add encrypted pages live demo page - New password-protected demo page (password: quartz) showing the plugin in action - Link to demo from EncryptedPages plugin page with password hint callout * feat: add encrypted-pages plugin to all templates - Enabled by default in default, obsidian, and ttrpg templates - Disabled by default in blog template * chore: updated plugins * chore: updated layouts * chore: updated plugins * feat: stacked pages * feat: added stacked page panes * docs: touch-ups
This commit is contained in:
Emile Bangma
21
docs/features/Bases.md
Normal file
21
docs/features/Bases.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Bases Support
|
||||
tags:
|
||||
- component
|
||||
---
|
||||
|
||||
Quartz supports rendering [Obsidian Bases](https://obsidian.md/changelog/2025-04-15-desktop-v1.8.0/) (`.base` files) as interactive database-like views. Bases files define queries over your vault's notes and display the results in configurable views such as tables, lists, cards, galleries, and boards.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
Bases support is provided by the [[BasesPage]] plugin. See the plugin page for configuration options, built-in views, the expression engine, and how to extend with custom views.
|
||||
|
||||
## Demo
|
||||
|
||||
![[Base.base]]
|
||||
|
||||
## Customization
|
||||
|
||||
- Install: `npx quartz plugin add github:quartz-community/bases-page`
|
||||
- Source: [`quartz-community/bases-page`](https://github.com/quartz-community/bases-page)
|
||||
21
docs/features/Canvas.md
Normal file
21
docs/features/Canvas.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Canvas Support
|
||||
tags:
|
||||
- component
|
||||
---
|
||||
|
||||
Quartz supports rendering [JSON Canvas](https://jsoncanvas.org) (`.canvas`) files as interactive, pannable and zoomable canvas pages. This brings your Obsidian canvas files to the web, preserving text nodes, file references, link nodes, group nodes, and edges with full visual fidelity.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
Canvas support is provided by the [[CanvasPage]] plugin. See the plugin page for configuration options and a full list of supported features.
|
||||
|
||||
## Demo
|
||||
|
||||
![[Canvas.canvas]]
|
||||
|
||||
## Customization
|
||||
|
||||
- Install: `npx quartz plugin add github:quartz-community/canvas-page`
|
||||
- Source: [`quartz-community/canvas-page`](https://github.com/quartz-community/canvas-page)
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
title: "Docker Support"
|
||||
tags:
|
||||
- feature
|
||||
---
|
||||
|
||||
Quartz comes shipped with a Docker image that will allow you to preview your Quartz locally without installing Node.
|
||||
|
||||
You can run the below one-liner to run Quartz in Docker.
|
||||
|
||||
@@ -70,10 +70,9 @@ For example:
|
||||
|
||||
### Using mhchem
|
||||
|
||||
Add the following import to the top of `quartz/plugins/transformers/latex.ts` (before all the other
|
||||
imports):
|
||||
If you are using the community Latex plugin, you can add `mhchem` support by forking the plugin repository and adding the following import to the top of `src/index.ts` (before all the other imports):
|
||||
|
||||
```ts title="quartz/plugins/transformers/latex.ts"
|
||||
```ts title="src/index.ts"
|
||||
import "katex/contrib/mhchem"
|
||||
```
|
||||
|
||||
|
||||
@@ -12,6 +12,188 @@ It also ships with support for [frontmatter parsing](https://help.obsidian.md/Ed
|
||||
|
||||
Finally, Quartz also provides [[CrawlLinks]] plugin, which allows you to customize Quartz's link resolution behaviour to match Obsidian.
|
||||
|
||||
## Supported Features
|
||||
|
||||
### Wikilinks
|
||||
|
||||
Internal links using the `[[page]]` syntax are converted to regular links. See [[wikilinks]] for more details. All variations are supported:
|
||||
|
||||
```markdown
|
||||
[[Page]] Link to a page
|
||||
[[Page|Custom text]] Link with alias
|
||||
[[Page#Heading]] Link to a heading
|
||||
[[Page#Heading|Custom text]] Link to a heading with alias
|
||||
[[Page#^block-id]] Link to a block reference
|
||||
![[Page]] Embed (transclude) a page
|
||||
![[image.png]] Embed an image
|
||||
![[image.png|alt 100x200]] Embed with alt text and dimensions
|
||||
```
|
||||
|
||||
Inside tables, pipes in wikilinks can be escaped with a backslash:
|
||||
|
||||
```markdown
|
||||
| Column |
|
||||
| --------------- |
|
||||
| [[page\|alias]] |
|
||||
```
|
||||
|
||||
### Highlights
|
||||
|
||||
Wrap text in `==` to highlight it:
|
||||
|
||||
```markdown
|
||||
This is ==highlighted text== in a sentence.
|
||||
```
|
||||
|
||||
This renders as: This is ==highlighted text== in a sentence.
|
||||
|
||||
### Comments
|
||||
|
||||
Obsidian-style comments are stripped from the output:
|
||||
|
||||
```markdown
|
||||
This is visible. %%This is a comment and won't appear.%%
|
||||
```
|
||||
|
||||
This renders as: This is visible. %%This is a comment and won't appear.%%
|
||||
|
||||
Multi-line comments are also supported:
|
||||
|
||||
```markdown
|
||||
%%
|
||||
This entire block
|
||||
is a comment.
|
||||
%%
|
||||
```
|
||||
|
||||
### Tags
|
||||
|
||||
Tags starting with `#` are parsed and linked to tag pages:
|
||||
|
||||
```markdown
|
||||
#tag #nested/tag #tag-with-dashes
|
||||
```
|
||||
|
||||
For example: #feature/transformer
|
||||
|
||||
> [!note]
|
||||
> Pure numeric tags like `#123` are ignored, matching Obsidian behaviour.
|
||||
|
||||
### Callouts
|
||||
|
||||
[[callouts|Obsidian callouts]] are fully supported, including collapsible variants:
|
||||
|
||||
```markdown
|
||||
> [!note]
|
||||
> This is a note callout.
|
||||
|
||||
> [!warning]- Collapsed by default
|
||||
> This content is hidden initially.
|
||||
|
||||
> [!tip]+ Expanded by default
|
||||
> This content is visible initially.
|
||||
```
|
||||
|
||||
> [!example] Live example
|
||||
> This is a live callout rendered from Obsidian-flavored Markdown.
|
||||
|
||||
All built-in callout types are supported: `note`, `abstract`, `info`, `todo`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, and `quote`, along with their aliases.
|
||||
|
||||
### Task Lists and Custom Task Characters
|
||||
|
||||
Standard checkboxes work out of the box. With `enableCheckbox: true`, you also get support for custom task characters that are popular in the Obsidian community:
|
||||
|
||||
```markdown
|
||||
- [ ] Unchecked
|
||||
- [x] Checked
|
||||
- [?] Question
|
||||
- [!] Important
|
||||
- [>] Forwarded
|
||||
- [/] In progress
|
||||
- [-] Cancelled
|
||||
- [s] Special
|
||||
```
|
||||
|
||||
Each custom character is preserved as a `data-task` attribute on the rendered element, allowing CSS-based styling per character.
|
||||
|
||||
- [ ] Unchecked
|
||||
- [x] Checked
|
||||
- [?] Question
|
||||
- [!] Important
|
||||
|
||||
### Mermaid Diagrams
|
||||
|
||||
[[Mermaid diagrams|Mermaid]] code blocks are rendered as diagrams:
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start] --> B{Decision}
|
||||
B -->|Yes| C[OK]
|
||||
B -->|No| D[Cancel]
|
||||
```
|
||||
````
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start] --> B{Decision}
|
||||
B -->|Yes| C[OK]
|
||||
B -->|No| D[Cancel]
|
||||
```
|
||||
|
||||
### YouTube Embeds
|
||||
|
||||
YouTube videos can be embedded using standard image syntax with a YouTube URL:
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
```
|
||||
|
||||
For example, the following embed is rendered from ``:
|
||||
|
||||
|
||||
|
||||
### Tweet Embeds
|
||||
|
||||
Tweets from Twitter/X are embedded as static blockquotes with a link to the original:
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
```
|
||||
|
||||
For example, the following embed is rendered from ``:
|
||||
|
||||
|
||||
|
||||
### Block References
|
||||
|
||||
Block references allow linking to specific blocks within a page:
|
||||
|
||||
```markdown
|
||||
Content paragraph. ^my-block
|
||||
|
||||
[[Page#^my-block]]
|
||||
```
|
||||
|
||||
### Obsidian URI Links
|
||||
|
||||
Links using the `obsidian://` protocol are marked with a CSS class (`obsidian-uri`) and a `data-obsidian-uri` attribute, so you can style them differently from regular links.
|
||||
|
||||
### Video Embeds
|
||||
|
||||
Video files can be embedded using standard image syntax:
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Embed in HTML
|
||||
|
||||
By default, Obsidian does not render its Markdown syntax inside HTML blocks. Quartz extends this with the `enableInHtmlEmbed` option, which parses wikilinks, highlights, and tags inside raw HTML nodes.
|
||||
|
||||
## Configuration
|
||||
|
||||
This functionality is provided by the [[ObsidianFlavoredMarkdown]], [[Frontmatter]] and [[CrawlLinks]] plugins. See the plugin pages for customization options.
|
||||
|
||||
@@ -8,18 +8,42 @@ tags:
|
||||
|
||||
Because the Markdown generated by ox-hugo is not pure Markdown but Hugo specific, we need to transform it to fit into Quartz. This is done by the [[OxHugoFlavoredMarkdown]] plugin. Even though this plugin was written with `ox-hugo` in mind, it should work for any Hugo specific Markdown.
|
||||
|
||||
```typescript title="quartz.config.ts"
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/obsidian-flavored-markdown
|
||||
enabled: true
|
||||
order: 30
|
||||
- source: github:quartz-community/ox-hugo
|
||||
enabled: true
|
||||
order: 25 # must come before obsidian-flavored-markdown
|
||||
- source: github:quartz-community/github-flavored-markdown
|
||||
enabled: true
|
||||
order: 40
|
||||
- source: github:quartz-community/note-properties
|
||||
enabled: true
|
||||
options:
|
||||
delimiters: "+++"
|
||||
language: toml # if using toml frontmatter
|
||||
order: 5
|
||||
```
|
||||
|
||||
For the TS override approach:
|
||||
|
||||
```ts title="quartz.ts (override)"
|
||||
plugins: {
|
||||
transformers: [
|
||||
Plugin.FrontMatter({ delims: "+++", language: "toml" }), // if toml frontmatter
|
||||
ExternalPlugin.FrontMatter({ delims: "+++", language: "toml" }),
|
||||
// ...
|
||||
Plugin.OxHugoFlavouredMarkdown(),
|
||||
Plugin.GitHubFlavoredMarkdown(),
|
||||
ExternalPlugin.OxHugoFlavouredMarkdown(),
|
||||
ExternalPlugin.GitHubFlavoredMarkdown(),
|
||||
// ...
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> In YAML, plugin execution order is controlled by the `order` field. Lower numbers execute first. Ensure `ox-hugo` has a lower `order` than `obsidian-flavored-markdown`.
|
||||
|
||||
## Usage
|
||||
|
||||
Quartz by default doesn't understand `org-roam` files as they aren't Markdown. You're responsible for using an external tool like `ox-hugo` to export the `org-roam` files as Markdown content to Quartz and managing the static assets so that they're available in the final output.
|
||||
|
||||
@@ -9,19 +9,31 @@ tags:
|
||||
Quartz supports transforming the special Markdown syntax from Roam Research (like `{{[[components]]}}` and other formatting) into
|
||||
regular Markdown via the [[RoamFlavoredMarkdown]] plugin.
|
||||
|
||||
```typescript title="quartz.config.ts"
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/roam
|
||||
enabled: true
|
||||
order: 25 # must come before obsidian-flavored-markdown
|
||||
- source: github:quartz-community/obsidian-flavored-markdown
|
||||
enabled: true
|
||||
order: 30
|
||||
```
|
||||
|
||||
For the TS override approach:
|
||||
|
||||
```ts title="quartz.ts (override)"
|
||||
plugins: {
|
||||
transformers: [
|
||||
// ...
|
||||
Plugin.RoamFlavoredMarkdown(),
|
||||
Plugin.ObsidianFlavoredMarkdown(),
|
||||
ExternalPlugin.RoamFlavoredMarkdown(),
|
||||
ExternalPlugin.ObsidianFlavoredMarkdown(),
|
||||
// ...
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
> [!warning]
|
||||
> As seen above placement of `Plugin.RoamFlavoredMarkdown()` within `quartz.config.ts` is very important. It must come before `Plugin.ObsidianFlavoredMarkdown()`.
|
||||
> In YAML, plugin execution order is controlled by the `order` field. Ensure `roam` has a lower `order` value than `obsidian-flavored-markdown` so it runs first.
|
||||
|
||||
## Customization
|
||||
|
||||
|
||||
@@ -1,7 +1,13 @@
|
||||
---
|
||||
title: "SPA Routing"
|
||||
tags:
|
||||
- feature
|
||||
---
|
||||
|
||||
Single-page-app style rendering. This prevents flashes of unstyled content and improves the smoothness of Quartz.
|
||||
|
||||
Under the hood, this is done by hijacking page navigations and instead fetching the HTML via a `GET` request and then diffing and selectively replacing parts of the page using [micromorph](https://github.com/natemoo-re/micromorph). This allows us to change the content of the page without fully refreshing the page, reducing the amount of content that the browser needs to load.
|
||||
|
||||
## Configuration
|
||||
|
||||
- Disable SPA Routing: set the `enableSPA` field of the [[configuration]] in `quartz.config.ts` to be `false`.
|
||||
- Disable SPA Routing: set the `enableSPA` field of the [[configuration]] in `quartz.config.yaml` to be `false`.
|
||||
|
||||
@@ -6,10 +6,12 @@ tags:
|
||||
|
||||
A backlink for a note is a link from another note to that note. Links in the backlink pane also feature rich [[popover previews]] if you have that feature enabled.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
## Customization
|
||||
|
||||
- Removing backlinks: delete all usages of `Component.Backlinks()` from `quartz.layout.ts`.
|
||||
- Hide when empty: hide `Backlinks` if given page doesn't contain any backlinks (default to `true`). To disable this, use `Component.Backlinks({ hideWhenEmpty: false })`.
|
||||
- Component: `quartz/components/Backlinks.tsx`
|
||||
- Style: `quartz/components/styles/backlinks.scss`
|
||||
- Script: `quartz/components/scripts/search.inline.ts`
|
||||
- Removing backlinks: remove the `backlinks` entry from `quartz.config.yaml` or set `enabled: false`.
|
||||
- Hide when empty: hide `Backlinks` if given page doesn't contain any backlinks (default to `true`). To disable this, set `hideWhenEmpty: false` in the plugin options in `quartz.config.yaml`.
|
||||
- Install: `npx quartz plugin add github:quartz-community/backlinks`
|
||||
- Source: [`quartz-community/backlinks`](https://github.com/quartz-community/backlinks)
|
||||
|
||||
@@ -8,28 +8,46 @@ Breadcrumbs provide a way to navigate a hierarchy of pages within your site usin
|
||||
|
||||
By default, the element at the very top of your page is the breadcrumb navigation bar (can also be seen at the top on this page!).
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
## Customization
|
||||
|
||||
Most configuration can be done by passing in options to `Component.Breadcrumbs()`.
|
||||
Most configuration can be done via the `options` section of the breadcrumbs plugin entry in `quartz.config.yaml`.
|
||||
|
||||
For example, here's what the default configuration looks like:
|
||||
|
||||
```typescript title="quartz.layout.ts"
|
||||
Component.Breadcrumbs({
|
||||
spacerSymbol: "❯", // symbol between crumbs
|
||||
rootName: "Home", // name of first/root element
|
||||
resolveFrontmatterTitle: true, // whether to resolve folder names through frontmatter titles
|
||||
showCurrentPage: true, // whether to display the current page in the breadcrumbs
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/breadcrumbs
|
||||
enabled: true
|
||||
options:
|
||||
spacerSymbol: "❯"
|
||||
rootName: Home
|
||||
resolveFrontmatterTitle: true
|
||||
showCurrentPage: true
|
||||
layout:
|
||||
position: beforeBody
|
||||
priority: 5
|
||||
```
|
||||
|
||||
For the TS override approach:
|
||||
|
||||
```ts title="quartz.ts (override)"
|
||||
ExternalPlugin.Breadcrumbs({
|
||||
spacerSymbol: "❯",
|
||||
rootName: "Home",
|
||||
resolveFrontmatterTitle: true,
|
||||
showCurrentPage: true,
|
||||
})
|
||||
```
|
||||
|
||||
When passing in your own options, you can omit any or all of these fields if you'd like to keep the default value for that field.
|
||||
|
||||
You can also adjust where the breadcrumbs will be displayed by adjusting the [[layout]] (moving `Component.Breadcrumbs()` up or down)
|
||||
You can also adjust where the breadcrumbs will be displayed by changing the `layout.position` field in the plugin entry in `quartz.config.yaml` (see [[layout]]).
|
||||
|
||||
Want to customize it even more?
|
||||
|
||||
- Removing breadcrumbs: delete all usages of `Component.Breadcrumbs()` from `quartz.layout.ts`.
|
||||
- Component: `quartz/components/Breadcrumbs.tsx`
|
||||
- Style: `quartz/components/styles/breadcrumbs.scss`
|
||||
- Script: inline at `quartz/components/Breadcrumbs.tsx`
|
||||
- Removing breadcrumbs: remove the `breadcrumbs` entry from `quartz.config.yaml` or set `enabled: false`.
|
||||
- Install: `npx quartz plugin add github:quartz-community/breadcrumbs`
|
||||
- Source: [`quartz-community/breadcrumbs`](https://github.com/quartz-community/breadcrumbs)
|
||||
|
||||
@@ -6,6 +6,9 @@ tags:
|
||||
|
||||
Quartz also has the ability to hook into various providers to enable readers to leave comments on your site.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
![[giscus-example.png]]
|
||||
|
||||
As of today, only [Giscus](https://giscus.app/) is supported out of the box but PRs to support other providers are welcome!
|
||||
@@ -30,28 +33,54 @@ After entering both your repository and selecting the discussion category, Giscu
|
||||
|
||||
![[giscus-results.png]]
|
||||
|
||||
Finally, in `quartz.layout.ts`, edit the `afterBody` field of `sharedPageComponents` to include the following options but with the values you got from above:
|
||||
Finally, in `quartz.config.yaml`, add the comments plugin with the following options (using the values you got from above):
|
||||
|
||||
```ts title="quartz.layout.ts"
|
||||
afterBody: [
|
||||
Component.Comments({
|
||||
provider: 'giscus',
|
||||
options: {
|
||||
// from data-repo
|
||||
repo: 'jackyzha0/quartz',
|
||||
// from data-repo-id
|
||||
repoId: 'MDEwOlJlcG9zaXRvcnkzODcyMTMyMDg',
|
||||
// from data-category
|
||||
category: 'Announcements',
|
||||
// from data-category-id
|
||||
categoryId: 'DIC_kwDOFxRnmM4B-Xg6',
|
||||
// from data-lang
|
||||
lang: 'en'
|
||||
}
|
||||
}),
|
||||
],
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/comments
|
||||
enabled: true
|
||||
options:
|
||||
provider: giscus
|
||||
options:
|
||||
repo: jackyzha0/quartz
|
||||
repoId: MDEwOlJlcG9zaXRvcnkzODcyMTMyMDg
|
||||
category: Announcements
|
||||
categoryId: DIC_kwDOFxRnmM4B-Xg6
|
||||
lang: en
|
||||
layout:
|
||||
position: afterBody
|
||||
priority: 10
|
||||
```
|
||||
|
||||
For the TS override approach:
|
||||
|
||||
```ts title="quartz.ts (override)"
|
||||
// If using quartz.ts overrides instead of YAML:
|
||||
import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"
|
||||
|
||||
const config = await loadQuartzConfig()
|
||||
export default config
|
||||
export const layout = await loadQuartzLayout({
|
||||
defaults: {
|
||||
afterBody: [
|
||||
ExternalPlugin.Comments({
|
||||
provider: "giscus",
|
||||
options: {
|
||||
repo: "jackyzha0/quartz",
|
||||
repoId: "MDEwOlJlcG9zaXRvcnkzODcyMTMyMDg",
|
||||
category: "Announcements",
|
||||
categoryId: "DIC_kwDOFxRnmM4B-Xg6",
|
||||
lang: "en",
|
||||
},
|
||||
}),
|
||||
],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> Install the comments plugin first: `npx quartz plugin add github:quartz-community/comments`
|
||||
|
||||
### Customization
|
||||
|
||||
Quartz also exposes a few of the other Giscus options as well and you can provide them the same way `repo`, `repoId`, `category`, and `categoryId` are provided.
|
||||
@@ -106,19 +135,39 @@ Quartz supports custom theme for Giscus. To use a custom CSS theme, place the `.
|
||||
|
||||
For example, if you have a light theme `light-theme.css`, a dark theme `dark-theme.css`, and your Quartz site is hosted at `https://example.com/`:
|
||||
|
||||
```ts
|
||||
afterBody: [
|
||||
Component.Comments({
|
||||
provider: 'giscus',
|
||||
options: {
|
||||
// Other options
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/comments
|
||||
enabled: true
|
||||
options:
|
||||
provider: giscus
|
||||
options:
|
||||
# Other options...
|
||||
themeUrl: "https://example.com/static/giscus" # corresponds to quartz/static/giscus/
|
||||
lightTheme: light-theme # corresponds to light-theme.css in quartz/static/giscus/
|
||||
darkTheme: dark-theme # corresponds to dark-theme.css in quartz/static/giscus/
|
||||
```
|
||||
|
||||
themeUrl: "https://example.com/static/giscus", // corresponds to quartz/static/giscus/
|
||||
lightTheme: "light-theme", // corresponds to light-theme.css in quartz/static/giscus/
|
||||
darkTheme: "dark-theme", // corresponds to dark-theme.css quartz/static/giscus/
|
||||
}
|
||||
}),
|
||||
],
|
||||
```ts title="quartz.ts (override)"
|
||||
import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"
|
||||
|
||||
const config = await loadQuartzConfig()
|
||||
export default config
|
||||
export const layout = await loadQuartzLayout({
|
||||
defaults: {
|
||||
afterBody: [
|
||||
ExternalPlugin.Comments({
|
||||
provider: "giscus",
|
||||
options: {
|
||||
// Other options...
|
||||
themeUrl: "https://example.com/static/giscus",
|
||||
lightTheme: "light-theme",
|
||||
darkTheme: "dark-theme",
|
||||
},
|
||||
}),
|
||||
],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
#### Conditionally display comments
|
||||
|
||||
@@ -6,12 +6,14 @@ tags:
|
||||
|
||||
Quartz supports darkmode out of the box that respects the user's theme preference. Any future manual toggles of the darkmode switch will be saved in the browser's local storage so it can be persisted across future page loads.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
## Customization
|
||||
|
||||
- Removing darkmode: delete all usages of `Component.Darkmode()` from `quartz.layout.ts`.
|
||||
- Component: `quartz/components/Darkmode.tsx`
|
||||
- Style: `quartz/components/styles/darkmode.scss`
|
||||
- Script: `quartz/components/scripts/darkmode.inline.ts`
|
||||
- Removing darkmode: remove the `darkmode` entry from `quartz.config.yaml` or set `enabled: false`.
|
||||
- Install: `npx quartz plugin add github:quartz-community/darkmode`
|
||||
- Source: [`quartz-community/darkmode`](https://github.com/quartz-community/darkmode)
|
||||
|
||||
You can also listen to the `themechange` event to perform any custom logic when the theme changes.
|
||||
|
||||
|
||||
@@ -6,6 +6,30 @@ tags:
|
||||
|
||||
Quartz features an explorer that allows you to navigate all files and folders on your site. It supports nested folders and is highly customizable.
|
||||
|
||||
> [!info]
|
||||
> The Explorer is now a community plugin. This demonstrates how external plugins can extend Quartz functionality while serving as a reference implementation for plugin developers.
|
||||
|
||||
## Installation
|
||||
|
||||
The Explorer is available as a community plugin from GitHub:
|
||||
|
||||
```bash
|
||||
npm install github:quartz-community/explorer --legacy-peer-deps
|
||||
```
|
||||
|
||||
Then add it to your `quartz.config.yaml`:
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/explorer
|
||||
enabled: true
|
||||
layout:
|
||||
position: left
|
||||
priority: 50
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
By default, it shows all folders and files on your page. To display the explorer in a different spot, you can edit the [[layout]].
|
||||
|
||||
Display names for folders get determined by the `title` frontmatter field in `folder/index.md` (more detail in [[authoring content | Authoring Content]]). If this file does not exist or does not contain frontmatter, the local folder name will be used instead.
|
||||
@@ -17,42 +41,63 @@ Display names for folders get determined by the `title` frontmatter field in `fo
|
||||
|
||||
## Customization
|
||||
|
||||
Most configuration can be done by passing in options to `Component.Explorer()`.
|
||||
Most configuration can be done by passing in options to `Explorer()`.
|
||||
|
||||
For example, here's what the default configuration looks like:
|
||||
|
||||
```typescript title="quartz.layout.ts"
|
||||
Component.Explorer({
|
||||
title: "Explorer", // title of the explorer component
|
||||
folderClickBehavior: "collapse", // what happens when you click a folder ("link" to navigate to folder page on click or "collapse" to collapse folder on click)
|
||||
folderDefaultState: "collapsed", // default state of folders ("collapsed" or "open")
|
||||
useSavedState: true, // whether to use local storage to save "state" (which folders are opened) of explorer
|
||||
// omitted but shown later
|
||||
sortFn: ...,
|
||||
filterFn: ...,
|
||||
mapFn: ...,
|
||||
// what order to apply functions in
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/explorer
|
||||
enabled: true
|
||||
options:
|
||||
title: Explorer
|
||||
folderClickBehavior: collapse # "link" to navigate or "collapse" to toggle
|
||||
folderDefaultState: collapsed # "collapsed" or "open"
|
||||
useSavedState: true
|
||||
layout:
|
||||
position: left
|
||||
priority: 50
|
||||
```
|
||||
|
||||
For advanced options like custom sort, filter, and map functions, use the TS override in `quartz.ts`:
|
||||
|
||||
```ts title="quartz.ts"
|
||||
import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"
|
||||
import { Explorer } from "@quartz-community/explorer"
|
||||
|
||||
// Advanced: pass callback functions that can't be expressed in YAML
|
||||
Explorer({
|
||||
sortFn: (a, b) => {
|
||||
/* ... */
|
||||
},
|
||||
filterFn: (node) => {
|
||||
/* ... */
|
||||
},
|
||||
mapFn: (node) => {
|
||||
/* ... */
|
||||
},
|
||||
order: ["filter", "map", "sort"],
|
||||
})
|
||||
|
||||
const config = await loadQuartzConfig()
|
||||
export default config
|
||||
export const layout = await loadQuartzLayout()
|
||||
```
|
||||
|
||||
When passing in your own options, you can omit any or all of these fields if you'd like to keep the default value for that field.
|
||||
|
||||
Want to customize it even more?
|
||||
|
||||
- Removing explorer: remove `Component.Explorer()` from `quartz.layout.ts`
|
||||
- Removing explorer: remove the `explorer` entry from `quartz.config.yaml` or set `enabled: false`
|
||||
- (optional): After removing the explorer component, you can move the [[table of contents | Table of Contents]] component back to the `left` part of the layout
|
||||
- Changing `sort`, `filter` and `map` behavior: explained in [[#Advanced customization]]
|
||||
- Component: `quartz/components/Explorer.tsx`
|
||||
- Style: `quartz/components/styles/explorer.scss`
|
||||
- Script: `quartz/components/scripts/explorer.inline.ts`
|
||||
|
||||
## Advanced customization
|
||||
|
||||
This component allows you to fully customize all of its behavior. You can pass a custom `sort`, `filter` and `map` function.
|
||||
All functions you can pass work with the `FileTrieNode` class, which has the following properties:
|
||||
|
||||
```ts title="quartz/components/Explorer.tsx"
|
||||
```ts title="@quartz-community/explorer"
|
||||
class FileTrieNode {
|
||||
isFolder: boolean
|
||||
children: Array<FileTrieNode>
|
||||
@@ -60,7 +105,7 @@ class FileTrieNode {
|
||||
}
|
||||
```
|
||||
|
||||
```ts title="quartz/plugins/emitters/contentIndex.tsx"
|
||||
```ts
|
||||
export type ContentDetails = {
|
||||
slug: FullSlug
|
||||
title: string
|
||||
@@ -74,7 +119,7 @@ Every function you can pass is optional. By default, only a `sort` function will
|
||||
|
||||
```ts title="Default sort function"
|
||||
// Sort order: folders first, then files. Sort folders and files alphabetically
|
||||
Component.Explorer({
|
||||
Explorer({
|
||||
sortFn: (a, b) => {
|
||||
if ((!a.isFolder && !b.isFolder) || (a.isFolder && b.isFolder)) {
|
||||
return a.displayName.localeCompare(b.displayName, undefined, {
|
||||
@@ -114,8 +159,20 @@ These examples show the basic usage of `sort`, `map` and `filter`.
|
||||
|
||||
Using this example, the explorer will alphabetically sort everything.
|
||||
|
||||
```ts title="quartz.layout.ts"
|
||||
Component.Explorer({
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/explorer
|
||||
enabled: true
|
||||
options:
|
||||
# Simple options go in YAML
|
||||
title: Explorer
|
||||
folderDefaultState: collapsed
|
||||
```
|
||||
|
||||
Custom sort functions require the TS override:
|
||||
|
||||
```ts title="quartz.ts (override)"
|
||||
Explorer({
|
||||
sortFn: (a, b) => {
|
||||
return a.displayName.localeCompare(b.displayName)
|
||||
},
|
||||
@@ -126,8 +183,8 @@ Component.Explorer({
|
||||
|
||||
Using this example, the display names of all `FileNodes` (folders + files) will be converted to full upper case.
|
||||
|
||||
```ts title="quartz.layout.ts"
|
||||
Component.Explorer({
|
||||
```ts title="quartz.ts (override)"
|
||||
Explorer({
|
||||
mapFn: (node) => {
|
||||
node.displayName = node.displayName.toUpperCase()
|
||||
return node
|
||||
@@ -135,13 +192,16 @@ Component.Explorer({
|
||||
})
|
||||
```
|
||||
|
||||
> [!note]
|
||||
> The `mapFn`, `filterFn`, and `sortFn` options require JavaScript callback functions and cannot be expressed in YAML. Use the TS override for these.
|
||||
|
||||
### Remove list of elements (`filter`)
|
||||
|
||||
Using this example, you can remove elements from your explorer by providing an array of folders/files to exclude.
|
||||
Note that this example filters on the title but you can also do it via slug or any other field available on `FileTrieNode`.
|
||||
|
||||
```ts title="quartz.layout.ts"
|
||||
Component.Explorer({
|
||||
```ts title="quartz.ts (override)"
|
||||
Explorer({
|
||||
filterFn: (node) => {
|
||||
// set containing names of everything you want to filter out
|
||||
const omit = new Set(["authoring content", "tags", "advanced"])
|
||||
@@ -158,8 +218,8 @@ Component.Explorer({
|
||||
|
||||
You can access the tags of a file by `node.data.tags`.
|
||||
|
||||
```ts title="quartz.layout.ts"
|
||||
Component.Explorer({
|
||||
```ts title="quartz.ts (override)"
|
||||
Explorer({
|
||||
filterFn: (node) => {
|
||||
// exclude files with the tag "explorerexclude"
|
||||
return node.data?.tags?.includes("explorerexclude") !== true
|
||||
@@ -172,8 +232,8 @@ Component.Explorer({
|
||||
By default, the explorer will filter out the `tags` folder.
|
||||
To override the default filter function, you can set the filter function to `undefined`.
|
||||
|
||||
```ts title="quartz.layout.ts"
|
||||
Component.Explorer({
|
||||
```ts title="quartz.ts (override)"
|
||||
Explorer({
|
||||
filterFn: undefined, // apply no filter function, every file and folder will visible
|
||||
})
|
||||
```
|
||||
@@ -181,24 +241,24 @@ Component.Explorer({
|
||||
## Advanced examples
|
||||
|
||||
> [!tip]
|
||||
> When writing more complicated functions, the `layout` file can start to look very cramped.
|
||||
> When writing more complicated functions, the `quartz.ts` file can start to look very cramped.
|
||||
> You can fix this by defining your sort functions outside of the component
|
||||
> and passing it in.
|
||||
>
|
||||
> ```ts title="quartz.layout.ts"
|
||||
> import { Options } from "./quartz/components/Explorer"
|
||||
> ```ts title="quartz.ts"
|
||||
> import { ExplorerOptions } from "@quartz-community/explorer/components"
|
||||
>
|
||||
> export const mapFn: Options["mapFn"] = (node) => {
|
||||
> export const mapFn: ExplorerOptions["mapFn"] = (node) => {
|
||||
> // implement your function here
|
||||
> }
|
||||
> export const filterFn: Options["filterFn"] = (node) => {
|
||||
> export const filterFn: ExplorerOptions["filterFn"] = (node) => {
|
||||
> // implement your function here
|
||||
> }
|
||||
> export const sortFn: Options["sortFn"] = (a, b) => {
|
||||
> export const sortFn: ExplorerOptions["sortFn"] = (a, b) => {
|
||||
> // implement your function here
|
||||
> }
|
||||
>
|
||||
> Component.Explorer({
|
||||
> Explorer({
|
||||
> // ... your other options
|
||||
> mapFn,
|
||||
> filterFn,
|
||||
@@ -208,10 +268,10 @@ Component.Explorer({
|
||||
|
||||
### Add emoji prefix
|
||||
|
||||
To add emoji prefixes (📁 for folders, 📄 for files), you could use a map function like this:
|
||||
To add emoji prefixes (📁 for folders, 📄 for files), you could use a map function in `quartz.ts`:
|
||||
|
||||
```ts title="quartz.layout.ts"
|
||||
Component.Explorer({
|
||||
```ts title="quartz.ts (override)"
|
||||
Explorer({
|
||||
mapFn: (node) => {
|
||||
if (node.isFolder) {
|
||||
node.displayName = "📁 " + node.displayName
|
||||
|
||||
@@ -6,6 +6,9 @@ tags:
|
||||
|
||||
Full-text search in Quartz is powered by [Flexsearch](https://github.com/nextapps-de/flexsearch). It's fast enough to return search results in under 10ms for Quartzs as large as half a million words.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
It can be opened by either clicking on the search bar or pressing `⌘`/`ctrl` + `K`. The top 5 search results are shown on each query. Matching subterms are highlighted and the most relevant 30 words are excerpted. Clicking on a search result will navigate to that page.
|
||||
|
||||
To search content by tags, you can either press `⌘`/`ctrl` + `shift` + `K` or start your query with `#` (e.g. `#components`).
|
||||
@@ -23,8 +26,6 @@ It properly tokenizes Chinese, Korean, and Japenese characters and constructs se
|
||||
|
||||
## Customization
|
||||
|
||||
- Removing search: delete all usages of `Component.Search()` from `quartz.layout.ts`.
|
||||
- Component: `quartz/components/Search.tsx`
|
||||
- Style: `quartz/components/styles/search.scss`
|
||||
- Script: `quartz/components/scripts/search.inline.ts`
|
||||
- You can edit `contextWindowWords`, `numSearchResults` or `numTagResults` to suit your needs
|
||||
- Removing search: remove the `search` entry from `quartz.config.yaml` or set `enabled: false`.
|
||||
- Install: `npx quartz plugin add github:quartz-community/search`
|
||||
- Source: [`quartz-community/search`](https://github.com/quartz-community/search)
|
||||
|
||||
@@ -9,6 +9,30 @@ Quartz features a graph-view that can show both a local graph view and a global
|
||||
- The local graph view shows files that either link to the current file or are linked from the current file. In other words, it shows all notes that are _at most_ one hop away.
|
||||
- The global graph view can be toggled by clicking the graph icon on the top-right of the local graph view. It shows _all_ the notes in your graph and how they connect to each other.
|
||||
|
||||
> [!info]
|
||||
> The Graph View is now a community plugin. This demonstrates how external plugins can extend Quartz functionality while serving as a reference implementation for plugin developers.
|
||||
|
||||
## Installation
|
||||
|
||||
The Graph View is available as a community plugin from GitHub:
|
||||
|
||||
```bash
|
||||
npm install github:quartz-community/graph --legacy-peer-deps
|
||||
```
|
||||
|
||||
Then add it to your `quartz.config.yaml`:
|
||||
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/graph
|
||||
enabled: true
|
||||
layout:
|
||||
position: right
|
||||
priority: 10
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
By default, the node radius is proportional to the total number of incoming and outgoing internal links from that file.
|
||||
|
||||
Additionally, similar to how browsers highlight visited links a different colour, the graph view will also show nodes that you have visited in a different colour.
|
||||
@@ -18,48 +42,50 @@ Additionally, similar to how browsers highlight visited links a different colour
|
||||
|
||||
## Customization
|
||||
|
||||
Most configuration can be done by passing in options to `Component.Graph()`.
|
||||
Most configuration can be done by passing in options to `Graph()`.
|
||||
|
||||
For example, here's what the default configuration looks like:
|
||||
|
||||
```typescript title="quartz.layout.ts"
|
||||
Component.Graph({
|
||||
localGraph: {
|
||||
drag: true, // whether to allow panning the view around
|
||||
zoom: true, // whether to allow zooming in and out
|
||||
depth: 1, // how many hops of notes to display
|
||||
scale: 1.1, // default view scale
|
||||
repelForce: 0.5, // how much nodes should repel each other
|
||||
centerForce: 0.3, // how much force to use when trying to center the nodes
|
||||
linkDistance: 30, // how long should the links be by default?
|
||||
fontSize: 0.6, // what size should the node labels be?
|
||||
opacityScale: 1, // how quickly do we fade out the labels when zooming out?
|
||||
removeTags: [], // what tags to remove from the graph
|
||||
showTags: true, // whether to show tags in the graph
|
||||
enableRadial: false, // whether to constrain the graph, similar to Obsidian
|
||||
},
|
||||
globalGraph: {
|
||||
drag: true,
|
||||
zoom: true,
|
||||
depth: -1,
|
||||
scale: 0.9,
|
||||
repelForce: 0.5,
|
||||
centerForce: 0.3,
|
||||
linkDistance: 30,
|
||||
fontSize: 0.6,
|
||||
opacityScale: 1,
|
||||
removeTags: [], // what tags to remove from the graph
|
||||
showTags: true, // whether to show tags in the graph
|
||||
enableRadial: true, // whether to constrain the graph, similar to Obsidian
|
||||
},
|
||||
})
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- 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
|
||||
layout:
|
||||
position: right
|
||||
priority: 10
|
||||
```
|
||||
|
||||
When passing in your own options, you can omit any or all of these fields if you'd like to keep the default value for that field.
|
||||
|
||||
Want to customize it even more?
|
||||
|
||||
- Removing graph view: delete all usages of `Component.Graph()` from `quartz.layout.ts`.
|
||||
- Component: `quartz/components/Graph.tsx`
|
||||
- Style: `quartz/components/styles/graph.scss`
|
||||
- Script: `quartz/components/scripts/graph.inline.ts`
|
||||
- Removing graph view: remove the `graph` entry from `quartz.config.yaml` or set `enabled: false`
|
||||
- Component source: https://github.com/quartz-community/graph
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
title: Internationalization
|
||||
---
|
||||
|
||||
Internationalization allows users to translate text in the Quartz interface into various supported languages without needing to make extensive code changes. This can be changed via the `locale` [[configuration]] field in `quartz.config.ts`.
|
||||
Internationalization allows users to translate text in the Quartz interface into various supported languages without needing to make extensive code changes. This can be changed via the `locale` [[configuration]] field in `quartz.config.yaml`.
|
||||
|
||||
The locale field generally follows a certain format: `{language}-{REGION}`
|
||||
|
||||
@@ -10,7 +10,7 @@ The locale field generally follows a certain format: `{language}-{REGION}`
|
||||
- `{REGION}` is usually a [2-letter uppercase region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
|
||||
|
||||
> [!tip] Interested in contributing?
|
||||
> We [gladly welcome translation PRs](https://github.com/jackyzha0/quartz/tree/v4/quartz/i18n/locales)! To contribute a translation, do the following things:
|
||||
> We [gladly welcome translation PRs](https://github.com/jackyzha0/quartz/tree/v5/quartz/i18n/locales)! To contribute a translation, do the following things:
|
||||
>
|
||||
> 1. In the `quartz/i18n/locales` folder, copy the `en-US.ts` file.
|
||||
> 2. Rename it to `{language}-{REGION}.ts` so it matches a locale of the format shown above.
|
||||
|
||||
@@ -1,3 +1,48 @@
|
||||
---
|
||||
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
|
||||
- [[Canvas]] — Render Obsidian Canvas files as interactive pages
|
||||
- [[Bases]] — Database-like views for your notes (tables, cards, galleries, and more)
|
||||
|
||||
## 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
|
||||
- [[StackedPages|stacked pages]] — Andy Matuschak-style stacked sliding panes for tracing note connections
|
||||
- [[EncryptedPages|encrypted pages]] — Password-protect individual pages with client-side encryption
|
||||
|
||||
## 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
|
||||
|
||||
@@ -12,6 +12,6 @@ Similar to Obsidian, [[quartz-layout-desktop.png|images referenced using wikilin
|
||||
|
||||
## Configuration
|
||||
|
||||
- Remove popovers: set the `enablePopovers` field in `quartz.config.ts` to be `false`.
|
||||
- Remove popovers: set the `enablePopovers` field in `quartz.config.yaml` to be `false`.
|
||||
- Style: `quartz/components/styles/popover.scss`
|
||||
- Script: `quartz/components/scripts/popover.inline.ts`
|
||||
|
||||
@@ -17,7 +17,7 @@ If you'd like to only publish a select number of notes, you can instead use [[Ex
|
||||
|
||||
## `ignorePatterns`
|
||||
|
||||
This is a field in `quartz.config.ts` under the main [[configuration]] which allows you to specify a list of patterns to effectively exclude from parsing all together. Any valid [fast-glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) pattern works here.
|
||||
This is a field in `quartz.config.yaml` under the main [[configuration]] which allows you to specify a list of patterns to effectively exclude from parsing all together. Any valid [fast-glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) pattern works here.
|
||||
|
||||
> [!note]
|
||||
> Bash's glob syntax is slightly different from fast-glob's and using bash's syntax may lead to unexpected results.
|
||||
|
||||
@@ -6,15 +6,28 @@ tags:
|
||||
|
||||
Reader Mode is a feature that allows users to focus on the content by hiding the sidebars and other UI elements. When enabled, it provides a clean, distraction-free reading experience.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
## Configuration
|
||||
|
||||
Reader Mode is enabled by default. To disable it, you can remove the component from your layout configuration in `quartz.layout.ts`:
|
||||
Reader Mode is enabled by default. To disable it, set `enabled: false` in your `quartz.config.yaml`:
|
||||
|
||||
```ts
|
||||
// Remove or comment out this line
|
||||
Component.ReaderMode(),
|
||||
```yaml title="quartz.config.yaml"
|
||||
plugins:
|
||||
- source: github:quartz-community/reader-mode
|
||||
enabled: false
|
||||
```
|
||||
|
||||
Or remove the plugin entirely:
|
||||
|
||||
```bash
|
||||
npx quartz plugin remove github:quartz-community/reader-mode
|
||||
```
|
||||
|
||||
- Install: `npx quartz plugin add github:quartz-community/reader-mode`
|
||||
- Source: [`quartz-community/reader-mode`](https://github.com/quartz-community/reader-mode)
|
||||
|
||||
## Usage
|
||||
|
||||
The Reader Mode toggle appears as a button with a book icon. When clicked:
|
||||
|
||||
@@ -3,15 +3,20 @@ title: Recent Notes
|
||||
tags: component
|
||||
---
|
||||
|
||||
Quartz can generate a list of recent notes based on some filtering and sorting criteria. Though this component isn't included in any [[layout]] by default, you can add it by using `Component.RecentNotes` in `quartz.layout.ts`.
|
||||
Quartz can generate a list of recent notes based on some filtering and sorting criteria. Though this component isn't included in any [[layout]] by default, you can add it by installing the plugin and configuring it in `quartz.config.yaml`.
|
||||
|
||||
> [!note]
|
||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||
|
||||
## Customization
|
||||
|
||||
- Changing the title from "Recent notes": pass in an additional parameter to `Component.RecentNotes({ title: "Recent writing" })`
|
||||
- Changing the number of recent notes: pass in an additional parameter to `Component.RecentNotes({ limit: 5 })`
|
||||
- Display the note's tags (defaults to true): `Component.RecentNotes({ showTags: false })`
|
||||
- Show a 'see more' link: pass in an additional parameter to `Component.RecentNotes({ linkToMore: "tags/components" })`. This field should be a full slug to a page that exists.
|
||||
- Customize filtering: pass in an additional parameter to `Component.RecentNotes({ filter: someFilterFunction })`. The filter function should be a function that has the signature `(f: QuartzPluginData) => boolean`.
|
||||
- Customize sorting: pass in an additional parameter to `Component.RecentNotes({ sort: someSortFunction })`. By default, Quartz will sort by date and then tie break lexographically. The sort function should be a function that has the signature `(f1: QuartzPluginData, f2: QuartzPluginData) => number`. See `byDateAndAlphabetical` in `quartz/components/PageList.tsx` for an example.
|
||||
- Component: `quartz/components/RecentNotes.tsx`
|
||||
- Style: `quartz/components/styles/recentNotes.scss`
|
||||
Most options are configured in the `options` section of the plugin entry in `quartz.config.yaml`:
|
||||
|
||||
- Changing the title from "Recent notes": set `title: "Recent writing"` in options
|
||||
- Changing the number of recent notes: set `limit: 5` in options
|
||||
- Display the note's tags (defaults to true): set `showTags: false` in options
|
||||
- Show a 'see more' link: set `linkToMore: "tags/components"` in options. This field should be a full slug to a page that exists.
|
||||
- Customize filtering: requires a TS override — pass `filter: someFilterFunction` to the plugin constructor in `quartz.ts`. The filter function should have the signature `(f: QuartzPluginData) => boolean`.
|
||||
- Customize sorting: requires a TS override — pass `sort: someSortFunction` to the plugin constructor in `quartz.ts`. By default, Quartz will sort by date and then tie break lexographically. The sort function should have the signature `(f1: QuartzPluginData, f2: QuartzPluginData) => number`.
|
||||
- Install: `npx quartz plugin add github:quartz-community/recent-notes`
|
||||
- Source: [`quartz-community/recent-notes`](https://github.com/quartz-community/recent-notes)
|
||||
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
draft: true
|
||||
---
|
||||
|
||||
## misc backlog
|
||||
|
||||
- static dead link detection
|
||||
- cursor chat extension
|
||||
- sidenotes? https://github.com/capnfabs/paperesque
|
||||
- direct match in search using double quotes
|
||||
- https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI
|
||||
- Canvas
|
||||
Reference in New Issue
Block a user