From 259d0a6d9ac5a02f0281e3fc061861b23481348f Mon Sep 17 00:00:00 2001 From: Jacky Zhao Date: Fri, 11 Aug 2023 00:31:44 -0700 Subject: [PATCH] more documentation --- content/authoring content.md | 33 +++++++++++++++++++++ content/features/Latex.md | 13 ++++++++ content/features/Mermaid diagrams.md | 18 +++++++++++ content/features/Obsidian compatibility.md | 31 +++++++++++++++++++ content/features/callouts.md | 23 ++++++++++++++ content/features/folder and tag listings.md | 28 +++++++++++++++++ content/features/private pages.md | 25 ++++++++++++++++ content/features/upcoming features.md | 3 -- content/index.md | 4 +-- quartz/plugins/transformers/frontmatter.ts | 2 -- 10 files changed, 173 insertions(+), 7 deletions(-) create mode 100644 content/authoring content.md create mode 100644 content/features/Obsidian compatibility.md create mode 100644 content/features/private pages.md diff --git a/content/authoring content.md b/content/authoring content.md new file mode 100644 index 000000000..b5b154c0f --- /dev/null +++ b/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. diff --git a/content/features/Latex.md b/content/features/Latex.md index 0dbc1133e..91cc952ed 100644 --- a/content/features/Latex.md +++ b/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$ diff --git a/content/features/Mermaid diagrams.md b/content/features/Mermaid diagrams.md index 91d0988be..f14a5589b 100644 --- a/content/features/Mermaid diagrams.md +++ b/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? diff --git a/content/features/Obsidian compatibility.md b/content/features/Obsidian compatibility.md new file mode 100644 index 000000000..61fcc060d --- /dev/null +++ b/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` diff --git a/content/features/callouts.md b/content/features/callouts.md index cb5feb9d3..63051ad9d 100644 --- a/content/features/callouts.md +++ b/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 diff --git a/content/features/folder and tag listings.md b/content/features/folder and tag listings.md index e69de29bb..caad796b8 100644 --- a/content/features/folder and tag listings.md +++ b/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: ` 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` diff --git a/content/features/private pages.md b/content/features/private pages.md new file mode 100644 index 000000000..e225e8c33 --- /dev/null +++ b/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. diff --git a/content/features/upcoming features.md b/content/features/upcoming features.md index 27d8bd949..ebfd62574 100644 --- a/content/features/upcoming features.md +++ b/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 diff --git a/content/index.md b/content/index.md index 32425852b..32f012c2e 100644 --- a/content/index.md +++ b/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 diff --git a/quartz/plugins/transformers/frontmatter.ts b/quartz/plugins/transformers/frontmatter.ts index 58ae7c79d..e09d20f76 100644 --- a/quartz/plugins/transformers/frontmatter.ts +++ b/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: "---", }