Merge branch 'shiki-themes' into 'main'

document theming the code syntax highlighting - fixes #12

Closes #12

See merge request !26

content/en/docs/customisation/themes.md

@@ -150,6 +150,44 @@ The difference between `$foo` and `foo` is that the latter will be set
 as a CSS variable, so a user's custom CSS could refer to it, while the
 former won't escape the theme.
 
+#### Code syntax highlighting
+
+MFM code blocks like these:
+
+  <!-- markdownlint-disable-next-line MD048 -->
+  ```ts
+  const foo=1;
+  ```
+
+are rendered with syntax highlighting provided by the
+[Shiki](https://shiki.style/) package. You can provide your own styles
+by setting the `codeHighlighter` top-level key in your theme:
+
+```json
+codeHighlighter: { "base": "catppuccin-mocha" }
+```
+
+The value inside `base` must be the name of one of the [themes bundled
+with Shiki](https://shiki.style/themes).
+
+Alternatively, you could provide a whole TextMate theme definition
+(the Shiki repository [has plenty of
+examples](https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-themes/themes/)):
+
+```json
+codeHighlighter: {
+  "base": "_none_",
+  "overrides": {
+    // put the whole TextMate theme definition here
+  }
+}
+```
+
+(Technically, you could have *both* a non-`_none_` `base` and an
+`overrides` object, but because the value of the `tokenColors` bit of
+the TextMate theme is an array, merging the two doesn't quite work as
+you'd expect)
+
 ## Example
 
 This is one of the built-in Misskey themes:
@@ -197,3 +235,18 @@ This is a minimal theme that just sets a font:
   }
 }
 ```
+
+This is a minimal theme that just sets a code highlighter theme
+(notice that you *must* provide a `props` value, even if it's empty):
+
+```json
+{
+  id: "c690ae5f-3523-4a02-9206-2cf0c433f2d5",
+  name: "Mocha code",
+  author: "dakkar",
+  desc: "Highlight with catppuccin-mocha",
+  base: "light",
+  props: {},
+  codeHighlighter: { base: "catppuccin-mocha" }
+}
+```