repository·master·Indexed 23 days ago
https://github.com/rehype-pretty/rehype-pretty-codeA rehype plugin that provides high-quality, syntax-highlighted code block rendering for MD and MDX documentation. It integrates with Shiki and unified to support features such as line and character highlighting via meta strings, inline code highlighting, custom titles, captions, and CSS-based line numbers. The ecosystem includes @rehype-pretty/transformers for adding functionality like a customizable copy button.
You can add metadata to code blocks using the title and caption keys in the meta string.
```js title="filename.js"```js caption="A description"You can control highlighting directly in Markdown code block fences using meta strings:
Use {} to specify a numeric range.
```js {1-3,4} highlights lines 1 through 3, and line 4.data-highlighted-line attribute.# after the range to assign an ID: ```js {1,2}#a {3,4}#b.data-highlighted-line-id="<id>".Use / or " as delimiters.
```js /carrot/ highlights the word 'carrot'.```js /carrot/3-5 highlights the 3rd through 5th instances of 'carrot'.data-highlighted-chars attribute.# after the delimiter: ```js /age/#v.data-chars-id="<id>".Use special syntax to highlight code within text:
Append {:lang} to the end of inline code to apply language highlighting.
`[1, 2, 3]{:js}`Append {: .token.name} to highlight text based on specific VS Code theme tokens.
`getStringLength{:.entity.name.function}`tokensMap in the plugin options to create aliases (e.g., fn: "entity.name.function"), allowing you to use `getStringLength{:.fn}`.Highlight specific words or character sequences using / or " delimiters in the meta string.
```js /carrot/
```You can highlight multiple segments or specify a range of occurrences (e.g., 3-5 for the 3rd to 5th instance).
```js /carrot/3-5 /apple/
```Use # after the delimiter to assign an ID.
```js /age/#v /name/#v
const [age, setName] = useState(50);
```Styling: The characters receive a data-chars-id="<id>" attribute.
Highlighted characters receive a data-highlighted-chars attribute.
To support dual themes, pass an object to the theme option where keys represent the color mode (e.g., dark, light).
When multiple themes are provided, the <code> and <pre> elements will have a data-theme attribute containing a space-separated list of the theme names (e.g., data-theme="github-dark-dimmed github-light").
You can then use CSS to switch colors based on the prefers-color-scheme media query or by targeting the data-theme attribute.
const options = {
theme: {
dark: "github-dark-dimmed",
light: "github-light",
},
};The library is unstyled, but it provides attributes to help you implement line numbers via CSS counters.
showLineNumbers meta string to enable them: ```js showLineNumbers.```js showLineNumbers{5}.<code> element will receive data-line-numbers and data-line-numbers-max-digits="n" attributes.Example CSS Implementation:
code[data-line-numbers] {
counter-reset: line;
}
code[data-line-numbers] > [data-line]::before {
counter-increment: line;
content: counter(line);
display: inline-block;
width: 0.75rem;
margin-right: 2rem;
text-align: right;
color: gray;
}code[data-line-numbers] {
counter-reset: line;
}
code[data-line-numbers] > [data-line]::before {
counter-increment: line;
content: counter(line);
display: inline-block;
width: 0.75rem;
margin-right: 2rem;
text-align: right;
color: gray;
}
code[data-line-numbers-max-digits="2"] > [data-line]::before {
width: 1.25rem;
}You can use rehype-pretty-code within React Server Components (RSC) by processing the code string through a unified pipeline.
Implementation Steps:
unified, remark-parse, remark-rehype, rehype-pretty-code, and rehype-stringify to process the code.dangerouslySetInnerHTML to render the result in your component.Example Component:
import * as React from "react";
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypePrettyCode from "rehype-pretty-code";
export async function Code({ code }: { code: string }) {
const highlightedCode = await highlightCode(code);
return (
<section
dangerouslySetInnerHTML={{
__html: highlightedCode,
}}
/>
);
}
async function highlightCode(code: string) {
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypePrettyCode, {
keepBackground: false,
})
.use(rehypeStringify)
.process(code);
return String(file);
}Rehype Pretty Code provides specific integration examples for several popular web frameworks and environments. You can explore these examples to see how to set up the plugin in your specific stack:
index.html example using CDN-based integration.You can use rehype-pretty-code within React Server Components by processing the code string through a unified pipeline.
unified, remark-parse, remark-rehype, rehype-pretty-code, and rehype-stringify to process the code.dangerouslySetInnerHTML.import * as React from "react";
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypePrettyCode from "rehype-pretty-code";
export async function Code({ code }: { code: string }) {
const highlightedCode = await highlightCode(code);
return (
<section
dangerouslySetInnerHTML={{
__html: highlightedCode,
}}
/>
);
}
async function highlightCode(code: string) {
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypePrettyCode, {
keepBackground: false,
})
.use(rehypeStringify)
.process(code);
return String(file);
}import * as React from "react";
import { Code } from "./code.tsx";
export default async function Page() {
return (
<main>
<Code code="`const numbers = [1, 2, 3]{:js}`" />
</main>
);
}Install the package and its required dependency shiki using your preferred package manager. Note that this package is ESM-only and requires shiki version ^1.0.0.
npm install rehype-pretty-code shiki
# or
pnpm add rehype-pretty-code shiki
# or
bun add rehype-pretty-code shiki
# or
yarn add rehype-pretty-code shikiTo use the Copy Button transformer, install the @rehype-pretty/transformers package using your preferred package manager.
npm install @rehype-pretty/transformers