docs: add guidance for handling embedded languages in fine-grained bu… #1105
+303
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ndles Fixes shikijs#1039 When using fine-grained bundles with createHighlighterCore, markdown's embedded languages (like JavaScript, Python, HTML in code blocks) are not loaded automatically. This is by design to keep bundles minimal, but it can be confusing for users. This PR provides comprehensive documentation and examples showing three approaches: 1. **Manual Loading**: Explicitly load all expected embedded languages upfront 2. **Dynamic Detection**: Use guessEmbeddedLanguages to detect and load on-demand 3. **Custom Shorthands (Recommended)**: Create custom shorthands with auto-loading The guessEmbeddedLanguages utility was already exported from @shikijs/core, so no code changes were needed to the library itself. Changes: - Added "Handling Embedded Languages" section to bundles.md with detailed examples - Added tip in best-performance.md about embedded languages - Created comprehensive test suite with all three solution approaches - Added practical example file demonstrating each solution This helps users avoid the current workaround of manually overriding embeddedLangs on the markdown grammar object, which is verbose and fragile.
✅ Deploy Preview for shiki-matsu ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for shiki-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Fix import sorting in test file - Remove trailing whitespace - Fix quote style for object properties - Remove example file with excessive console.log usage - Format code blocks in documentation properly
- Fix import ordering (move vitest import to end) - Fix guessEmbeddedLanguages test expectations: - Function returns language aliases as found in code (e.g., 'js', 'ts') - When no highlighter provided, returns all detected languages - When highlighter provided, filters to only bundled languages - Fix test for dynamically loading embedded languages: - Don't pass highlighter to guessEmbeddedLanguages when using createHighlighterCore - createHighlighterCore has no bundle, so filtering would return empty array - Fix HTML entity test (HTML tags are escaped in output) - Fix markdown code block formatting in docs - Use createdBundledHighlighter in bundle filter test for correct behavior
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1105 +/- ##
==========================================
+ Coverage 88.35% 88.38% +0.03%
==========================================
Files 74 74
Lines 3322 3322
Branches 956 954 -2
==========================================
+ Hits 2935 2936 +1
+ Misses 344 343 -1
Partials 43 43 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
- Sort named imports alphabetically (createdBundledHighlighter before createSingletonShorthands) - Add blank lines in tip block for proper markdown formatting
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR fixes an issue where code blocks inside markdown aren't highlighted when using fine-grained bundles.
What's happening:
When you use
createHighlighterCorewith just markdown, embedded languages (JavaScript, Python, HTML, etc. in code blocks) don't get loaded automatically. This is intentional to keep bundles small, but it's confusing and leads to unhighlighted code blocks.Users have been working around this by manually overriding the markdown grammar's
embeddedLangsproperty, which is pretty fragile and verbose.What this PR does:
Adds clear documentation and examples showing three ways to handle this properly:
guessEmbeddedLanguagesto auto-detect what's neededThe best part? The
guessEmbeddedLanguagesutility was already there - we just needed to document how to use it!What changed:
docs/guide/bundles.mddocs/guide/best-performance.mdLinked Issues
Fixes #1039
Additional context
The recommended approach (custom shorthands) gives you the same smooth experience as the full bundle presets, but with complete control over what gets bundled.
Everything is backward compatible - this is just documentation to help people avoid common pitfalls.