Skip to content

Commit

Permalink
docs: prefer @shikijs/langs and @shikijs/themes
Browse files Browse the repository at this point in the history
  • Loading branch information
antfu committed Jan 3, 2025
1 parent 89461c7 commit d1a840a
Show file tree
Hide file tree
Showing 8 changed files with 23 additions and 24 deletions.
14 changes: 7 additions & 7 deletions docs/guide/bundles.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,24 +44,24 @@ When importing `shiki`, all the themes and languages are bundled as async chunks

```ts twoslash
// @noErrors
// directly import the theme and language modules, only the ones you imported will be bundled.
import nord from '@shikijs/themes/nord'

// `shiki/core` entry does not include any themes or languages or the wasm binary.
import { createHighlighterCore } from 'shiki/core'
import { createOnigurumaEngine } from 'shiki/engine/oniguruma'

// directly import the theme and language modules, only the ones you imported will be bundled.
import nord from 'shiki/themes/nord.mjs'

const highlighter = await createHighlighterCore({
themes: [
// instead of strings, you need to pass the imported module
nord,
// or a dynamic import if you want to do chunk splitting
import('shiki/themes/material-theme-ocean.mjs')
import('@shikijs/themes/material-theme-ocean')
],
langs: [
import('shiki/langs/javascript.mjs'),
import('@shikijs/langs/javascript'),
// shiki will try to interop the module with the default export
() => import('shiki/langs/css.mjs'),
() => import('@shikijs/langs/css'),
// or a getter that returns custom grammar
async () => JSON.parse(await fs.readFile('my-grammar.json', 'utf-8'))
],
Expand All @@ -70,7 +70,7 @@ const highlighter = await createHighlighterCore({
})

// optionally, load themes and languages after creation
await highlighter.loadTheme(import('shiki/themes/vitesse-light.mjs'))
await highlighter.loadTheme(import('@shikijs/themes/vitesse-light'))

const code = highlighter.codeToHtml('const a = 1', {
lang: 'javascript',
Expand Down
6 changes: 3 additions & 3 deletions docs/guide/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ To use `shiki` in the browser via CDN, you can use [esm.run](https://esm.run) or
</body>
```

It's quite efficient as it will only load the languages and themes on demand. For the code snippet above, only four requests will be fired (`shiki`, `shiki/themes/vitesse-light.mjs`, `shiki/langs/javascript.mjs`, `shiki/wasm.mjs`), with around 200KB data transferred in total.
It's quite efficient as it will only load the languages and themes on demand. For the code snippet above, only four requests will be fired (`shiki`, `@shikijs/themes/vitesse-light`, `@shikijs/langs/javascript`, `shiki/wasm.mjs`), with around 200KB data transferred in total.

[Demo](https://jsfiddle.net/t7brz23v/)

Expand All @@ -245,9 +245,9 @@ Meanwhile, it's also recommended to use the [Fine-grained Bundle](#fine-grained-

```ts twoslash theme:nord
// @noErrors
import js from '@shikijs/langs/javascript'
import nord from '@shikijs/themes/nord'
import { createHighlighterCore, loadWasm } from 'shiki/core'
import js from 'shiki/langs/javascript.mjs'
import nord from 'shiki/themes/nord.mjs'

// import wasm as assets
await loadWasm(import('shiki/onig.wasm'))
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/migrate.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Breaking changes that you need to migrate manually:
Breaking changes applies to main package `shiki`, but are shimmed by the [compatible build `@shikijs/compat`](/guide/compat#compatibility-build):

- Top-level named exports `setCDN`, `loadLanguage`, `loadTheme`, `setWasm` are dropped as they are not needed anymore.
- `BUNDLED_LANGUAGES`, `BUNDLED_THEMES` are moved to `shiki/langs` and `shiki/themes` and renamed to `bundledLanguages` and `bundledThemes` respectively.
- `BUNDLED_LANGUAGES`, `BUNDLED_THEMES` are moved to `@shikijs/langs` and `@shikijs/themes` and renamed to `bundledLanguages` and `bundledThemes` respectively.
- `theme` option for `createHighlighter` is dropped, use `themes` with an array instead.
- Highlighter does not maintain an internal default theme context. `theme` option is required for `codeToHtml` and `codeToTokens`.
- `codeToThemedTokens` is renamed to `codeToTokensBase`, a higher level `codeToTokens` is added.
Expand Down
8 changes: 4 additions & 4 deletions docs/guide/sync-usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ The `await createHighlighter()` and `highlighter.codeToHtml()` are already the e
In some extreme cases that you need to run Shiki completely synchronously, since v1.16, we provide a synchronous version of the core API. You can use `createHighlighterCoreSync` to create a highlighter instance synchronously.

```ts
import js from '@shikijs/langs/javascript'
import nord from '@shikijs/themes/nord'
import { createHighlighterCoreSync } from 'shiki/core'
import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
import js from 'shiki/langs/javascript.mjs'
import nord from 'shiki/themes/nord.mjs'

const shiki = createHighlighterCoreSync({
themes: [nord],
Expand All @@ -24,10 +24,10 @@ When doing so, it requires all `themes` and `langs` to be provide as plain objec
The [Oniguruma Engine](/guide/regex-engines#oniguruma-engine) can only be created asynchronously, so you need to resolve the engine promise before creating the sync highlighter.

```ts
import js from '@shikijs/langs/javascript'
import nord from '@shikijs/themes/nord'
import { createHighlighterCoreSync } from 'shiki/core'
import { createOnigurumaEngine } from 'shiki/engine/oniguruma'
import js from 'shiki/langs/javascript.mjs'
import nord from 'shiki/themes/nord.mjs'

// Load this somewhere beforehand
const engine = await createOnigurumaEngine(import('shiki/wasm'))
Expand Down
4 changes: 2 additions & 2 deletions docs/packages/markdown-it.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@ import { createHighlighterCore } from 'shiki/core'

const highlighter = await createHighlighterCore({
themes: [
import('shiki/themes/vitesse-light.mjs')
import('@shikijs/themes/vitesse-light')
],
langs: [
import('shiki/langs/javascript.mjs'),
import('@shikijs/langs/javascript'),
],
loadWasm: import('shiki/wasm')
})
Expand Down
4 changes: 2 additions & 2 deletions docs/packages/rehype.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,10 @@ import { unified } from 'unified'

const highlighter = await createHighlighterCore({
themes: [
import('shiki/themes/vitesse-light.mjs')
import('@shikijs/themes/vitesse-light')
],
langs: [
import('shiki/langs/javascript.mjs'),
import('@shikijs/langs/javascript'),
],
loadWasm: import('shiki/wasm')
})
Expand Down
4 changes: 2 additions & 2 deletions packages/core/src/constructors/bundle-factory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,11 @@ import { createHighlighterCore } from './highlighter'
* ```ts
* const createHighlighter = createdBundledHighlighter({
* langs: {
* typescript: () => import('shiki/langs/typescript.mjs'),
* typescript: () => import('@shikijs/langs/typescript'),
* // ...
* },
* themes: {
* nord: () => import('shiki/themes/nord.mjs'),
* nord: () => import('@shikijs/themes/nord'),
* // ...
* },
* engine: () => createOnigurumaEngine(), // or createJavaScriptRegexEngine()
Expand Down
5 changes: 2 additions & 3 deletions packages/shiki/test/cf.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
import type { LanguageRegistration } from '@shikijs/types'
import { loadWasm } from '@shikijs/engine-oniguruma'
import js from '@shikijs/langs/javascript'
import nord from '@shikijs/themes/nord'
import { createHighlighterCore } from 'shiki/core'

import js from 'shiki/langs/javascript.mjs'
import nord from 'shiki/themes/nord.mjs'

// @ts-expect-error no types
// eslint-disable-next-line antfu/no-import-dist
import wasm from '../dist/onig.wasm'
Expand Down

0 comments on commit d1a840a

Please sign in to comment.