docs: loading themes and grammar, close #27

docs/languages.md

@@ -1,4 +1,6 @@
-# All Languages
+# Languages
+
+## All Languages
 
 Inherited from [`shiki`](https://github.com/shikijs/shiki/blob/main/docs/languages.md#supporting-your-own-languages-with-shiki), here are all the languages bundled in `shikiji`.
 
@@ -177,3 +179,86 @@ Inherited from [`shiki`](https://github.com/shikijs/shiki/blob/main/docs/languag
 | `zenscript` | ZenScript |  |
 | `zig` | zig |  |
 <!--all-languages:end-->
+
+## Load Custom Languages
+
+You can load custom languages by passing a TextMate grammar object into the langs array.
+
+```ts
+import { getHighlighter } from 'shikiji'
+
+const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8'))
+
+const highlighter = await getHighlighter({
+  langs: [myLang]
+})
+
+const html = highlighter.codeToHtml(code, {
+  lang: 'my-lang',
+})
+```
+
+You can also load languages after the highlighter has been created.
+
+```ts
+import { getHighlighter } from 'shikiji'
+
+const myLang = JSON.parse(fs.readFileSync('my-lang.json', 'utf8'))
+
+const highlighter = await getHighlighter()
+
+await highlighter.loadLanguage(myLang) // <--
+
+const html = highlighter.codeToHtml(code, {
+  lang: 'my-lang',
+})
+```
+
+### Migrate from Shiki
+
+Since `shikiji` is environment agnostic, that means we don't have access to the file system. That means the `path` property `shiki` supports is not available in `shikiji`. Instead, you need to read them in yourself and pass the object. For example:
+
+```ts
+const highlighter = await getHighlighter({
+  langs: [
+    {
+      id: 'vue-vine',
+      scopeName: 'source.vue-vine',
+      // ‼️ This would not work!
+      path: join(__dirname, './vine-ts.tmLanguage.json'),
+      embeddedLangs: [
+        'vue-html',
+        'css',
+        'scss',
+        'sass',
+        'less',
+        'stylus',
+      ],
+    },
+  ]
+})
+```
+
+Instead, load that file yourself (via `fs`, `import()`, `fetch()`, etc.) and pass the object:
+
+```ts
+const vineGrammar = JSON.parse(fs.readFileSync(join(__dirname, './vine-ts.tmLanguage.json'), 'utf8'))
+
+const highlighter = await getHighlighter({
+  langs: [
+    {
+      id: 'vue-vine',
+      scopeName: 'source.vue-vine',
+      embeddedLangs: [
+        'vue-html',
+        'css',
+        'scss',
+        'sass',
+        'less',
+        'stylus',
+      ],
+      ...vineGrammar
+    },
+  ]
+})
+```

docs/themes.md

@@ -1,4 +1,6 @@
-# All Themes
+# Themes
+
+## All Themes
 
 Inherited from [`shiki`](https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes), here are all the themes bundled in `shikiji`.
 
@@ -35,3 +37,41 @@ Inherited from [`shiki`](https://github.com/shikijs/shiki/blob/main/docs/themes.
 | `vitesse-dark` |
 | `vitesse-light` |
 <!--all-themes:end-->
+
+## Load Custom Themes
+
+You can load custom themes by passing a `Theme` object into the themes array.
+
+```ts
+import { getHighlighter } from 'shikiji'
+
+const myTheme = JSON.parse(fs.readFileSync('my-theme.json', 'utf8'))
+
+const highlighter = await getHighlighter({
+  themes: [myTheme]
+})
+
+const html = highlighter.codeToHtml(code, {
+  lang: 'javascript',
+  theme: 'my-theme'
+})
+```
+
+You can also load themes after the highlighter has been created.
+
+```ts
+import { getHighlighter } from 'shikiji'
+
+const myTheme = JSON.parse(fs.readFileSync('my-theme.json', 'utf8'))
+
+const highlighter = await getHighlighter()
+
+await highlighter.loadTheme(myTheme) // <--
+
+const html = highlighter.codeToHtml(code, {
+  lang: 'javascript',
+  theme: 'my-theme'
+})
+```
+
+The theme should be a TextMate theme in JSON object. For example, [it should looks like this](https://github.com/antfu/vscode-theme-vitesse/blob/main/themes/vitesse-dark.json).