From 9868339b2070bdbe0fd4ee9a0450a935feb76b34 Mon Sep 17 00:00:00 2001 From: Anthony Fu Date: Mon, 20 Jan 2025 16:21:32 +0800 Subject: [PATCH] feat!: enable runtime warning by default, v2 release blog post (#898) --- docs/.vitepress/config.ts | 16 ++++-- docs/blog/v2.md | 116 ++++++++++++++++++++++++++++++++++++++ docs/guide/future.md | 53 ----------------- docs/guide/migrate.md | 10 +++- packages/core/src/warn.ts | 2 +- 5 files changed, 136 insertions(+), 61 deletions(-) create mode 100644 docs/blog/v2.md delete mode 100644 docs/guide/future.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 514fdbc47..058e03dfb 100644 --- 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 new file mode 100644 index 000000000..5e7657844 --- /dev/null +++ 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 deleted file mode 100644 index 5d1f4829a..000000000 --- a/docs/guide/future.md +++ /dev/null @@ -1,53 +0,0 @@ -# Future - -We planned to remove some deprecated APIs and optimize the tree-shaking in the future major versions. - -The plan is: - -- 👉 `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. - -At the current version, since v1.19.0, you can opt-in to the runtime warnings by calling `enableDeprecationWarnings()` at the beginning of your application. - -```ts -import { enableDeprecationWarnings, getHighlighter } from 'shiki' - -enableDeprecationWarnings() // [!code hl] - -// Then calling deprecated usages like below would warn: -// [SHIKI DEPRECATED]: Use `createHighlighter` instead -const shiki = await getHighlighter(/* ... */) -``` - -This would help you better prepare for the future changes and upgrade smoothly. - -## Notable Deprecations - -### `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 `getHighlighter` 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 ++] -}) -``` diff --git a/docs/guide/migrate.md b/docs/guide/migrate.md index b5fa9c418..8b4dc0c54 100644 --- 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 index 0887a44da..871ef1b65 100644 --- 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