OpenParable
Skip to content
← Back to skills

Shiki Skilld

Development
shiki-skilld

Shiki 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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: CreatedBundledHighlighterOptions type removed — renamed to CreateBundledHighlighterOptions (typo fix) source

  • BREAKING: createdBundledHighlighter function removed — renamed to createBundledHighlighter (typo fix) source

  • BREAKING: theme option removed in TwoslashFloatingVue — use themes object instead source

  • NEW: @shikijs/markdown-exit package — modern markdown parser with native async support, replaces markdown-it approach source

  • NEW: @shikijs/primitive package — 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 shiki or shiki/bundle/full in production applications. Instead use fine-grained modules such as shiki/core, @shikijs/langs/typescript, and @shikijs/themes/nord to 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' or enforce: 'post' modifiers to control execution order relative to default transformers, ensuring dependencies are resolved correctly source

  • Use dual themes by passing themes object with light and dark keys, 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() and loadTheme() methods to support runtime addition without recreating the highlighter instance source source

  • Use grammarState and getLastGrammarState() when highlighting code snippets to provide the correct parsing context, making inline type annotations and partial code blocks highlight correctly source

  • Pass highlighted hast nodes to getLastGrammarState() instead of code strings to retrieve cached grammar state, avoiding redundant highlighting execution in pausable or streaming scenarios source

  • Use createHighlighterCoreSync with explicit engine and resolved themes/languages for completely synchronous highlighting when necessary, requiring the JavaScript engine or pre-loaded Oniguruma source