Shiki Skilld
Developmentshiki-skilldShiki Skilld is an Agent Skill for development published in the harlan-zw/mdream repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
ALWAYS use when writing code importing "shiki". Consult for debugging, best practices, or modifying shiki.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/harlan-zw/mdream/blob/HEAD/.claude/skills/shiki-skilld/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/shiki-skilld, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
shikijs/shiki shiki
Version: 4.0.2 (Mar 2026) Deps: @shikijs/vscode-textmate@^10.0.2, @types/hast@^3.0.4, @shikijs/[email protected], @shikijs/[email protected], @shikijs/[email protected], @shikijs/[email protected], @shikijs/[email protected], @shikijs/[email protected] Tags: next: 0.9.4 (May 2021), latest: 4.0.2 (Mar 2026)
References: package.json — exports, entry points • README — setup, basic usage • Docs — API reference, guides • GitHub Issues — bugs, workarounds, edge cases • GitHub Discussions — Q&A, patterns, recipes • Releases — changelog, breaking changes, new APIs
Search
Use skilld search instead of grepping .skilld/ directories — hybrid semantic + keyword search across all indexed docs, issues, and releases. If skilld is unavailable, use npx -y skilld search.
skilld search "query" -p shiki
skilld search "issues:error handling" -p shiki
skilld search "releases:deprecated" -p shiki
Filters: docs:, issues:, releases: prefix narrows by source type.
API Changes
This section documents version-specific API changes — prioritize recent major/minor releases.
-
BREAKING: Node.js ≥ 20 required — Shiki v4 drops Node.js 18 support which reached EOL in April 2025 source
-
BREAKING:
CreatedBundledHighlighterOptionstype removed — renamed toCreateBundledHighlighterOptions(typo fix) source -
BREAKING:
createdBundledHighlighterfunction removed — renamed tocreateBundledHighlighter(typo fix) source -
BREAKING:
themeoption removed inTwoslashFloatingVue— usethemesobject instead source -
NEW:
@shikijs/markdown-exitpackage — modern markdown parser with native async support, replacesmarkdown-itapproach source -
NEW:
@shikijs/primitivepackage — leaner primitive package for core functionality source
Also changed: CSS class twoslash-query-presisted renamed to twoslash-query-persisted · rootStyle: false option added · transformerRemoveComments transformer added · classActiveCode option for notation transformers · zeroIndexed option for transformerMetaHighlight · leading position support in transformerRenderWhitespace
Best Practices
-
Cache the highlighter instance using singleton pattern to avoid recreating it for each call, as initialization is expensive. Reuse across requests and call
dispose()when no longer needed to free memory source -
Avoid importing full bundles like
shikiorshiki/bundle/fullin production applications. Instead use fine-grained modules such asshiki/core,@shikijs/langs/typescript, and@shikijs/themes/nordto reduce bundle size and memory usage source -
Use shorthand functions like
codeToHtml()for on-demand loading when highlighting can be asynchronous, as they maintain an internal highlighter and load only necessary themes and languages without upfront overhead source -
Use the JavaScript regex engine instead of Oniguruma for web applications to avoid large WebAssembly files, faster startup, and better native performance — ensure language compatibility via the reference table source
-
Apply custom transformers with
enforce: 'pre'orenforce: 'post'modifiers to control execution order relative to default transformers, ensuring dependencies are resolved correctly source -
Use dual themes by passing
themesobject withlightanddarkkeys, which generates CSS variables on each token for automatic theme switching via media queries or class selectors source -
Load languages and themes dynamically after highlighter creation using
loadLanguage()andloadTheme()methods to support runtime addition without recreating the highlighter instance source source -
Use
grammarStateandgetLastGrammarState()when highlighting code snippets to provide the correct parsing context, making inline type annotations and partial code blocks highlight correctly source -
Pass highlighted
hastnodes togetLastGrammarState()instead of code strings to retrieve cached grammar state, avoiding redundant highlighting execution in pausable or streaming scenarios source -
Use
createHighlighterCoreSyncwith explicitengineand resolved themes/languages for completely synchronous highlighting when necessary, requiring the JavaScript engine or pre-loaded Oniguruma source