roadmap/docs/features/syntax highlighting.md

136 lines
3.3 KiB
Markdown
Raw Normal View History

2023-07-10 02:32:24 +00:00
---
title: Syntax Highlighting
2023-07-26 04:10:37 +00:00
tags:
- plugin/transformer
2023-07-10 02:32:24 +00:00
---
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
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
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
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
Add a file title to your code block, with text inside double quotes (`""`):
````
```js title="..."
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
```
````
```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
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
Place a numeric range inside `{}`.
````
```js {1-3,4}
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
```
````
```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
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
A series of characters, like a literal regex.
````
```js /useState/
const [age, setAge] = useState(50);
const [name, setName] = useState('Taylor');
```
````
```js /useState/
2023-07-23 00:27:41 +00:00
const [age, setAge] = useState(50)
const [name, setName] = useState("Taylor")
2023-07-10 02:32:24 +00:00
```
### Line numbers
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
Syntax highlighting has line numbers configured automatically. If you want to start line numbers at a specific number, use `showLineNumbers{number}`:
````
```js showLineNumbers{number}
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
```
````
```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
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
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
2023-07-23 00:27:41 +00:00
2023-07-10 02:32:24 +00:00
- 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.
2023-07-23 00:27:41 +00:00
- Plugin: `quartz/plugins/transformers/syntax.ts`