From cdac1faebd9dbe9a7e31c9fc768b8bc3986d1848 Mon Sep 17 00:00:00 2001
From: Anthony Fu <anthonyfu117@hotmail.com>
Date: Thu, 25 Jan 2024 20:02:02 +0100
Subject: [PATCH] docs: update

---
 docs/languages.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 docs/themes.md    | 16 ++++++++++++++++
 2 files changed, 60 insertions(+)

diff --git a/docs/languages.md b/docs/languages.md
index 062c99fc..71bf3e46 100644
--- a/docs/languages.md
+++ b/docs/languages.md
@@ -1,5 +1,7 @@
 # Languages
 
+## Bundled Languages
+
 Language grammars listed below are re-distributed via [`tm-grammars`](https://github.com/antfu/textmate-grammars-themes/tree/main/packages/tm-grammars) into the `shikiji` package.
 
 <LanguagesList />
@@ -7,3 +9,45 @@ Language grammars listed below are re-distributed via [`tm-grammars`](https://gi
 Grammars are covered by their repositories’ respective licenses, which are permissive (apache-2.0, mit, etc), and made available in [this NOTICE](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-grammars/NOTICE).
 
 For loading your custom languages, please reference to [this guide](/guide/load-lang).
+
+## Special Languages
+
+### Plain Text
+
+You can set lang to `text` to bypass highlighting. This is useful as the fallback when you receive user specified language that are not available. For example:
+
+```txt
+import { codeToHtml } from 'shikiji'
+
+const html = codeToHtml('console.log("Hello World")', {
+  lang: 'text', // [!code hl]
+  theme: 'vitesse-light', 
+})
+```
+
+`txt`, `plain` are provided as aliases to `text` as well.
+
+### ANSI
+
+A special processed language `ansi` is provided to highlight terminal outputs. For example:
+
+```ansi
+┌  Welcome to VitePress!
+│
+◇  Where should VitePress initialize the config?
+│  ./docs
+│
+◇  Site title:
+│  My Awesome Project
+│
+◇  Site description:
+│  A VitePress Site
+│
+◆  Theme:
+│  ● Default Theme (Out of the box, good-looking docs)
+│  ○ Default Theme + Customization
+│  ○ Custom Theme
+└
+```
+
+Check the [raw markdown of code snippet above](https://github.com/antfu/shikiji/blob/main/docs/languages.md?plain=1#L35).
diff --git a/docs/themes.md b/docs/themes.md
index fe21e0e5..f61cb264 100644
--- a/docs/themes.md
+++ b/docs/themes.md
@@ -1,5 +1,7 @@
 # Themes
 
+## Bundled Themes
+
 Themes listed below are re-distributed via [`tm-themes`](https://github.com/antfu/textmate-grammars-themes/tree/main/packages/tm-themes) into the `shikiji` package.
 
 <ThemesList />
@@ -7,3 +9,17 @@ Themes listed below are re-distributed via [`tm-themes`](https://github.com/antf
 Themes are covered by their repositories’ respective licenses, which are permissive (apache-2.0, mit, etc), and made available in [this NOTICE](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-themes/NOTICE).
 
 For loading your custom themes, please reference to [this guide](/guide/load-theme).
+
+## Special Themes
+
+You can set theme to `none` to bypass highlighting. This is useful as the fallback when you receive user specified theme names that are not available. For example:
+
+```ts twoslash theme:none
+import { codeToHtml } from 'shikiji'
+
+const html = codeToHtml('console.log("Hello World")', {
+  lang: 'javascript',
+  theme: 'none', // [!code hl]
+})
+```
+