Installation
Code Hike is a remark plugin for MDX v2. The specific set up will depend on your stack, it usually involves five steps:
Frameworks
Installation guides for specific frameworks. Pick one:
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-websitenpm i @mdx-js/react@2 docusaurus-theme-mdx-v2 @code-hike/mdx
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 <!--truncate-->
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.
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 <!--truncate-->
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.
A demo of Code Hike + Docusaurus is available on GitHub. You can also try it out from your browser on StackBlitz.