Split the Shiki highlighter from the plain token helpers

[nolannbiron]

ClientCodeBlock imports plain-highlight.ts, which pulled getHighlightTokensText, parseDiffNotation and truncateHighlightTokens from highlight.ts. That module imports shiki/core, shiki/engine/javascript, shiki/langs and shiki/themes, so the whole Shiki bundle landed in the initial client payload of every docs page — defeating the lazy import('./highlight') that ClientCodeBlock already does.

The token and plain-text helpers need no Shiki values (the shiki/core imports they use are types, erased at build), so they move to highlight-tokens.ts. highlight.ts keeps the highlighter itself and re-exports the helpers, so existing importers are unchanged. This also breaks the highlight.ts ↔ plain-highlight.ts import cycle.

Initial client JS for the docs route (/sites/static/[mode]/[siteURL]/[siteData]/(content)/[pagePath]), measured on a production build:

main	1797.2 KB
this branch	1616.3 KB
	−180.9 KB (−10.1%)

Sizes are minified and uncompressed on disk; over the wire the saving is roughly a third of that.

First of several changes coming out of the Lighthouse audit in DOCS-6253, where a docs page executes ~9.1 s of JavaScript on a mid-range phone.

[changeset-bot]

🦋 Changeset detected

Latest commit: 182087c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
gitbook	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Summary of the deployments:

Version	URL	Status
Vercel	https://gitbook-v2-7vwze2ry9-gitbook.vercel.app	✅
Cloudflare	https://b1fd40a4-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-7vwze2ry9-gitbook.vercel.app/url/gitbook.com/docs	https://b1fd40a4-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-7vwze2ry9-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://b1fd40a4-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.gitbook.io/test-gitbook-open

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
customers-v2-cloudflare (Inspect)	👍 Approved by Nolann Biron	39 changed, 6 ignored	Aug 5, 2026, 2:33 PM
customers-v2-vercel (Inspect)	👍 Approved by Nolann Biron	13 changed, 31 ignored	Aug 5, 2026, 2:30 PM
v2-cloudflare (Inspect)	👍 Approved by Nolann Biron	8 changed, 4 ignored	Aug 5, 2026, 2:34 PM
v2-vercel (Inspect)	👍 Approved by Nolann Biron	8 changed, 1 ignored	Aug 5, 2026, 2:32 PM