feat!: enable runtime warning by default, v2 release blog post (#898)

shikijs · Jan 20, 2025 · 9868339 · 9868339
1 parent 50864af
commit 9868339
Show file tree

Hide file tree

Showing 5 changed files with 136 additions and 61 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -24,7 +24,6 @@ const GUIDES: DefaultTheme.NavItemWithLink[] = [
   { text: 'Synchronous Usage', link: '/guide/sync-usage' },
   { text: 'Custom Themes', link: '/guide/load-theme' },
   { text: 'Custom Languages', link: '/guide/load-lang' },
-  { text: 'Future', link: '/guide/future' },
   { text: 'Migration', link: '/guide/migrate' },
   { text: 'Compatibility Build', link: '/guide/compat' },
 ]
@@ -50,12 +49,18 @@ const INTEGRATIONS: DefaultTheme.NavItemWithLink[] = [
   { text: 'CLI', link: '/packages/cli' },
 ]
 
+const BLOGS: DefaultTheme.NavItemWithLink[] = [
+  { text: 'Shiki v2.0', link: '/blog/v2' },
+  { text: 'The Evolution of Shiki v1.0', link: 'https://nuxt.com/blog/shiki-v1' },
+]
+
 const VERSIONS: (DefaultTheme.NavItemWithLink | DefaultTheme.NavItemChildren)[] = [
   { text: `v${version} (current)`, link: '/' },
   { text: `Release Notes`, link: 'https://github.com/shikijs/shiki/releases' },
   { text: `Contributing`, link: 'https://github.com/shikijs/shiki/blob/main/CONTRIBUTING.md' },
   {
     items: [
+      { text: 'Migration from v1.0', link: '/blog/v2' },
       { text: 'Migration from v0.14', link: '/guide/migrate#migrate-from-v0-14' },
       { text: 'Migration from Shikiji', link: '/guide/migrate#migrate-from-shikiji' },
     ],
@@ -157,10 +162,10 @@ export default withMermaid(defineConfig({
         text: 'References',
         items: REFERENCES,
       },
-      // {
-      //   text: 'Play',
-      //   link: '/play',
-      // },
+      {
+        text: 'Blog',
+        items: BLOGS,
+      },
       {
         text: `v${version}`,
         items: VERSIONS,
@@ -196,6 +201,7 @@ export default withMermaid(defineConfig({
     },
 
     socialLinks: [
+      { icon: 'bluesky', link: 'https://bsky.app/profile/shiki.style' },
       { icon: 'github', link: 'https://github.com/shikijs/shiki' },
     ],
 

diff --git a/docs/blog/v2.md b/docs/blog/v2.md
@@ -0,0 +1,116 @@
+# Shiki v2.0.0
+
+Shiki v2.0.0 itself is a **boring** release.
+
+In case you missed them, here are quote some cool new features we have landed in minor releases progressively:
+
+| Version                                                          | Noteable New Features                                                                                                                                 |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [v1.1.0](https://github.com/shikijs/shiki/releases/tag/v1.1.0)   | Better Twoslash support                                                                                                                               |
+| [v1.3.0](https://github.com/shikijs/shiki/releases/tag/v1.3.0)   | New `structure: inline` option                                                                                                                        |
+| [v1.6.0](https://github.com/shikijs/shiki/releases/tag/v1.6.0)   | Scoped color replacement, thanks to [@QuentinRoy](https://github.com/QuentinRoy)                                                                      |
+| [v1.8.0](https://github.com/shikijs/shiki/releases/tag/v1.8.0)   | Expose `.dispose()` method for explicit resource cleanup                                                                                              |
+| [v1.10.0](https://github.com/shikijs/shiki/releases/tag/v1.10.0) | Introduced [Grammar State](https://github.com/shikijs/shiki/pull/712) for partial code highlighting                                                   |
+| [v1.15.0](https://github.com/shikijs/shiki/releases/tag/v1.15.0) | Introduced [JavaScript Engine](/guide/regex-engines#javascript-engine) with better portability and bundle size                                        |
+| [v1.16.0](https://github.com/shikijs/shiki/releases/tag/v1.16.0) | Support [Synchronous Usage](/guide/sync-usage)                                                                                                        |
+| [v1.19.0](https://github.com/shikijs/shiki/releases/tag/v1.19.0) | Introduced `enableDeprecationWarnings()` function for easier migration. Support object-style `htmlStyle` and new `htmlAttrs` on themed tokens.        |
+| [v1.23.0](https://github.com/shikijs/shiki/releases/tag/v1.23.0) | New [`@shikijs/colorized-brackets`](/packages/colorized-brackets) package, thanks to [@MichaelMakesGames](https://github.com/MichaelMakesGames)       |
+| [v1.24.0](https://github.com/shikijs/shiki/releases/tag/v1.24.0) | Improved performance and accuracy for the JavaScript engine, thanks to [@slevithan](https://github.com/slevithan)                                     |
+| [v1.25.0](https://github.com/shikijs/shiki/releases/tag/v1.25.0) | Separated themes and languages into `@shikijs/themes` and `@shikijs/languages` packages                                                               |
+| [v1.26.0](https://github.com/shikijs/shiki/releases/tag/v1.26.0) | Introduced [pre-compiled languages](https://shiki.style/guide/regex-engines#pre-compiled-languages) package for smaller bundle and better performance |
+| [v1.27.0](https://github.com/shikijs/shiki/releases/tag/v1.27.0) | New [`shiki-codegen`](/packages/codegen) package for easier fine-grained bundle creation                                                              |
+| [v1.29.0](https://github.com/shikijs/shiki/releases/tag/v1.28.0) | Improved the transformer matching algorithm, introduce `matchAlgorithm` option. Thanks to [@fuma-nama](https://github.com/fuma-nama)                  |
+
+Among all these new features, we also includes a lot of new languages support and new themes. Check out [languages](/languages) and [themes](/themes) list for the full list.
+
+Meanwhile, huge thanks to [@slevithan](https://github.com/slevithan)'s great work on [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es) that make the [JavaScript engine supports 97.2% of all the languages](/references/engine-js-compat).
+
+## Breaking Changes
+
+There are **NO** hard breaking changes in v2.0.0. It serves as a stepping stone for the upcoming v3.0.0.
+
+The only change in v2 is that Shiki will now **emit warnings when you are using APIs that are deprecated** and planned to be removed in v3. As this might affect the end users, we make a major version bump so you can opt-in to the warnings and prepare for the future removal.
+
+- `v1.x`: Deprecated APIs are still supported, marked on type level only. With optional runtime warnings to opt-in.
+- 👉 `v2.0`: No breaking changes, but enable runtime deprecated warnings by default.
+- `v3.0`: Remove deprecated APIs, breaking changes.
+
+Expect v3.0.0 to be released soon after v2.0.0.
+
+## Deprecations
+
+We highly recommend you to migrate them sooner.
+
+### `getHighlighter` -> `createHighlighter`
+
+There is no functional changes, but more like correcting the naming to avoid confusion. It should be a straightforward find-and-replace.
+
+### WASM Related APIs
+
+Since the introduce of the [engine system](/guide/regex-engines) in v0.16, the WebAssembly related dependencies are no longer a hard requirement. To make tree-shaking easier and decoupled the engines with the core, two packages are extracted `@shikijs/engine-oniguruma` and `@shikijs/engine-javascript`. They are also re-exported from the main package's `shiki/engine/oniguruma` and `shiki/engine/javascript` respectively.
+
+You might need to change your import path:
+
+```ts
+import { loadWasm } from 'shiki' // [!code --]
+import { loadWasm } from 'shiki/engine/oniguruma' // [!code ++]
+```
+
+`loadWasm` field in `createHighlighterCore` is replaced with `engine` field:
+
+```ts
+import { createHighlighter } from 'shiki'
+import { createOnigurumaEngine } from 'shiki/engine/oniguruma' // [!code ++]
+
+const shiki = await createHighlighter({
+  // ...
+  loadWasm: () => import('shiki/wasm'), // [!code --]
+  engine: createOnigurumaEngine(() => import('shiki/wasm')), // [!code ++]
+})
+```
+
+### Shiki Compat
+
+The `@shikijs/compat` package that built for compatibility with v0.14 is now deprecated. Please migrate to the main package. This package will be removed in v3.0.
+
+### Transformers Matching Algorithm
+
+The `matchAlgorithm` option for transformers is introduced in v1.29.0 to allow users to choose the matching algorithm. The default value will be changed from `v1` to `v3` in v3.0.0. We recommend you to set the `matchAlgorithm` option explicitly to avoid breaking changes in the future.
+
+[Learn more](/packages/transformers#matching-algorithm).
+
+### Other Deprecations
+
+- `createdBundledHighlighter` requires a single object-style argument
+- `@shikijs/core`
+  - The regex engines `createJavaScriptRegexEngine` `createOnigurumaEngine` are no longer included, import them from `@shikijs/engine-oniguruma` and `@shikijs/engine-javascript` respectively
+  - `createHighlighterCore` now explicits requires an `engine` field to be passed
+  - `loadWasm` field in `createHighlighterCore` is replaced with `engine` field
+  - `@shikijs/core/wasm-inline` is replaced with `@shikijs/engine-oniguruma/wasm-inline`
+  - Import `FontStyle` and `StackElementMetadata` from `@shikijs/vscode-textmate` instead of `@shikijs/core`
+
+## Tweaking Warnings
+
+If you prepre hard errors instead of warnings, you can run the following code before using Shiki, the first argument decides if warnings should be enabled, the second argument decides if warnings should be thrown as errors:
+
+```ts
+import { enableDeprecationWarnings } from 'shiki/core'
+
+enableDeprecationWarnings(true, true) // enable warnings and throw errors
+
+// use crateHighlighter(...) etc. after that
+```
+
+### Disable Warnings
+
+If you want to disable the warnings:
+
+```ts
+import { enableDeprecationWarnings } from 'shiki/core'
+
+enableDeprecationWarnings(false)
+```
+
+## Feedback
+
+Any feedbacks are welcome! Feel free to open an issue on [GitHub](https://github.com/shikijs/shiki) and let us know your thoughts.
diff --git a/docs/guide/future.md b/docs/guide/future.md
diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md
@@ -4,13 +4,19 @@ outline: deep
 
 # Migration
 
+We suggest you to migrate step by step, following each version's migration guide.
+
+## Migrate from v1.0
+
+There is no hard breaking changes in v2.0, read [Shiki v2.0](/blog/v2) for more details.
+
+## Migrate from v0.14
+
 The v1.0 release of Shiki is a major rewrite that we took the chance to revise every design decision we made in the past. We originally had a separate package name as [Shikiji](https://github.com/antfu/shikiji) to experiment with the new design, now it's merged back to Shiki as v1.0.
 
 > [!TIP] Learn more
 > Interested in the story behind v1.0? Check out this [blog post](https://nuxt.com/blog/shiki-v1) for more details.
 
-## Migrate from v0.14
-
 Compare to [`shiki@0.14.3`](https://github.com/shikijs/shiki/releases/tag/v0.14.3), the list of breaking changes are:
 
 ### Hard Breaking Changes

diff --git a/packages/core/src/warn.ts b/packages/core/src/warn.ts
@@ -1,4 +1,4 @@
-let _emitDeprecation: DeprecationTarget | boolean = false
+let _emitDeprecation: DeprecationTarget | boolean = 3
 let _emitError = false
 
 export type DeprecationTarget = 3