docs + various polish

content/features/Latex.md

@@ -0,0 +1,44 @@
+---
+tags:
+- plugins/transformer
+---
+
+Quartz uses [Katex](https://katex.org/) by default to typeset both inline and block math expressions at build time.
+
+## Formatting
+
+### Block Math
+Block math can be rendered by delimiting math expression with `$$`.
+
+```
+$$
+f(x) = \int_{-\infty}^\infty
+    f\hat(\xi),e^{2 \pi i \xi x}
+    \,d\xi
+$$
+```
+
+$$
+f(x) = \int_{-\infty}^\infty
+    f\hat(\xi),e^{2 \pi i \xi x}
+    \,d\xi
+$$
+
+### 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$
+
+### Escaping symbols
+There will be cases where you may have more than one `$` in a paragraph at once which may accidentally trigger MathJax/Katex. 
+
+To get around this, you can escape the dollar sign by doing `\$` instead.
+
+For example:
+- Incorrect: `I have $1 and you have $2` produces I have $1 and you have $2
+- Correct: `I have \$1 and you have \$2` produces I have \$1 and you have \$2
+
+## MathJax
+In `quartz.config.ts`, you can configure Quartz to use [MathJax SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html) by replacing `Plugin.Latex({ renderEngine: 'katex' })` with `Plugin.Latex({ renderEngine: 'mathjax' })`
+
+## Customization
+- Removing Latex support: remove all instances of `Plugin.Latex()` from `quartz.config.ts`.
+- Plugin: `quartz/plugins/transformers/latex.ts`

content/features/Mermaid diagrams.md

@@ -0,0 +1,10 @@
+> [!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()`.
+
+```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!
+```

content/features/SPA Routing.md

@@ -0,0 +1 @@
+Single-page-app style rendering. This prevents flashes of unstyled content and improves smoothness of Quartz

content/features/backlinks.md

@@ -0,0 +1,13 @@
+---
+title: Backlinks
+tags:
+- component
+---
+
+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.
+
+## Customization
+- Removing backlinks: delete all usages of `Component.Backlinks()` from `quartz.config.ts`.
+- Component: `quartz/components/Backlinks.tsx`
+- Style: `quartz/components/styles/backlinks.scss`
+- Script: `quartz/components/scripts/search.inline.ts`

content/features/callouts.md

@@ -0,0 +1,62 @@
+---
+title: 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()`.
+
+
+> [!info]
+> Default title
+
+> [!question]+ Can callouts be nested?
+> > [!todo]- Yes!, they can.
+> > > [!example]  You can even use multiple layers of nesting.
+
+> [!EXAMPLE] Examples
+>
+> Aliases: example
+
+> [!note] Notes
+>
+> Aliases: note
+
+> [!abstract] Summaries 
+>
+> Aliases: abstract, summary, tldr
+
+> [!info] Info 
+>
+> Aliases: info, todo
+
+> [!tip] Hint 
+>
+> Aliases: tip, hint, important
+
+> [!success] Success 
+>
+> Aliases: success, check, done
+
+> [!question] Question 
+>
+> Aliases: question, help, faq
+
+> [!warning] Warning 
+>
+> Aliases: warning, caution, attention
+
+> [!failure] Failure 
+>
+> Aliases: failure, fail, missing
+
+> [!danger] Error
+>
+> Aliases: danger, error
+
+> [!bug] Bug
+>
+> Aliases: bug
+
+> [!quote] Quote
+>
+> Aliases: quote, cite

content/features/full-text search.md

@@ -0,0 +1,26 @@
+---
+title: Full-text Search
+tags: 
+- component
+---
+
+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.
+
+It can be opened by either clicking on the search bar or pressing ⌘+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. 
+
+This component is also keyboard accessible: Tab and Shift+Tab will cycle forward and backward through search results and Enter will navigate to the highlighted result (first result by default).
+
+> [!info]
+> Search requires the `ContentIndex` emitter plugin to be present in the [[configuration]].
+
+### Indexing Behaviour
+By default, it indexes every page on the site with **Markdown syntax removed**. This means link URLs for instance are not indexed.
+
+It properly tokenizes Chinese, Korean, and Japenese characters and constructs separate indexes for the title and content, weighing title matches above content matches.
+
+## Customization
+- Removing search: delete all usages of `Component.Search()` from `quartz.config.ts`.
+- Component: `quartz/components/Search.tsx`
+- Style: `quartz/components/styles/search.scss`
+- Script: `quartz/components/scripts/search.inline.ts`
+	- You can edit `contextWindowWords` or `numSearchResults` to suit your needs

content/features/graph view.md

@@ -0,0 +1,58 @@
+---
+title: "Graph View"
+tags:
+- component
+---
+
+Quartz features a graph-view that can show both a local graph view and a global graph view. 
+
+- 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.
+
+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.
+
+> [!info]
+> Graph View requires the `ContentIndex` emitter plugin to be present in the [[configuration]].
+
+## Customization
+Most configuration can be done by passing in options to `Component.Graph()`.
+
+For example, here's what the default configuration looks like:
+
+```typescript title="quartz.config.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?
+  },
+  globalGraph: {
+    drag: true,
+    zoom: true,
+    depth: -1,
+    scale: 0.9,
+    repelForce: 0.5,
+    centerForce: 0.3,
+    linkDistance: 30,
+    fontSize: 0.6,
+    opacityScale: 1
+  }
+})
+```
+
+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.config.ts`.
+- Component: `quartz/components/Graph.tsx`
+- Style: `quartz/components/styles/graph.scss`
+- Script: `quartz/components/scripts/graph.inline.ts`

content/features/index.md

@@ -0,0 +1,3 @@
+---
+title: Feature List
+---

content/features/popover previews.md

@@ -0,0 +1,14 @@
+---
+title: Popover Previews
+---
+
+Like Wikipedia, when you hover over a link in Quartz, there is a popup of a page preview that you can scroll to see the entire content.
+
+By default, Quartz only fetches previews for pages inside your vault due to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). It does this by selecting all HTML elements with the `popover-hint` class. For most pages, this includes the page title, page metadata like words and time to read, tags, and the actual page content.
+
+When [[creating components|creating your own components]], you can include this `popover-hint` class to also include it in the popover.
+
+## Configuration
+- Remove popovers: set the `enablePopovers` field in `quartz.config.ts` to be `false`.
+- Style: `quartz/components/styles/popover.scss`
+- Script: `quartz/components/scripts/popover.inline.ts`

content/features/syntax highlighting.md

@@ -0,0 +1,128 @@
+---
+title: Syntax Highlighting
+tags: 
+- plugins/transformer
+---
+
+Syntax highlighting in Quartz is completely done at build-time. This means that Quartz only ships pre-calculated CSS to highlight the right words so there is no heavy client-side bundle that does the syntax highlighting.
+
+And, unlike some client-side highlighters, it has a full TextMate parser grammar instead of using Regexes, allowing for highly accurate code highlighting.
+
+In short, it generates HTML that looks exactly like your code in an editor like VS Code. Under the hood, it's powered by [Rehype Pretty Code](https://rehype-pretty-code.netlify.app/) which uses [Shiki](https://github.com/shikijs/shiki).
+
+> [!warning]
+> Syntax highlighting does have an impact on build speed if you have a lot of code snippets in your notes.
+
+## Formatting
+Text inside `backticks` on a line will be formatted like code.
+
+````
+```ts
+export function trimPathSuffix(fp: string): string {
+  fp = clientSideSlug(fp)
+  let [cleanPath, anchor] = fp.split("#", 2)
+  anchor = anchor === undefined ? "" : "#" + anchor
+
+  return cleanPath + anchor
+}
+```
+````
+
+```ts
+export function trimPathSuffix(fp: string): string {
+  fp = clientSideSlug(fp)
+  let [cleanPath, anchor] = fp.split("#", 2)
+  anchor = anchor === undefined ? "" : "#" + anchor
+
+  return cleanPath + anchor
+}
+```
+
+### Titles
+Add a file title to your code block, with text inside double quotes (`""`):
+
+````
+```js title="..."
+ 
+```
+````
+
+```ts title="quartz/path.ts"
+export function trimPathSuffix(fp: string): string {
+  fp = clientSideSlug(fp)
+  let [cleanPath, anchor] = fp.split("#", 2)
+  anchor = anchor === undefined ? "" : "#" + anchor
+
+  return cleanPath + anchor
+}
+```
+
+### Line highlighting
+Place a numeric range inside `{}`.
+
+````
+```js {1-3,4}
+ 
+```
+````
+
+```ts {2-3,6}
+export function trimPathSuffix(fp: string): string {
+  fp = clientSideSlug(fp)
+  let [cleanPath, anchor] = fp.split("#", 2)
+  anchor = anchor === undefined ? "" : "#" + anchor
+
+  return cleanPath + anchor
+}
+```
+
+### Word highlighting
+A series of characters, like a literal regex.
+
+````
+```js /useState/
+const [age, setAge] = useState(50);
+const [name, setName] = useState('Taylor');
+```
+````
+
+```js /useState/
+const [age, setAge] = useState(50);
+const [name, setName] = useState('Taylor');
+```
+
+### Line numbers
+Syntax highlighting has line numbers configured automatically. If you want to start line numbers at a specific number, use `showLineNumbers{number}`:
+
+````
+```js showLineNumbers{number}
+ 
+```
+````
+
+```ts showLineNumbers{20}
+export function trimPathSuffix(fp: string): string {
+  fp = clientSideSlug(fp)
+  let [cleanPath, anchor] = fp.split("#", 2)
+  anchor = anchor === undefined ? "" : "#" + anchor
+
+  return cleanPath + anchor
+}
+```
+
+### Escaping code blocks
+You can format a codeblock inside of a codeblock by wrapping it with another level of backtick fences that has one more backtick than the previous fence.
+
+`````
+````
+```js /useState/
+const [age, setAge] = useState(50);
+const [name, setName] = useState('Taylor');
+```
+````
+`````
+
+## Customization
+- Removing syntax highlighting: delete all usages of `Plugin.SyntaxHighlighting()` from `quartz.config.ts`.
+- Style: By default, Quartz uses derivatives of the GitHub light and dark themes. You can customize the colours in the `quartz/styles/syntax.scss` file.
+- Plugin: `quartz/plugins/transformers/syntax.ts`

content/features/upcoming features.md

@@ -0,0 +1,31 @@
+
+- CLI    
+    - update
+    - push
+    - create → ask for link resolution strategy
+- cursor chat extension    
+- [https://giscus.app/](https://giscus.app/) extension
+- breadcrumbs component
+- filetree component
+- recent notes component
+- custom md blocks (e.g. for poetry)
+- sidenotes? [https://github.com/capnfabs/paperesque](https://github.com/capnfabs/paperesque)
+- show orphans in graph
+- parse tags in content
+- watch mode
+- direct match in search using double quotes
+- obsidian quirks to account for:
+    - attachments path
+    - [https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI](https://help.obsidian.md/Advanced+topics/Using+Obsidian+URI)
+    - angle bracket url escape [https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Escape+blank+spaces+in+links](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Escape+blank+spaces+in+links) 
+    - [https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Task+lists](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Task+lists) task list styling
+    - [https://help.obsidian.md/Editing+and+formatting/Tags#Nested+tags](https://help.obsidian.md/Editing+and+formatting/Tags#Nested+tags) nested tags??
+    - public metadata [https://help.obsidian.md/Editing+and+formatting/Metadata#Metadata+for+Obsidian+Publish](https://help.obsidian.md/Editing+and+formatting/Metadata#Metadata+for+Obsidian+Publish)
+    - metadata aliases: [https://help.obsidian.md/Editing+and+formatting/Metadata#Predefined+metadata](https://help.obsidian.md/Editing+and+formatting/Metadata#Predefined+metadata)
+    - \%\% style comments
+    - audio/video embed styling
+    - Canvas
+    - mermaid styling: [https://mermaid.js.org/config/theming.html#theme-variables-reference-table](https://mermaid.js.org/config/theming.html#theme-variables-reference-table)
+        - [https://github.com/jackyzha0/quartz/issues/331](https://github.com/jackyzha0/quartz/issues/331)
+    - block links: [https://help.obsidian.md/Linking+notes+and+files/Internal+links#Link+to+a+block+in+a+note](https://help.obsidian.md/Linking+notes+and+files/Internal+links#Link+to+a+block+in+a+note)
+    - note/header/block transcludes: [https://help.obsidian.md/Linking+notes+and+files/Embedding+files](https://help.obsidian.md/Linking+notes+and+files/Embedding+files)