Getting Started

Quick start

Start from a template with Next.js, MDX, Tailwind CSS:

Or try it online on StackBlitz or CodeSandbox.

For more complete starters, see the examples page.

For manual installation, see below.

Slow start

Why Code Hike?

Code Hike gives structure to markdown, turning it into a powerful base for creating interactive user interfaces. By integrating deeply with React, it allows you to show content tailored for the modern web.

Who is it for?

The main use cases are code walkthroughs, tutorials, and documentation. But it can be used for much more.

Big docs

If the people building your docs design system aren't the same as the ones writing the content, this is for you. Code Hike helps you build modern layouts, components, and codeblocks; all while keeping the authoring experience of markdown. Type-safe Stripe-level docs UI? We got you covered.

Small docs and blogs

If you are a solo developer or a small team, Code Hike makes your content flexible so you can use your creativity and the whole power of React to present it in the most engaging way.

Content creators

Videos, slides, screenshots. Code Hike makes separating content from presentation easy. Build the perfect style for your content using React, and reuse it across all your platforms. Did you know you can use Code Hike with Remotion?

Any content website

Landing pages, marketing sites, portfolios. It doesn't even need content related to programming. Code Hike helps you keep the content separated from the design.

See the examples for inspiration.

How?

Code Hike uses MDX plugins to transform markdown content into objects. You can then access these objects in React Components and present the content with all the flexibility that React provides.

For codeblocks, Code Hike provides a highlight function that not only applies syntax highlighting but also extract annotations from code comments. The result can be passed to a Pre component provided by Code Hike. You can write your own React Server Components to handle those annotations, giving you again all the power of React to display code.

The docs provide a variety of examples, both for layouts and code annotations, that you can copy, paste and adapt to your needs.

Tech stack

React and MDX are required.

Zod is highly recommended for schema validation.

A framework supporting React Server Components is recommended, but not required.

Astro is not suppoted.

Examples from the docs use Tailwind CSS, but it's not required.

My recommendation for documentation sites is Next.js + Fuma Docs, because of its support of React Server Components. RSCs aren't required for Code Hike, but having components that only run at build-time gives you extra power and flexibility.

For examples using various frameworks, see the examples.

Comparison with other tools

MDX: Code Hike is built on top of MDX.

Markdoc: Markdoc is another extension to Markdown. The main differences are:

  • Fine-grained markdown: similar to Code Hike, Markdoc lets you add some structure to Markdown, allowing more flexibility in how the content is rendered. Markdoc's approach is lower level, so an integration with Code Hike is something to explore in the future.
  • Code blocks: you can combine Code Hike and Markdoc by using Code Hike's highlight function instead of prismjs in Markdoc's syntax highlighting example.

Shiki: A syntax highlighter that includes transformers to customize codeblocks. Code Hike uses it's own highlighter. The main difference between the highlighters is that Shiki transformers are used to transform the AST (abstract syntax tree) of the codebock, while Code Hike annotations are React components.

Docusaurus, Nextra, Fuma Docs: These are frameworks that help you build documentation sites, handling Markdown/MDX files and providing some UI components. You can use Code Hike on top of them. There is an overlap in how to handle codeblocks, but you can incrementally let Code Hike take over using the ignoreCode config

Manual Installation

  1. Make sure you already have a set up with a framework that handles MDX files (for Next.js you can follow this guide).

  2. Install Code Hike:

npm install codehike
  1. Set up MDX plugins:
next.config.mjs
import { remarkCodeHike, recmaCodeHike } from "codehike/mdx"



/** @type {import('codehike/mdx').CodeHikeConfig} */

const chConfig = {

  // optional (see code docs):

  components: { code: "Code" },

  // if you can't use RSC:

  // syntaxHighlighting: {

  //   theme: "github-dark",

  // },

}



const mdxOptions = {

  remarkPlugins: [[remarkCodeHike, chConfig]],

  recmaPlugins: [[recmaCodeHike, chConfig]],

  jsx: true,

}
  1. Try the examples from the blocks page.

Blocks