feat: add a special none theme (#115)

Author: antfu

docs/languages.md

@@ -1,9 +1,53 @@
 # 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 />
 
 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).

docs/themes.md

@@ -1,9 +1,25 @@
 # 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 />
 
 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]
+})
+```
+

packages/shikiji-core/src/bundle-factory.ts

@@ -1,6 +1,6 @@
 import type { Root } from 'hast'
-import type { BundledHighlighterOptions, CodeToHastOptions, CodeToThemedTokensOptions, CodeToTokensWithThemesOptions, HighlighterCoreOptions, HighlighterGeneric, LanguageInput, MaybeArray, RequireKeys, SpecialLanguage, ThemeInput, ThemeRegistrationAny, ThemedToken, ThemedTokenWithVariants } from './types'
-import { isSpecialLang, toArray } from './utils'
+import type { BundledHighlighterOptions, CodeToHastOptions, CodeToThemedTokensOptions, CodeToTokensWithThemesOptions, HighlighterCoreOptions, HighlighterGeneric, LanguageInput, MaybeArray, RequireKeys, SpecialLanguage, SpecialTheme, ThemeInput, ThemeRegistrationAny, ThemedToken, ThemedTokenWithVariants } from './types'
+import { isSpecialLang, isSpecialTheme, toArray } from './utils'
 import { getHighlighterCore } from './highlighter'
 
 export type GetHighlighterFactory<L extends string, T extends string> = (options?: BundledHighlighterOptions<L, T>) => Promise<HighlighterGeneric<L, T>>
@@ -30,7 +30,9 @@ export function createdBundledHighlighter<BundledLangs extends string, BundledTh
       return lang as LanguageInput
     }
 
-    function resolveTheme(theme: ThemeInput | BundledThemes): ThemeInput {
+    function resolveTheme(theme: ThemeInput | BundledThemes | SpecialTheme): ThemeInput | SpecialTheme {
+      if (isSpecialTheme(theme))
+        return 'none'
       if (typeof theme === 'string') {
         const bundle = bundledThemes[theme]
         if (!bundle)
@@ -111,7 +113,7 @@ export function createSingletonShorthands<L extends string, T extends string >(g
   let _shiki: ReturnType<typeof getHighlighter>
 
   async function _getHighlighter(options: {
-    theme?: MaybeArray<T | ThemeRegistrationAny>
+    theme?: MaybeArray<T | ThemeRegistrationAny | SpecialTheme>
     lang?: MaybeArray<L | SpecialLanguage>
   } = {}) {
     if (!_shiki) {

packages/shikiji-core/src/code-to-hast.ts

@@ -62,8 +62,8 @@ export function codeToHast(
     tokens = themeTokens
       .map(line => line.map(token => mergeToken(token, themesOrder, cssVariablePrefix, defaultColor)))
 
-    fg = themes.map((t, idx) => (idx === 0 && defaultColor ? '' : `${cssVariablePrefix + t.color}:`) + themeRegs[idx].fg).join(';')
-    bg = themes.map((t, idx) => (idx === 0 && defaultColor ? '' : `${cssVariablePrefix + t.color}-bg:`) + themeRegs[idx].bg).join(';')
+    fg = themes.map((t, idx) => (idx === 0 && defaultColor ? '' : `${cssVariablePrefix + t.color}:`) + (themeRegs[idx].fg || 'inherit')).join(';')
+    bg = themes.map((t, idx) => (idx === 0 && defaultColor ? '' : `${cssVariablePrefix + t.color}-bg:`) + (themeRegs[idx].bg || 'inherit')).join(';')
     themeName = `shiki-themes ${themeRegs.map(t => t.name).join(' ')}`
     rootStyle = defaultColor ? undefined : [fg, bg].join(';')
   }

packages/shikiji-core/src/code-to-tokens.ts

@@ -5,7 +5,7 @@ import type { IGrammar } from './textmate'
 import { INITIAL } from './textmate'
 import type { CodeToThemedTokensOptions, FontStyle, ShikiInternal, ThemeRegistrationResolved, ThemedToken, ThemedTokenScopeExplanation, TokenizeWithThemeOptions } from './types'
 import { StackElementMetadata } from './stack-element-metadata'
-import { applyColorReplacements, isPlaintext, splitLines } from './utils'
+import { applyColorReplacements, isNoneTheme, isPlainLang, splitLines } from './utils'
 import { tokenizeAnsiWithTheme } from './code-to-tokens-ansi'
 
 export function codeToThemedTokens(
@@ -18,7 +18,7 @@ export function codeToThemedTokens(
     theme: themeName = internal.getLoadedThemes()[0],
   } = options
 
-  if (isPlaintext(lang))
+  if (isPlainLang(lang) || isNoneTheme(themeName))
     return splitLines(code).map(line => [{ content: line[0], offset: line[1] }])
 
   const { theme, colorMap } = internal.setTheme(themeName)

packages/shikiji-core/src/internal.ts

@@ -1,9 +1,10 @@
-import type { HighlighterCoreOptions, LanguageInput, MaybeGetter, ShikiInternal, ThemeInput, ThemeRegistrationResolved } from './types'
+import type { HighlighterCoreOptions, LanguageInput, MaybeGetter, ShikiInternal, SpecialTheme, ThemeInput, ThemeRegistrationResolved } from './types'
 import type { LoadWasmOptions } from './oniguruma'
 import { createOnigScanner, createOnigString, loadWasm } from './oniguruma'
 import { Registry } from './registry'
 import { Resolver } from './resolver'
 import { normalizeTheme } from './normalize'
+import { isSpecialTheme } from './utils'
 
 let _defaultWasmLoader: LoadWasmOptions | undefined
 /**
@@ -64,7 +65,9 @@ export async function getShikiInternal(options: HighlighterCoreOptions = {}): Pr
     return _lang
   }
 
-  function getTheme(name: string | ThemeRegistrationResolved) {
+  function getTheme(name: string | ThemeRegistrationResolved): ThemeRegistrationResolved {
+    if (name === 'none')
+      return { bg: '', fg: '', name: 'none', settings: [], type: 'dark' }
     const _theme = _registry.getTheme(name)
     if (!_theme)
       throw new Error(`[shikiji] Theme \`${name}\` not found, you may need to load it first`)
@@ -96,9 +99,13 @@ export async function getShikiInternal(options: HighlighterCoreOptions = {}): Pr
     await _registry.loadLanguages(await resolveLangs(langs))
   }
 
-  async function loadTheme(...themes: ThemeInput[]) {
+  async function loadTheme(...themes: (ThemeInput | SpecialTheme)[]) {
     await Promise.all(
-      themes.map(async theme => _registry.loadTheme(await normalizeGetter(theme))),
+      themes.map(async theme =>
+        isSpecialTheme(theme)
+          ? null
+          : _registry.loadTheme(await normalizeGetter(theme)),
+      ),
     )
   }
 

packages/shikiji-core/src/types.ts

@@ -27,6 +27,8 @@ export type PlainTextLanguage = 'text' | 'plaintext' | 'txt'
 export type AnsiLanguage = 'ansi'
 export type SpecialLanguage = PlainTextLanguage | AnsiLanguage
 
+export type SpecialTheme = 'none'
+
 export type Awaitable<T> = T | Promise<T>
 export type MaybeGetter<T> = Awaitable<MaybeModule<T>> | (() => Awaitable<MaybeModule<T>>)
 export type MaybeModule<T> = T | { default: T }
@@ -107,7 +109,7 @@ export interface HighlighterGeneric<BundledLangKeys extends string, BundledTheme
   /**
    * Load a theme to the highlighter, so later it can be used synchronously.
    */
-  loadTheme(...themes: (ThemeInput | BundledThemeKeys)[]): Promise<void>
+  loadTheme(...themes: (ThemeInput | BundledThemeKeys | SpecialTheme)[]): Promise<void>
   /**
    * Load a language to the highlighter, so later it can be used synchronously.
    */
@@ -136,6 +138,8 @@ export interface HighlighterGeneric<BundledLangKeys extends string, BundledTheme
   getLoadedLanguages(): string[]
   /**
    * Get the names of loaded themes
+   *
+   * Special-handled themes like `none` are not included.
    */
   getLoadedThemes(): string[]
 
@@ -220,7 +224,7 @@ export interface LanguageRegistration extends RawGrammar {
 
 export interface CodeToThemedTokensOptions<Languages = string, Themes = string> extends TokenizeWithThemeOptions {
   lang?: Languages | SpecialLanguage
-  theme?: Themes | ThemeRegistrationAny
+  theme?: Themes | ThemeRegistrationAny | SpecialTheme
 }
 
 export interface CodeToHastOptionsCommon<Languages extends string = string> extends
@@ -259,7 +263,7 @@ export interface CodeToTokensWithThemesOptions<Languages = string, Themes = stri
    * }
    * ```
    */
-  themes: Partial<Record<string, Themes | ThemeRegistrationAny>>
+  themes: Partial<Record<string, Themes | ThemeRegistrationAny | SpecialTheme>>
 }
 
 export interface CodeOptionsSingleTheme<Themes extends string = string> {

packages/shikiji-core/src/utils.ts

@@ -1,5 +1,5 @@
 import type { Element } from 'hast'
-import type { MaybeArray, ThemedToken } from './types'
+import type { MaybeArray, SpecialTheme, ThemeInput, ThemedToken } from './types'
 
 export function toArray<T>(x: MaybeArray<T>): T[] {
   return Array.isArray(x) ? x : [x]
@@ -15,19 +15,37 @@ export function splitLines(str: string) {
 /**
  * Check if the language is plaintext that is ignored by Shikiji.
  *
- * Hard-coded languages: `plaintext`, `txt`, `text`, `plain`.
+ * Hard-coded plain text languages: `plaintext`, `txt`, `text`, `plain`.
  */
-export function isPlaintext(lang: string | null | undefined) {
+export function isPlainLang(lang: string | null | undefined) {
   return !lang || ['plaintext', 'txt', 'text', 'plain'].includes(lang)
 }
 
 /**
- * Check if the language is specially handled by Shikiji.
+ * Check if the language is specially handled or bypassed by Shikiji.
  *
  * Hard-coded languages: `ansi` and plaintexts like `plaintext`, `txt`, `text`, `plain`.
  */
 export function isSpecialLang(lang: string) {
-  return lang === 'ansi' || isPlaintext(lang)
+  return lang === 'ansi' || isPlainLang(lang)
+}
+
+/**
+ * Check if the theme is specially handled or bypassed by Shikiji.
+ *
+ * Hard-coded themes: `none`.
+ */
+export function isNoneTheme(theme: string | ThemeInput | null | undefined): theme is 'none' {
+  return theme === 'none'
+}
+
+/**
+ * Check if the theme is specially handled or bypassed by Shikiji.
+ *
+ * Hard-coded themes: `none`.
+ */
+export function isSpecialTheme(theme: string | ThemeInput | null | undefined): theme is SpecialTheme {
+  return isNoneTheme(theme)
 }
 
 /**
@@ -91,3 +109,8 @@ export function splitToken<
 export function applyColorReplacements(color: string, replacements?: Record<string, string>): string {
   return replacements?.[color.toLowerCase()] || color
 }
+
+/**
+ * @deprecated Use `isPlainLang` instead.
+ */
+export const isPlaintext = isPlainLang

packages/shikiji-twoslash/test/out/rich/rich-none-theme.html

@@ -0,0 +1,40 @@
+
+<link rel="stylesheet" href="../../../style-rich.css" />
+<style>
+html, body { margin: 0; }
+.shiki { padding: 2em; }
+
+.dark .shiki,
+.dark .shiki span {
+  color: var(--shiki-dark, inherit);
+  --twoslash-popup-bg: var(--shiki-dark-bg, inherit);
+}
+
+.dark .shiki {
+  background-color: var(--shiki-dark-bg, inherit);
+}
+
+html:not(.dark) .shiki,
+html:not(.dark) .shiki span {
+  color: var(--shiki-light, inherit);
+  --twoslash-popup-bg: var(--shiki-light-bg, inherit);
+}
+
+html:not(.dark) .shiki {
+  background-color: var(--shiki-light-bg, inherit);
+}
+</style>
+<pre class="shiki none twoslash lsp" style="background-color:;color:" tabindex="0"><code><span class="line"><span>interface </span><span>Todo</span><span> {</span></span>
+<span class="line"><span>  </span><span>/** The title of the todo item */</span></span>
+<span class="line"><span>  </span><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>Todo.title: string</span></span></code><div class="twoslash-popup-docs">The title of the todo item</div></span>title</span></span><span>: string;</span></span>
+<span class="line"><span>}</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span>const </span><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>const todo: Readonly&#x3C;Todo></span></span></code></span>todo</span></span><span>: </span><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>type Readonly&#x3C;T> = { readonly [P in keyof T]: T[P]; }</span></span></code><div class="twoslash-popup-docs">Make all properties in T readonly</div></span>Readonly</span></span><span>&#x3C;</span><span>Todo</span><span>> = {</span></span>
+<span class="line"><span>  </span><span><span class="twoslash-hover twoslash-query-presisted"><span class="twoslash-popup-container"><div class="twoslash-popup-arrow"></div><code class="twoslash-popup-code"><span class="line"><span>title: string</span></span></code><div class="twoslash-popup-docs">The title of the todo item</div></span>title</span></span><span>: "Delete inactive users".</span><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>String.toUpperCase(): string</span></span></code><div class="twoslash-popup-docs">Converts all the alphabetic characters in a string to uppercase.</div></span>toUpperCase</span></span><span>(),</span></span>
+<span class="line"><span>};</span></span>
+<span class="line"><span></span></span>
+<span class="line"><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>const todo: Readonly&#x3C;Todo></span></span></code></span>todo</span></span><span>.</span><span><span class="twoslash-error">title</span></span><span> = "Hello";</span></span><div class="twoslash-meta-line twoslash-error-line">Cannot assign to 'title' because it is a read-only property.</div><span class="line"><span></span></span>
+<span class="line"><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>var Number: NumberConstructor</span></span></code><div class="twoslash-popup-docs">An object that represents a number of any kind. All JavaScript numbers are 64-bit floating-point numbers.</div></span>Number</span></span><span>.</span><span><span>p<span class="twoslash-completion-cursor"><ul class="twoslash-completion-list"><li><span class="twoslash-completions-icon completions-method"><svg viewBox="0 0 32 32"><path fill="currentColor" d="m19.626 29.526l-.516-1.933a12.004 12.004 0 0 0 6.121-19.26l1.538-1.28a14.003 14.003 0 0 1-7.143 22.473"></path><path fill="currentColor" d="M10 29H8v-3.82l.804-.16C10.262 24.727 12 23.62 12 20v-1.382l-4-2v-2.236l4-2V12c0-5.467 3.925-9 10-9h2v3.82l-.804.16C21.738 7.273 20 8.38 20 12v.382l4 2v2.236l-4 2V20c0 5.467-3.925 9-10 9m0-2c4.935 0 8-2.682 8-7v-2.618l3.764-1.882L18 13.618V12c0-4.578 2.385-6.192 4-6.76V5c-4.935 0-8 2.682-8 7v1.618L10.236 15.5L14 17.382V20c0 4.578-2.385 6.192-4 6.76Z"></path><path fill="currentColor" d="M5.231 24.947a14.003 14.003 0 0 1 7.147-22.474l.516 1.932a12.004 12.004 0 0 0-6.125 19.263Z"></path></svg></span><span><span class="twoslash-completions-matched">p</span><span class="twoslash-completions-unmatched">arseFloat</span></span></li><li><span class="twoslash-completions-icon completions-method"><svg viewBox="0 0 32 32"><path fill="currentColor" d="m19.626 29.526l-.516-1.933a12.004 12.004 0 0 0 6.121-19.26l1.538-1.28a14.003 14.003 0 0 1-7.143 22.473"></path><path fill="currentColor" d="M10 29H8v-3.82l.804-.16C10.262 24.727 12 23.62 12 20v-1.382l-4-2v-2.236l4-2V12c0-5.467 3.925-9 10-9h2v3.82l-.804.16C21.738 7.273 20 8.38 20 12v.382l4 2v2.236l-4 2V20c0 5.467-3.925 9-10 9m0-2c4.935 0 8-2.682 8-7v-2.618l3.764-1.882L18 13.618V12c0-4.578 2.385-6.192 4-6.76V5c-4.935 0-8 2.682-8 7v1.618L10.236 15.5L14 17.382V20c0 4.578-2.385 6.192-4 6.76Z"></path><path fill="currentColor" d="M5.231 24.947a14.003 14.003 0 0 1 7.147-22.474l.516 1.932a12.004 12.004 0 0 0-6.125 19.263Z"></path></svg></span><span><span class="twoslash-completions-matched">p</span><span class="twoslash-completions-unmatched">arseInt</span></span></li><li><span class="twoslash-completions-icon completions-property"><svg viewBox="0 0 32 32"><path fill="currentColor" d="M12.1 2a9.8 9.8 0 0 0-5.4 1.6l6.4 6.4a2.1 2.1 0 0 1 .2 3a2.1 2.1 0 0 1-3-.2L3.7 6.4A9.84 9.84 0 0 0 2 12.1a10.14 10.14 0 0 0 10.1 10.1a10.9 10.9 0 0 0 2.6-.3l6.7 6.7a5 5 0 0 0 7.1-7.1l-6.7-6.7a10.9 10.9 0 0 0 .3-2.6A10 10 0 0 0 12.1 2m8 10.1a7.61 7.61 0 0 1-.3 2.1l-.3 1.1l.8.8l6.7 6.7a2.88 2.88 0 0 1 .9 2.1A2.72 2.72 0 0 1 27 27a2.9 2.9 0 0 1-4.2 0l-6.7-6.7l-.8-.8l-1.1.3a7.61 7.61 0 0 1-2.1.3a8.27 8.27 0 0 1-5.7-2.3A7.63 7.63 0 0 1 4 12.1a8.33 8.33 0 0 1 .3-2.2l4.4 4.4a4.14 4.14 0 0 0 5.9.2a4.14 4.14 0 0 0-.2-5.9L10 4.2a6.45 6.45 0 0 1 2-.3a8.27 8.27 0 0 1 5.7 2.3a8.49 8.49 0 0 1 2.4 5.9"></path></svg></span><span><span class="twoslash-completions-matched">p</span><span class="twoslash-completions-unmatched">rototype</span></span></li></ul></span></span></span><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>NumberConstructor.parseInt(string: string, radix?: number | undefined): number</span></span></code><div class="twoslash-popup-docs">Converts A string to an integer.</div><div class="twoslash-popup-docs twoslash-popup-docs-tags"><span class="twoslash-popup-docs-tag"><span class="twoslash-popup-docs-tag-name">@param</span><span class="twoslash-popup-docs-tag-value">string A string to convert into a number.</span></span><span class="twoslash-popup-docs-tag"><span class="twoslash-popup-docs-tag-name">@param</span><span class="twoslash-popup-docs-tag-value">radix A value between 2 and 36 that specifies the base of the number in `string`.
+If this argument is not supplied, strings with a prefix of '0x' are considered hexadecimal.
+All other strings are considered decimal.</span></span></div></span>arseInt</span></span><span>(</span><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>const todo: Readonly&#x3C;Todo></span></span></code></span>todo</span></span><span>.</span><span><span class="twoslash-hover"><span class="twoslash-popup-container"><code class="twoslash-popup-code"><span class="line"><span>title: string</span></span></code><div class="twoslash-popup-docs">The title of the todo item</div></span>title</span></span><span>, 10);</span></span>
+<span class="line"><span></span></span></code></pre>