more documentation
This commit is contained in:
parent
b3635a0c5a
commit
41f7de75a9
33
content/authoring content.md
Normal file
33
content/authoring content.md
Normal file
@ -0,0 +1,33 @@
|
||||
---
|
||||
title: 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 initailized. 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 all of your local files and allow you to easily edit and link across files.
|
||||
|
||||
Got everything setup? Let's [[build]] and preview your Quartz locally!
|
||||
|
||||
## Syntax
|
||||
|
||||
As Quartz uses Markdown files as the main way of writing content, it fully supports Markdown syntax along with a few extensions like [Github Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (footnotes, strikethrough, tables, tasklists) and [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown) ([[callouts]], [[wikilinks]]).
|
||||
|
||||
Additionally, Quartz also allows you to specify additional metadata in your notes called **frontmatter** using YAML.
|
||||
|
||||
```md title="content/note.md"
|
||||
---
|
||||
title: Example Title
|
||||
draft: false
|
||||
tags:
|
||||
- example-tag
|
||||
---
|
||||
|
||||
The rest of your content lives here. You can use **Markdown** here :)
|
||||
```
|
||||
|
||||
Some common frontmatter fields that are natively supported by Quartz:
|
||||
|
||||
- `title`: Quartz will use the name of the file as the title if this isn't provided. If it is provided, it should be a string.
|
||||
- `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz.
|
||||
- `aliases`: Other names for this note. This is a list of strings.
|
||||
- `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format but other formats _may_ work.
|
@ -25,6 +25,19 @@ f(x) = \int_{-\infty}^\infty
|
||||
\,d\xi
|
||||
$$
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
a &= b + c \\ &= e + f \\
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
$$
|
||||
\begin{bmatrix}
|
||||
1 & 2 & 3 \\
|
||||
a & b & c
|
||||
\end{bmatrix}
|
||||
$$
|
||||
|
||||
### Inline Math
|
||||
|
||||
Similarly, inline math can be rendered by delimiting math expression with a single `$`. For example, `$e^{i\pi} = -1$` produces $e^{i\pi} = -1$
|
||||
|
@ -1,6 +1,24 @@
|
||||
Quartz supports Mermaid which allows you to add diagrams and charts to your notes. Mermaid supports a range of diagrams, such as [flow charts](https://mermaid.js.org/syntax/flowchart.html), [sequence diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html), and [timelines](https://mermaid.js.org/syntax/timeline.html). This is enabled as a part of [[Obsidian compatibility]] and can be configured and enabled/disabled from that plugin.
|
||||
|
||||
By default, Quartz will render Mermaid diagrams to match the site theme.
|
||||
|
||||
> [!warning]
|
||||
> Wondering why Mermaid diagrams may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is _after_ `Plugin.SyntaxHighlighting()`.
|
||||
|
||||
## Syntax
|
||||
|
||||
To add a Mermaid diagram, create a mermaid code block.
|
||||
|
||||
````
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Alice->>+John: Hello John, how are you?
|
||||
Alice->>+John: John, can you hear me?
|
||||
John-->>-Alice: Hi Alice, I can hear you!
|
||||
John-->>-Alice: I feel great!
|
||||
```
|
||||
````
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Alice->>+John: Hello John, how are you?
|
||||
|
31
content/features/Obsidian compatibility.md
Normal file
31
content/features/Obsidian compatibility.md
Normal file
@ -0,0 +1,31 @@
|
||||
---
|
||||
tags:
|
||||
- plugin/transformer
|
||||
---
|
||||
|
||||
Quartz was originally designed as a tool to publish Obsidian vaults as websites. Even as the scope of Quartz has widened over time, it hasn't lost the ability to seamlessly interoperate with Obsidian.
|
||||
|
||||
By default, Quartz ships with `Plugin.ObsidianFlavoredMarkdown` which is a transformer plugin that adds support for [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown). This includes support for features like [[wikilinks]] and [[Mermaid diagrams]].
|
||||
|
||||
It also ships with support for [frontmatter parsing](https://help.obsidian.md/Editing+and+formatting/Properties) with the same fields that Obsidian uses through the `Plugin.FrontMatter` transformer plugin.
|
||||
|
||||
Finally, Quartz also provides `Plugin.CrawlLinks` which allows you to customize Quartz's link resolution behaviour to match Obsidian.
|
||||
|
||||
## Configuration
|
||||
|
||||
- Frontmatter parsing:
|
||||
- Disabling: remove all instances of `Plugin.FrontMatter()` from `quartz.config.ts`.
|
||||
- Customize default values for frontmatter: edit `quartz/plugins/transformers/frontmatter.ts`
|
||||
- Obsidian Flavored Markdown:
|
||||
- Disabling: remove all instances of `Plugin.ObsidianFlavoredMarkdown()` from `quartz.config.ts`
|
||||
- Customizing features: `Plugin.ObsidianFlavoredMarkdown` has several other options to toggle on and off:
|
||||
- `comments`: whether to enable `%%` style Obsidian comments. Defaults to `true`
|
||||
- `highlight`: whether to enable `==` style highlights. Defaults to `true`
|
||||
- `wikilinks`: whether to enable turning [[wikilinks]] into regular links. Defaults to `true`
|
||||
- `callouts`: whether to enable [[callouts]]. Defaults to `true`
|
||||
- `mermaid`: whether to enable [[Mermaid diagrams]]. Defaults to `true`
|
||||
- `parseTags`: whether to try and parse tags in the content body. Defaults to `true`
|
||||
- `enableInHtmlEmbed`: whether to try and parse Obsidian flavoured markdown in raw HTML. Defaults to `false`
|
||||
- Link resolution behaviour:
|
||||
- Disabling: remove all instances of `Plugin.CrawlLinks()` from `quartz.config.ts`
|
||||
- Changing link resolution preference: set `markdownLinkResolution` to one of `absolute`, `relative` or `shortest`
|
@ -1,10 +1,33 @@
|
||||
---
|
||||
title: Callouts
|
||||
tags:
|
||||
- plugin/transformer
|
||||
---
|
||||
|
||||
Quartz supports the same Admonition-callout syntax as Obsidian.
|
||||
|
||||
This includes
|
||||
|
||||
- 12 Distinct callout types (each with several aliases)
|
||||
- Collapsable callouts
|
||||
|
||||
```
|
||||
> [!info] Title
|
||||
> This is a callout!
|
||||
```
|
||||
|
||||
See [documentation on supported types and syntax here](https://help.obsidian.md/Editing+and+formatting/Callouts).
|
||||
|
||||
> [!warning]
|
||||
> Wondering why callouts may not be showing up even if you have them enabled? You may need to reorder your plugins so that `Plugin.ObsidianFlavoredMarkdown()` is _after_ `Plugin.SyntaxHighlighting()`.
|
||||
|
||||
## Customization
|
||||
|
||||
- Disable callouts: simply pass `callouts: false` to the plugin: `Plugin.ObsidianFlavoredMarkdown({ callouts: false })`
|
||||
- Editing icons: `quartz/plugins/transformers/ofm.ts`
|
||||
|
||||
## Showcase
|
||||
|
||||
> [!info]
|
||||
> Default title
|
||||
|
||||
|
@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Folder and Tag Listings
|
||||
tags:
|
||||
- plugin/emitter
|
||||
---
|
||||
|
||||
Quartz creates listing pages for any folders and tags you have.
|
||||
|
||||
## Folder Listings
|
||||
|
||||
Quartz will generate an index page for all the pages under that folder. This includes any content that is multiple levels deep.
|
||||
|
||||
Additionally, Quartz will also generate pages for subfolders. Say you have a note in a nested folder `content/abc/def/note.md`. Then, Quartz would generate a page for all the notes under `abc` _and_ a page for all the notes under `abc/def`.
|
||||
|
||||
By default, Quartz will title the page `Folder: <name of folder>` and no description. You can override this by creating an `index.md` file in the folder with the `title` [[authoring content#Syntax|frontmatter]] field. Any content you write in this file will also be used in the description of the folder.
|
||||
|
||||
## Tag Listings
|
||||
|
||||
Quartz will also create an index page for each unique tag in your vault and render a list of all notes with that tag.
|
||||
|
||||
Quartz also supports tag hierarchies as well (e.g. `plugin/emitter`) and will also render a separate tag page for each layer of the tag hierarchy. It will also create a default global tag index page at `/tags` that displays a list of all the tags in your Quartz.
|
||||
|
||||
## Customization
|
||||
|
||||
The layout for both the folder and content pages can be customized. By default, they use the `defaultListPageLayout` in `quartz.layouts.ts`. If you'd like to make more involved changes to the layout and don't mind editing some [[creating components|Quartz components]], you can take a look at `quartz/components/pages/FolderContent.tsx` and `quartz/components/pages/TagContent.tsx` respectively.
|
||||
|
||||
- Removing folder listings: remove `Plugin.FolderPage()` from `emitters` in `quartz.config.ts`
|
||||
- Removing tag listings: remove `Plugin.TagPage()` from `emitters` in `quartz.config.ts`
|
25
content/features/private pages.md
Normal file
25
content/features/private pages.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Private Pages
|
||||
---
|
||||
|
||||
There may be some notes you want to avoid publishing as a website. Quartz supports this through two mechanisms which can be used in conjunction:
|
||||
|
||||
## Filter Plugins
|
||||
|
||||
[[making plugins#Filters|Filter plugins]] are plugins that filter out content based off of certain criteria. By default, Quartz uses the `Plugin.RemoveDrafts` plugin which filters out any note that has `drafts: true` in the frontmatter.
|
||||
|
||||
If you'd like to only publish a select number of notes, you can instead use `Plugin.ExplicitPublish` which will filter out all notes except for any that have `publish: true` in the frontmatter.
|
||||
|
||||
## `ignoreFiles`
|
||||
|
||||
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 [glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) pattern works here.
|
||||
|
||||
Common examples include:
|
||||
|
||||
- `some/folder`: exclude the entire of `some/folder`
|
||||
- `*.md`: exclude all files with a `.md` extension
|
||||
- `!*.md` exclude all files that _don't_ have a `.md` extension
|
||||
- `**/private`: exclude any files or folders named `private` at any level of nesting
|
||||
|
||||
> [!warning]
|
||||
> Marking something as private via either a plugin or through the `ignoreFiles` pattern will only prevent a page from being included in the final built site. If your GitHub repository is public, also be sure to include an ignore for those in the `.gitignore` of your Quartz. See the `git` [documentation](https://git-scm.com/docs/gitignore#_pattern_format) for more information.
|
@ -14,9 +14,6 @@ draft: true
|
||||
- test/fix with subpath
|
||||
- fix docs with deploy from github
|
||||
- write feature docs
|
||||
- callouts
|
||||
- folder and tag listings
|
||||
- mermaid diagrams
|
||||
- rss
|
||||
- spa-routing
|
||||
- table of contents
|
||||
|
@ -18,14 +18,14 @@ npm i
|
||||
npx quartz create
|
||||
```
|
||||
|
||||
This will guide you through initializing your Quartz with content. Once you've done so, see how to [[build]] and [[hosting|host]] Quartz.
|
||||
This will guide you through initializing your Quartz with content. Once you've done so, see how to [[authoring content|author content]] or how to [[build]] and [[hosting|host]] Quartz.
|
||||
|
||||
> [!info]
|
||||
> Coming from Quartz 3? See the [[migrating from Quartz 3|migration guide]] for the differences between Quartz 3 and Quartz 4 and how to migrate.
|
||||
|
||||
## 🔧 Features
|
||||
|
||||
- [[full-text search|Full-text search]], [[graph view]], [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], and many more right out of the box
|
||||
- [[Obsidian compatibility]], [[full-text search]], [[graph view]], [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], and many more right out of the box
|
||||
- Hot-reload for both configuration and content
|
||||
- Simple JSX [[creating components|layouts and page components]]
|
||||
- [[SPA Routing|Ridiculously fast page loads]] and tiny bundle sizes
|
||||
|
@ -5,12 +5,10 @@ import yaml from "js-yaml"
|
||||
import { slugTag } from "../../path"
|
||||
|
||||
export interface Options {
|
||||
language: "yaml" | "toml"
|
||||
delims: string | string[]
|
||||
}
|
||||
|
||||
const defaultOptions: Options = {
|
||||
language: "yaml",
|
||||
delims: "---",
|
||||
}
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user