feat!: rename `getHighlighter` to `createHighlighter`

antfu commented 3 months ago

The function name getHighlighter, inherited from Shiki v0.x, which is somehow confusing. While it is supposed to be a singleton, we see people using it incorrectly in components or loops:

693
567

While we improved the docs in https://github.com/shikijs/shiki/commit/412fe10ef185a329ca9d5e2f722751e3cd7389a5, I think the confusing still down to the name prefix get reads like it will retrieve the global instance, while it actually not. In the actual behavior, it's more like create a new instance every time calling the function, thus this PR propose renaming:

getHighlighter to createHighlighter
getHighlighterCore to createHighlighterCore
getShikiInternal to createShikiInternal

Alternatively, we encourage users to use getSingletonHighlighter instead, where it holds the singleton instance underneath, and loads new themes/languages automatically.

Changes rolling out plan

v1.9.0 will introduce createHighlighter getSingletonHighlighter functions. All docs change to create* version. APIs like getHighlighter are shims to behave like before, but marked as deprecate on the type level.
v1.10.0+ warning messages will be print at runtime when using getHighlighter etc.
v2.0.0 Deprecated APIs will be removed (breaking changes)

netlify[bot] commented 3 months ago

Deploy Preview for shiki-matsu ready!

Name	Link
Latest commit	850a2a7ac156fbf4686c718a5b370f4d2c35680c
Latest deploy log	https://app.netlify.com/sites/shiki-matsu/deploys/6675a884b1a9990008387590
Deploy Preview	https://deploy-preview-702--shiki-matsu.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify[bot] commented 3 months ago

Deploy Preview for shiki-next ready!

Name	Link
Latest commit	850a2a7ac156fbf4686c718a5b370f4d2c35680c
Latest deploy log	https://app.netlify.com/sites/shiki-next/deploys/6675a8840eedf80008ebf851
Deploy Preview	https://deploy-preview-702--shiki-next.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

codecov[bot] commented 3 months ago

Codecov Report

Attention: Patch coverage is 90.55118% with 12 lines in your changes missing coverage. Please review.

Project coverage is 96.31%. Comparing base (2468337) to head (850a2a7).

Files	Patch %	Lines
packages/core/src/bundle-factory.ts	94.11%	3 Missing :warning:
packages/core/src/internal.ts	66.66%	3 Missing :warning:
packages/shiki/src/bundle-full.ts	72.72%	3 Missing :warning:
packages/shiki/src/bundle-web.ts	72.72%	3 Missing :warning:

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #702 +/- ## ========================================== - Coverage 96.45% 96.31% -0.14% ========================================== Files 70 70 Lines 5984 6056 +72 Branches 799 805 +6 ========================================== + Hits 5772 5833 +61 - Misses 207 218 +11 Partials 5 5 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

shikijs / shiki