Installation

Code Hike is a remark plugin for MDX v2. The specific set up will depend on your stack, it usually involves five steps:

1. Set up MDX v2

2. Install the Code Hike plugin

3. Include Code Hike's CSS

4. Add the remark plugin to your MDX configuration

5. Copy and try one of the demos to test the set up.

Frameworks

Installation guides for specific frameworks. Pick one:

Next.js

Docusaurus

Next.js + Contentlayer

Next.js + MDX Bundler

Next MDX Remote

docs.page

Docusaurus + Code Hike

Docusaurus is a static-site generator with a focus on documentation sites.

Let's start by creating a new Docusaurus website inside the my-website directory with this command:


npx create-docusaurus@latest my-website classic

To use Code Hike we need to add these dependencies:


cd my-website
npm i @mdx-js/react@2 docusaurus-theme-mdx-v2 @code-hike/mdx

docusaurus.config.js


/** @type {import('@docusaurus/types').Config} */
const config = {
  presets: [
    // ...
  ],
  themes: ["mdx-v2"],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        // ...
      },
    }),
}
module.exports = config

MDX v2 theme

Code Hike requires MDX v2 but Docusaurus doesn't support it yet. That's why we are using the MDX v2 theme.

We've already added the dependency, now we need to add the theme to the docusaurus.config.js file with themes: ["mdx-v2"].

There may be a few Docusuaurus features that don't work with mdx v2 yet, make sure to check the known issues.

docusaurus.config.js


const {
  remarkCodeHike,
} = require("@code-hike/mdx")
/** @type {import('@docusaurus/types').Config} */
const config = {
  presets: [
    [
      "classic",
      {
        docs: {
          beforeDefaultRemarkPlugins: [
            [remarkCodeHike, { theme: "nord" }],
          ],
          sidebarPath: require.resolve("./sidebars.js"),
        },
      },
    ],
  ],
  themes: ["mdx-v2"],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        // ...
      },
    }),
};
module.exports = config;

Remark plugin

Now that Docusaurus can render MDX v2 we can add Code Hike to the docusaurus.config.js.

We need to import the remarkCodeHike function from the @code-hike/mdx package, and add it to the beforeDefaultRemarkPlugins array.

Next to the plugin you can pass a config object. Almost always you'll want to pass a theme there. For more information about themes, see the themes docs.

You can also pass more options, like lineNumbers for example. See the configuration docs for more information.

docusaurus.config.js


const {
  remarkCodeHike,
} = require("@code-hike/mdx")
/** @type {import('@docusaurus/types').Config} */
const config = {
  presets: [
    [
      "classic",
      {
        docs: {
          beforeDefaultRemarkPlugins: [
            [remarkCodeHike, { theme: "nord" }],
          ],
          sidebarPath: require.resolve("./sidebars.js"),
        },
        theme: {
          customCss: [
            require.resolve("@code-hike/mdx/styles.css"),
            require.resolve("./src/css/custom.css"),
          ],
        },
      },
    ],
  ],
  themes: ["mdx-v2"],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        // ...
      },
    }),
};
module.exports = config;

Styles

Then we need to import Code Hike's stylesheet.

There's a customCSS property in the theme config. You can replace it with an array and add Code Hike's stylesheet to it.

If you want to customize Code Hike's styles with a global stylesheet make sure to import it after this import to avoid specificity issues.

You can learn more about customizing Code Hike styles in the styling docs.

docusaurus.config.js

blog/2019-05-29-long-blog-post.md


---
slug: long-blog-post
title: Long Blog Post
authors: endi
tags: [hello, docusaurus]
---
This is the summary of a very long blog post,
Use a comment to limit blog post size in the list view.
<!--truncate-->
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Pellentesque elementum dignissim ultricies. Fusce rhoncus
ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Pellentesque elementum dignissim ultricies. Fusce rhoncus
ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

MDX v2 breaking changes

MDX v2 has some breaking changes in the syntax. So if you already have content using mdx v1 make sure to migrate to the new syntax. You can find the migration guide on the mdx website.

If you are following this guide with the Docusaurus template the only change we need to make is one comment in the blog post 2019-05-29-long-blog-post.md.

Change it from  to {/* truncate */}.

docusaurus.config.js

blog/2019-05-29-long-blog-post.md

docs/intro.md


---
sidebar_position: 1
---
### Lorem ipsum
```python hello.py
# mark[16:24]
print("This is Code Hike")
```
Lorem ipsum dolor sit amet.

Now go and edit a page and add some Code Hike components.

For example, let's replace the markdown in docs/intro.md.

If you run the website (with npm run start) and go to localhost:3000/docs/intro you should see the Code Hike components rendered:

You can find more things to try on the demos page.

MDX v2 theme

Code Hike requires MDX v2 but Docusaurus doesn't support it yet. That's why we are using the MDX v2 theme.

We've already added the dependency, now we need to add the theme to the docusaurus.config.js file with themes: ["mdx-v2"].

There may be a few Docusuaurus features that don't work with mdx v2 yet, make sure to check the known issues.

Remark plugin

Now that Docusaurus can render MDX v2 we can add Code Hike to the docusaurus.config.js.

We need to import the remarkCodeHike function from the @code-hike/mdx package, and add it to the beforeDefaultRemarkPlugins array.

Next to the plugin you can pass a config object. Almost always you'll want to pass a theme there. For more information about themes, see the themes docs.

You can also pass more options, like lineNumbers for example. See the configuration docs for more information.

Styles

Then we need to import Code Hike's stylesheet.

There's a customCSS property in the theme config. You can replace it with an array and add Code Hike's stylesheet to it.

If you want to customize Code Hike's styles with a global stylesheet make sure to import it after this import to avoid specificity issues.

You can learn more about customizing Code Hike styles in the styling docs.

MDX v2 breaking changes

MDX v2 has some breaking changes in the syntax. So if you already have content using mdx v1 make sure to migrate to the new syntax. You can find the migration guide on the mdx website.

If you are following this guide with the Docusaurus template the only change we need to make is one comment in the blog post 2019-05-29-long-blog-post.md.

Change it from  to {/* truncate */}.

Now go and edit a page and add some Code Hike components.

For example, let's replace the markdown in docs/intro.md.

If you run the website (with npm run start) and go to localhost:3000/docs/intro you should see the Code Hike components rendered:

You can find more things to try on the demos page.

docusaurus.config.js


/** @type {import('@docusaurus/types').Config} */
const config = {
  presets: [
    // ...
  ],
  themes: ["mdx-v2"],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        // ...
      },
    }),
}
module.exports = config

A demo of Code Hike + Docusaurus is available on GitHub. You can also try it out from your browser on StackBlitz.