more documentation

content/authoring content.md

@@ -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.

content/features/Latex.md

@@ -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$

content/features/Mermaid diagrams.md

@@ -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?

content/features/Obsidian compatibility.md

@@ -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`

content/features/callouts.md

@@ -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
 

content/features/folder and tag listings.md

@@ -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`

content/features/private pages.md

@@ -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.

content/features/upcoming features.md

@@ -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

content/index.md

@@ -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

quartz/plugins/transformers/frontmatter.ts

@@ -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: "---",
 }