Rodrigo Pombo

@pomber

Announcing Code Hike 1.0

A new approach to turn markdown into rich interactive experiences

After a year of exploration and development, I’m thrilled to announce the stable release of Code Hike 1.0!

What is Code Hike?

Code Hike is an open-source library that bridges the gap between Markdown and React to help you create technical content that takes full advantage of the modern web.

While the main use cases are code walkthroughs and interactive documentation, Code Hike can be used for any combination of content and presentation. And since it's all React components, it can be rendered anywhere React can be rendered.

Code Hike 1.0 introduces two new features: fine-grained markdown and headless codeblocks.

Fine-grained Markdown

When using Markdown, the content often becomes an inflexible block of UI that limits your control over its rendering.

Code Hike allows you to break down your Markdown into smaller pieces, which can be rendered however you like using React. This is done by using special decorators in Markdown:

## !intro The Roman Emperors

The Roman Empire was one of the most influential empires in history.

It was marked by a series of powerful rulers known as emperors.

## !!emperors Augustus

The founder of the Roman Empire and its first Emperor.

![!img cover](/one.png)

```js !code
console.log(1)
```

## !!emperors Nero

Reigned from AD 54 to 68 and is one of the most infamous emperors in Roman history.

## !!emperors Trajan

The second of the Five Good Emperors, Trajan reigned from AD 98 to 117. He is remembered for his extensive public building programs and for expanding the empire to its greatest territorial extent.

import Content from "./content.md"
import { parse } from "codehike"
const content = parse(Content)
content = {
  intro: {
    title: "The Roman Emperors",
    children: <>
      <p>The Roman Empire was ...</p>
      <p>It was marked by ...</p>
    </>,
  },
  emperors: [
    {
      title: "Augustus",
      children: <p>The founder ...</p>,
      img: { src: "/one.png" },
      code: {
        lang: "js",
        value: "console.log(1)",
      },
    },
    { title: "Nero", ... },
    { title: "Trajan", ... },
  ],
}

function Page() {
  const { intro, emperors } = content
  return (
    <main>
      <h1>{intro.title}</h1>
      {intro.children}
      {emperors.map((emperor) => (
        <section>...</section>
      ))}
    </main>
  )
}

Code Hike also integrates nicely with Zod schemas, giving you type-safe Markdown.

Learn more:

• Documentation: Code Hike blocks
• Blog post: Fine-grained Markdown
• Example: SwiftUI tutorials clone

Headless Codeblocks

With Code Hike 1.0, you can build your own component library for codeblocks.

• Use React components to define UI and behaviors: tooltips, animations, line numbers, diffs, copy buttons, collapse, fold, footnotes, links, tabs, callouts, language switchers, or whatever you can imagine.
• Then add comments inside your codeblocks to make use of those components

```js
function sum(a, b) {
  return a + b
}

// !tooltip[/result/] 23
let result = sum("2", "3")
```

function sum(a, b) {
  return a + b
}

let result = sum("2", "3")

import { Pre, highlight } from "codehike/code"
import { Tooltip } from "./my-tooltip"

const tooltipHandler = {
  name: "tooltip",
  Inline: ({ annotation, children }) => (
    <Tooltip>
      <Tooltip.Trigger>{children}</Tooltip.Trigger>
      <Tooltip.Content>
        {annotation.query}
      </Tooltip.Content>
    </Tooltip>
  ),
}

export async function Code({ codeblock }) {
  const code = await highlight(codeblock, "dracula")
  return (
    <Pre code={code} handlers={[tooltipHandler]} />
  )
}

You don't have to start from scratch. There are plenty of examples to copy, paste, and adapt to your needs in the code examples page.

Learn more:

• Documentation: Code Blocks
• Documentation: Code Annotations
• Examples

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.

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.

Try Code Hike 1.0

Try it online on StackBlitz, or clone the Code Hike v1 starter:

npx create-next-app -e https://github.com/code-hike/v1-starter

If you were using a previous version of Code Hike, check the migration guide.

Supported frameworks

Code Hike depends on React and MDX, so any framework that supports those should work. These include Next.js, Remix, Docusaurus, Nextra, Fuma Docs, and more. One notable exception is Astro (because MDX is compiled to Astro components, not React).

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.

Find examples for various frameworks in the examples page.

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

Thank you!

Big thanks to all the sponsors, some of whom have been supporting Code Hike from the very beginning, when it was just an experiment.

Special thanks to the GitHub Accelerator for selecting Code Hike for the first cohort of the program. Their sponsorship and guidance have been a huge help in getting Code Hike to this point.

I'm excited about what’s next for Code Hike. You can become a sponsor to help us make it happen!