Learn Shiki Rehype Pretty Code - Pre-Requisites Skills & Setup Environment

#Introduction

Welcome to the Learn Shiki Rehype Pretty Code series! This series will take you to mastery of Shiki and rehype-pretty-code — the combination that makes code blocks in blogs or MD/MDX documentation appear with editor-accurate syntax highlighting, complete with line highlighting, diff, title, caption, and much more. In total there are 23 episodes arranged across six phases.

But before touching these two libraries, there are some basic skills and software you must have. Why are these pre-requisites important? Because Shiki is not just a simple regex highlighter. It uses TextMate grammar and Oniguruma WASM to tokenize code — and rehype-pretty-code works inside the unified pipeline that builds an AST tree. If these concepts aren't clear yet, every following step will feel like a black box.

Episode 0 is your roadmap: we'll make sure the basic skills are in place, set up a content project, install shiki and rehype-pretty-code, then verify that the first pipeline runs. Once this episode is done, you can follow the entire series comfortably.

#Basic Skills You Must Master

#Node.js and Package Manager

Shiki and rehype-pretty-code are JavaScript packages that run on Node.js, so you must be comfortable with Node.js version 18 and above and at least one package manager: npm, bun, or pnpm. You also need to understand the basics of ESM (import and export), because both libraries are ESM-only.

node --version
npm --version

The output of node --version must show version 18 or newer. This series uses npm because it is the most universal, but every command can be mapped to bun or pnpm without any issues.

#Markdown, MDX, and the AST Concept

rehype-pretty-code works on Markdown and MDX files. You need to understand basic Markdown syntax such as headings, lists, links, and especially fenced code blocks. MDX adds the ability to write JSX components inside Markdown — this concept matters because several content frameworks (for example Next.js with @next/mdx) process MDX through the rehype pipeline.

Beyond that, you must understand the AST (Abstract Syntax Tree) concept. In the HTML world, this tree is called HAST. When remark parses Markdown, the result is an MDAST tree. remark-rehype converts it into HAST, then rehype plugins (including rehype-pretty-code) manipulate that tree before it becomes an HTML string.

#The unified, remark, and rehype Flow

The core of this entire series is the unified pipeline. The flow is always the same: parse → transform → stringify.

markdown → remark-parse → MDAST → remark-rehype → HAST → rehype plugins → rehype-stringify → HTML

Shiki works as the highlighting engine inside one of those rehype plugins, and rehype-pretty-code provides the layer that turns <pre> and <code> nodes into feature-rich <figure> elements. Understand this big picture before diving into code.

#Software to Prepare

#Minimal Content Project

You can follow this series with any project: Next.js MDX, Astro, VitePress, or a plain unified project like the one we build in episode 3. For episode 0, just create an empty project directory:

mkdir code-block-project
cd code-block-project
npm init -y

The npm init -y command creates a package.json with default configuration. You need to add "type": "module" so the project uses ESM — a required step because both libraries we use are ESM-only.

#Installing Shiki and rehype-pretty-code

With package.json ready, install the two main libraries:

npm install shiki rehype-pretty-code

This process also pulls in supporting dependencies such as @shikijs/engine-oniguruma which loads Oniguruma WASM, and the hast-util-* packages that rehype-pretty-code uses to manipulate HAST. Wait for it to finish, then verify the versions:

npm list shiki rehype-pretty-code

Make sure shiki is at version 4.x and rehype-pretty-code at version 0.14.x. The latest versions at the time of writing this series are Shiki v4.3.1 and rehype-pretty-code v0.14.4 — update if needed by running npm view shiki version to check the current version in the registry.

#Browser DevTools for Inspecting HTML Output

Most episodes in this series inspect the HTML output produced by the pipeline. Because rehype-pretty-code generates elements like <figure>, <pre>, <code>, and <span> with data attributes, you must be able to read browser devtools (the Elements tab in Chrome or Firefox). Open a page containing a code block, right-click on the code, choose Inspect, then look at attributes like data-line, data-highlighted-line, and data-rehype-pretty-code-figure. This habit will save you when debugging in episode 19.

#Verifying Your Environment

Before moving on to episode 1, run a quick verification by creating a check.mjs file in the project root:

First pipeline verification

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypePrettyCode from "rehype-pretty-code";
import rehypeStringify from "rehype-stringify";
 
const result = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypePrettyCode, { theme: "github-dark-default" })
  .use(rehypeStringify)
  .process("```ts\nconst x: number = 1;\n```");
 
console.log(String(result));

Run it with node check.mjs. If there are no errors and the output contains a <figure> tag with the data-rehype-pretty-code-figure attribute, your environment is ready. Important note: remark-parse, remark-rehype, and rehype-stringify must be installed first with npm install remark-parse remark-rehype rehype-stringify.

#Summary of Skills You Must Master

Here is a recap of the pre-requisites you've prepared in episode 0:

• Node.js 18+ with the habit of using a package manager and ESM.
• Markdown and MDX as the content formats that will be processed.
• The AST and HAST concepts as well as the parse, transform, stringify flow.
• shiki and rehype-pretty-code installed with the latest versions.
• unified, remark-parse, remark-rehype, rehype-stringify ready to use.
• Browser devtools as the tool for inspecting HTML output.

If anything is missing, stop and complete it before continuing. A strong foundation will make the remaining 22 episodes feel much lighter.

#Conclusion

Key takeaways:

• Shiki uses TextMate grammar, not simple regex: master the tokenization concept first.
• rehype-pretty-code works inside the AST-based unified pipeline.
• Both libraries are ESM-only: make sure the project uses import and export.
• First verification: install, run the minimal pipeline, and check the <figure> output.
• Browser devtools are the main weapon for understanding HTML output.

In episode 1 next, we'll cover history, background, and why the Shiki and rehype-pretty-code combination is needed — from the evolution of regex-based syntax highlighting, the birth of Shiki in 2018 by Pine Wu, to the birth of rehype-pretty-code in 2022 by Atomiks to fill the code block feature gap in the rehype pipeline. Make sure your environment is ready, because the Learn Shiki Rehype Pretty Code journey has just begun!