English
Shiki highlighting
@cjslash/shiki connects @cjslash/core analysis results to Shiki. Node splitting, position mapping, and HTML rendering reuse @shikijs/twoslash and its twoslash-* CSS classes.
Install
bash
pnpm add -D @cjslash/core @cjslash/shiki shiki @shikijs/twoslash@shikijs/twoslash is included here for the stylesheet imported directly by your application. Use the Cangjie grammar exported by @cjslash/shiki in the highlighter.
Analyze before highlighting
ts
import { createCjslasher } from '@cjslash/core'
import { cangjieLanguage, transformerCjslash } from '@cjslash/shiki'
import { createHighlighter } from 'shiki'
await using cjslasher = await createCjslasher({ sdkPath: '/path/to/cangjie' })
const transformer = transformerCjslash({ cjslasher: cjslasher.analyze })
const source = 'let answer = 42\n// ^?\nmain() { println(answer) }\n'
await transformer.prepare(source)
const highlighter = await createHighlighter({
langs: [cangjieLanguage],
themes: ['monokai'],
})
try {
const html = highlighter.codeToHtml(source, {
lang: 'cj',
theme: 'monokai',
transformers: [transformer],
})
console.log(html)
}
finally {
highlighter.dispose()
}The Cangjie LSP is asynchronous, while the Shiki transformer reads results synchronously during rendering. Wait for prepare(source), then pass the exact same original source to codeToHtml(). Do not replace it with result.code: the transformer applies cropping and position adjustments.
Load the presentation styles
Import the stylesheet in the application that displays the HTML:
ts
import '@shikijs/twoslash/style-rich.css'This stylesheet supports the default rich renderer. For FloatingVue popups in VitePress, use the VitePress plugin, which installs its client and styles automatically.
Prepared result caching
A transformer caches successful results by their complete original source. Concurrent prepare() calls for identical source share one promise, and failed preparation can be retried. This cache belongs to the transformer instance; it is not a disk cache and does not persist across builds.
Execution options are captured when the transformer is created. Cloneable settings are copied; signals and callbacks keep their original references. Create a new transformer when changing the SDK or analysis settings. Prepared results can still be rendered after the analyzer has been disposed.
The caller owns the analyzer. The transformer does not dispose it.
Trigger rules
The Shiki integration processes cj by default, with cangjie and Cangjie aliases. It does not require cjslash metadata by default. Set explicitTrigger: true to require that metadata:
ts
import { createCjslasher } from '@cjslash/core'
import { transformerCjslash } from '@cjslash/shiki'
await using cjslasher = await createCjslasher({ sdkPath: '/path/to/cangjie' })
const transformer = transformerCjslash({
cjslasher: cjslasher.analyze,
explicitTrigger: true,
})nocjslash and no-cjslash disable transformation by default. When calling Shiki directly, pass metadata as meta: { __raw: 'cjslash' }. Trigger rules control rendering and do not replace the preparation step.
Customize rendering
rendererRich accepts upstream RendererRichOptions. For example, hide documentation returned by the SDK:
ts
import { createCjslasher } from '@cjslash/core'
import { transformerCjslash } from '@cjslash/shiki'
await using cjslasher = await createCjslasher({ sdkPath: '/path/to/cangjie' })
const transformer = transformerCjslash({
cjslasher: cjslasher.analyze,
rendererRich: { jsdoc: false },
})For complete control over HTML output, pass a renderer implementing the upstream TwoslashRenderer shape. rendererClassic, rendererRich, ShikiTwoslashError, and related types are re-exported directly; see the API reference.
Handle errors
prepare() rejects directly when analysis fails. Catch that rejection in the calling code. throws, onTwoslashError, and onShikiError control upstream behavior during synchronous rendering; they do not catch the earlier asynchronous analysis failure.
If you see “source has not been prepared,” check that preparation finished and that the source, including line endings and trailing whitespace, is identical in both calls.