docs + various polish

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`