mirror of
https://github.com/jackyzha0/quartz.git
synced 2026-03-21 21:45:42 -05:00
docs: rewrite Frontmatter documentation for note-properties plugin
This commit is contained in:
saberzero1
parent
7100a33807
commit
81f16534ef
@ -1,72 +1,107 @@
|
|||||||
---
|
---
|
||||||
title: "Frontmatter"
|
title: "Frontmatter"
|
||||||
|
aliases:
|
||||||
|
- note-properties
|
||||||
|
- Note Properties
|
||||||
|
description: "Parses frontmatter and displays note properties in a collapsible panel."
|
||||||
tags:
|
tags:
|
||||||
- plugin/transformer
|
- plugin/transformer
|
||||||
|
- plugin/component
|
||||||
|
publish: true
|
||||||
|
enableToc: true
|
||||||
---
|
---
|
||||||
|
|
||||||
This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library. See [[authoring content#Syntax]], [[Obsidian compatibility]] and [[OxHugo compatibility]] for more information.
|
This plugin parses the frontmatter of the page using the [gray-matter](https://github.com/jonschlinkert/gray-matter) library and optionally displays selected properties in a collapsible panel. See [[authoring content#Syntax]], [[Obsidian compatibility]] and [[OxHugo compatibility]] for more information.
|
||||||
|
|
||||||
> [!note]
|
> [!note]
|
||||||
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
|
||||||
|
|
||||||
|
> [!warning]
|
||||||
|
> This plugin must not be removed, otherwise Quartz will break.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
This plugin accepts the following configuration options:
|
This plugin accepts the following configuration options:
|
||||||
|
|
||||||
- `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`.
|
- `delimiters`: the delimiters to use for the frontmatter. Can have one value (e.g. `"---"`) or separate values for opening and closing delimiters (e.g. `["---", "~~~"]`). Defaults to `"---"`.
|
||||||
- `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`.
|
- `language`: the language to use for parsing the frontmatter. Can be `yaml` (default) or `toml`.
|
||||||
|
- `includeAll`: include all frontmatter properties in the properties panel. When `false`, only `includedProperties` are shown. Defaults to `false`.
|
||||||
|
- `includedProperties`: properties to include when `includeAll` is `false`. Defaults to `["description", "tags", "aliases"]`.
|
||||||
|
- `excludedProperties`: properties to always exclude from display, even when `includeAll` is `true`. Defaults to `[]`.
|
||||||
|
- `hidePropertiesView`: hide the visual properties panel while still processing frontmatter. Useful if you only need frontmatter parsing without the UI. Defaults to `false`.
|
||||||
|
|
||||||
> [!warning]
|
### Default options
|
||||||
> This plugin must not be removed, otherwise Quartz will break.
|
|
||||||
|
|
||||||
## List
|
```yaml title="quartz.config.yaml"
|
||||||
|
- source: github:quartz-community/note-properties
|
||||||
|
enabled: true
|
||||||
|
options:
|
||||||
|
includeAll: false
|
||||||
|
includedProperties:
|
||||||
|
- description
|
||||||
|
- tags
|
||||||
|
- aliases
|
||||||
|
excludedProperties: []
|
||||||
|
hidePropertiesView: false
|
||||||
|
delimiters: "---"
|
||||||
|
language: yaml
|
||||||
|
```
|
||||||
|
|
||||||
Quartz supports the following frontmatter:
|
## Properties panel
|
||||||
|
|
||||||
- title
|
When enabled, this plugin renders a collapsible "Properties" panel before the page body. The panel displays selected frontmatter fields in a table with automatic type rendering:
|
||||||
- `title`
|
|
||||||
- description
|
- **Strings** are shown as plain text. [[Wikilinks]] and [markdown links](https://example.com) within strings are rendered as clickable links.
|
||||||
- `description`
|
- **Arrays** are rendered as comma-separated lists.
|
||||||
- permalink
|
- **Booleans** are rendered as disabled checkboxes.
|
||||||
- `permalink`
|
- **Numbers** are rendered in a monospace font.
|
||||||
- comments
|
- **Objects** are rendered as JSON in a code block.
|
||||||
- `comments`
|
- **Tags** get special treatment: they are rendered as highlighted links that point to the corresponding tag page.
|
||||||
- lang
|
- **Null/undefined** values are shown as an em-dash (—).
|
||||||
- `lang`
|
|
||||||
- publish
|
### Per-note overrides
|
||||||
- `publish`
|
|
||||||
- draft
|
You can control the properties panel on a per-note basis using frontmatter keys:
|
||||||
- `draft`
|
|
||||||
- enableToc
|
- `quartz-properties` (or `quartzProperties`): set to `true` to force-show the panel, or `false` to force-hide it, overriding the global `hidePropertiesView` setting.
|
||||||
- `enableToc`
|
- `quartz-properties-collapse` (or `quartzPropertiesCollapse`): set to `true` to start the panel collapsed, or `false` to start it expanded, overriding the default collapse state.
|
||||||
- tags
|
|
||||||
- `tags`
|
These keys are automatically excluded from the visible properties table.
|
||||||
- `tag`
|
|
||||||
- aliases
|
```yaml title="Example frontmatter"
|
||||||
- `aliases`
|
---
|
||||||
- `alias`
|
title: My Note
|
||||||
- cssclasses
|
quartz-properties: true
|
||||||
- `cssclasses`
|
quartz-properties-collapse: false
|
||||||
- `cssclass`
|
---
|
||||||
- socialDescription
|
```
|
||||||
- `socialDescription`
|
|
||||||
- socialImage
|
## Supported frontmatter
|
||||||
- `socialImage`
|
|
||||||
- `image`
|
Quartz supports the following frontmatter fields. Where multiple keys are listed, they are aliases — the first matching key is used.
|
||||||
- `cover`
|
|
||||||
- created
|
| Field | Keys | Description |
|
||||||
- `created`
|
| ------------------ | ------------------------------------------------- | ------------------------------------------------------------------ |
|
||||||
- `date`
|
| Title | `title` | Page title. Falls back to filename if empty. |
|
||||||
- modified
|
| Description | `description` | Page description for metadata and search. |
|
||||||
- `modified`
|
| Tags | `tags`, `tag` | Categorization tags. Automatically slugified. |
|
||||||
- `lastmod`
|
| Aliases | `aliases`, `alias` | Alternative names for the page, used for link resolution. |
|
||||||
- `updated`
|
| Permalink | `permalink` | Custom URL slug. Also added to aliases. |
|
||||||
- `last-modified`
|
| CSS classes | `cssclasses`, `cssclass` | CSS classes applied to the page body. |
|
||||||
- published
|
| Social image | `socialImage`, `image`, `cover` | Image used for social media previews. |
|
||||||
- `published`
|
| Social description | `socialDescription` | Description used specifically for social media previews. |
|
||||||
- `publishDate`
|
| Created date | `created`, `date` | When the note was created. |
|
||||||
- `date`
|
| Modified date | `modified`, `lastmod`, `updated`, `last-modified` | When the note was last modified. Falls back to `created` if unset. |
|
||||||
|
| Published date | `published`, `publishDate`, `date` | When the note was published. |
|
||||||
|
| Publish | `publish` | Whether the note should be published. |
|
||||||
|
| Draft | `draft` | Whether the note is a draft. |
|
||||||
|
| Comments | `comments` | Whether comments are enabled for the note. |
|
||||||
|
| Language | `lang` | Language code for the note. |
|
||||||
|
| Enable TOC | `enableToc` | Whether to show the table of contents. |
|
||||||
|
|
||||||
## API
|
## API
|
||||||
|
|
||||||
- Category: Transformer
|
- Category: Transformer, Component
|
||||||
- Function name: `Plugin.Frontmatter()`.
|
- Function name: `ExternalPlugin.NoteProperties()`.
|
||||||
- Source: [`quartz/plugins/transformers/frontmatter.ts`](https://github.com/jackyzha0/quartz/blob/v5/quartz/plugins/transformers/frontmatter.ts).
|
- Source: [`quartz-community/note-properties`](https://github.com/quartz-community/note-properties)
|
||||||
|
- Install: `npx quartz plugin add github:quartz-community/note-properties`
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user