Initial commit

docs/features/syntax highlighting.md

@@ -0,0 +1,143 @@
+---
+title: Syntax Highlighting
+tags:
+  - feature/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")
+```
+
+### Inline Highlighting
+
+Append {:lang} to the end of inline code to highlight it like a regular code block.
+
+```
+This is an array `[1, 2, 3]{:js}` of numbers 1 through 3.
+```
+
+This is an array `[1, 2, 3]{:js}` of numbers 1 through 3.
+
+### 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
+
+Syntax highlighting is a functionality of the [[SyntaxHighlighting]] plugin. See the plugin page for customization options.