v1-migration.mdx

title	description	authors	date	draft
Migrating to Code Hike 1.0	Incremental adoption guide	pomber	2024-08-25	false

import { CodeWithNotes } from "@/components/code/code-with-notes"

If you were using Code Hike before v1 and want to migrate to the new version, this guide is for you. To learn more about the new features, read the v1 announcement post.

Code Hike v1 is different from the previous versions in many ways, so migrating won't be trivial. The good news is that the two version can coexist, so you can adopt the new version incrementally.

Installing v1 (without removing v0)

Since the new version of Code Hike is a different package, you can install it alongside the old one:

npm install codehike

Update your configuration file (depending on the framework, for example next.config.mjs for Next.js) to use the new package:

// codehike v0
import { remarkCodeHike } from "@code-hike/mdx"
// !diff(1:2) +
// codehike v1
import * as v1 from "codehike/mdx"

// !diff(1:4) +
/** @type {import('codehike/mdx').CodeHikeConfig} */
const chConfig = {
  syntaxHighlighting: { theme: "github-dark" },
}

const mdxOptions = {
  remarkPlugins: [
    // !diff +
    [v1.remarkCodeHike, chConfig],
    [remarkCodeHike, { theme: "github-dark", lineNumbers: false }],
  ],
  // !diff +
  recmaPlugins: [[v1.recmaCodeHike, chConfig]],
}

With this setup, you can start using the new features of v1 while keeping the old ones working with v0.

Migrating codeblocks and annotations

To avoid changing all your codeblocks at once, you can use the ignoreCode option to only use v1 for the codeblocks you want.

import { remarkCodeHike } from "@code-hike/mdx"
import * as v1 from "codehike/mdx"

/** @type {import('codehike/mdx').CodeHikeConfig} */
const chConfig = {
  syntaxHighlighting: { theme: "github-dark" },
  // !diff(1:2) +
  // !callout[/MyCode/] MyCode
  components: { code: "MyCode" },
  // !callout[/use-v1/] use-v1
  ignoreCode: ({ meta }) => !meta.startsWith("use-v1"),
}

const mdxOptions = {
  remarkPlugins: [
    [v1.remarkCodeHike, chConfig],
    [remarkCodeHike, { theme: "github-dark", lineNumbers: false }],
  ],
  recmaPlugins: [[v1.recmaCodeHike, chConfig]],
}

!!notes MyCode

In v1, you define your own component to render codeblocks

!!notes use-v1

Opt-in to v1 when the codeblock metastring starts with use-v1

In your MDX files, you can start adopting v1 by adding the use-v1 metastring to the codeblocks you want to migrate:

{/* prettier-ignore */}

# Hello world

```js
console.log("this is codehike v0")
```

{/* !mark[/use-v1/] */}
```js use-v1
console.log("this is codehike v1")
```

Instead of "use-v1", you can use any string. Just make sure it's easy to find and replace when you finish the migration.

Comparison table

Here's the equivalent features between v0 and v1, they aren't exactly the same, but they are similar:

	v0	v1
Docs	v0.codehike.org/docs	codehike.org/docs
Package name	@code-hike/mdx	codehike
Line numbers	Config	Example
Copy button	Config	Example
Themes	Config	Config
Skip languages	Config	Config
Static components	Config	Media queries
Auto import	Config	Not needed
Auto link	Config	Example
Codeblock filename	Directive	Example
focus	Annotation	Example
mark	Annotation	Example
withClass	Annotation	Example
link	Annotation	Example
from	Annotation	Syntax
<CH.Code> Tabs	Component	Example
<CH.Code> Panels	Component	-
Inline code	Syntax	Syntax
Code mentions	Syntax	Example
<CH.Scrollycoding>	Component	Example
<CH.Spotlight>	Component	Example
<CH.Slideshow>	Component	Example