Use rehype-code-group with Vocs
Vocs already includes polished code blocks and package-manager code groups. Add rehype-code-group when your content needs the package's framework-neutral HTML contract, arbitrary rich-content panels, explicit synchronization, or persisted choices.
Choose the right path
| Requirement | Recommended path |
|---|---|
| Package-manager or language snippets written directly in Vocs | Vocs native code groups |
| Generated Markdown or HTML consumed outside the Vocs page compiler | rehype-code-group unified pipeline |
| Rich panels containing prose, lists, and multiple code blocks | rehype-code-group rich-content groups |
| Tabs synchronized across separate previews | sync with the package browser client |
| A choice persisted in local storage or the URL | persist="local" or persist="url" |
Add a package preview
Keep the integration in a client component
Vocs pages can import React components from the documentation source tree. A small client boundary can initialize the browser behavior after hydration.
- CodeGroupEnhancer.tsximports the browser client
- CodeGroupPreview.tsxrenders the generated markup contract
- guide.mdximports the preview component
- vocs.config.ts
Load application-owned assets once
Use the public stylesheet in the preview component or your root stylesheet. Import the client from a client component so it only runs in the browser.
"use client";
import type React from "react";
import { useEffect } from "react";
export function CodeGroupEnhancer({ children }: { children: React.ReactNode }) {
useEffect(() => {
void import("rehype-code-group/client");
}, []);
return <>{children}</>;
}Import rehype-code-group/styles.css once from the preview component or the application stylesheet.
Render the stable HTML contract
Wrap markup produced by rehype-code-group with the enhancer. Keep the required roles, relationships, default classes, and data-rcg-value attributes intact so the browser client and stylesheet can enhance it.
import { PackageManagerPreview } from '../components/PackageManagerPreview.js'
<PackageManagerPreview />Process generated content
When another build step owns the Markdown transformation, run the remark helper before remark-rehype, then run the rehype plugin after the tree becomes HAST. Set assets: "none" because the Vocs application already imports the stylesheet and client.
import rehypeCodeGroup from "rehype-code-group";
import remarkCodeGroup from "rehype-code-group/remark";
import rehypeStringify from "rehype-stringify";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
export async function renderMarkdown(markdown: string) {
const file = await unified()
.use(remarkParse)
.use(remarkCodeGroup)
.use(remarkRehype)
.use(rehypeCodeGroup, { assets: "none" })
.use(rehypeStringify)
.process(markdown);
return String(file);
}Use Vocs features around previews
Keep surrounding documentation native to Vocs: use callouts for constraints, steps for installation flows, file trees for project structure, and cards for related guides. Vocs code blocks also provide titles, copy controls, focus annotations, diffs, and line numbers without extra package styling.
Read the official Vocs Markdown extensions and code highlighting guide for the complete authoring surface.