Getting Started
[01] Getting Started
Markdown Rendering
Render Markdown as VaneUI components with @vaneui/md: use Md in server and client components, place components with vaneui fences, restyle each element, and handle untrusted content.
@vaneui/md renders a Markdown string as VaneUI components: a heading becomes Title, a paragraph Text, a list List, a quote or a code block Card, inline code Code, a table Table, a link Link and an image Img. The source is parsed with Markdoc. Unlike MDX it holds no JSX and no imports, so a document is data and cannot run code.
Install the package and render a string
@vaneui/md needs @vaneui/ui 1.5.0 or later, set up as on the Installation page:
npm install @vaneui/mdPass the Markdown source as content:
import { Md } from '@vaneui/md';
const source = `# Release notes
The **1.6.0** release adds nine import paths.
- Faster builds- Smaller bundles
> Upgrade with \`npm install @vaneui/ui@latest\`.`;
export function ReleaseNotes() { return <Md content={source} />;}The output takes its colors and sizes from the nearest ThemeProvider, like any other VaneUI component. For the spacing between blocks, add the package's stylesheet to your CSS entry, after the VaneUI imports:
@import "@vaneui/md/styles";It holds spacing rules for the rendered document and nothing else.
Server Components and the client entry
Md from @vaneui/md uses no React context and no hooks, so it renders inside a React Server Component. Markdown known at build time is parsed on the server, and the parser stays out of the browser bundle:
// app/blog/[slug]/page.tsx: a Server Componentimport { Md } from '@vaneui/md';
export default async function Post({ params }: { params: Promise<{ slug: string }> }) { const content = await loadPost((await params).slug); return <Md content={content} />;}@vaneui/md/client is the client entry. It exports MdStream for text that grows while it is shown, such as a model's answer, and takes the same props as Md:
'use client';
import { MdStream } from '@vaneui/md/client';
export function Answer({ text }: { text: string }) { return <MdStream content={text} />;}On each update MdStream renders again only the blocks whose content changed, so finished paragraphs and code blocks keep their DOM nodes.
Frontmatter values inside the document
Md reads the YAML block at the top of a document when you pass a parser. parseYamlFrontmatter needs the yaml package (npm install yaml):
import { Md } from '@vaneui/md';import { parseYamlFrontmatter } from '@vaneui/md/yaml';
<Md content={source} parseFrontmatter={parseYamlFrontmatter} />The parsed values are available in the document as $markdoc.frontmatter:
---title: Get startedauthor: Jane---
# {% $markdoc.frontmatter.title %}
By {% $markdoc.frontmatter.author %}.Data you already hold goes in the frontmatter prop, which wins over the parser: <Md content={source} frontmatter={{ title: 'Get started' }} />.
VaneUI components inside Markdown with vaneui fences
A code block with the language vaneui is read as YAML and rendered as a component tree at that spot. The key holds the component name and its boolean props. A string value becomes the children, a list becomes child components, and a map sets other props:
```vaneuiCard primary filled: - Title lg: Welcome - Text: Everything you need to ship.```
```vaneuiButton filled: href: /get-started text: Get started```The fence needs two props on Md: the YAML parser and a registry that maps names to components.
import { Md } from '@vaneui/md';import { parseYamlFrontmatter } from '@vaneui/md/yaml';import { defaultRegistry } from '@vaneui/md/registry';
<Md content={source} parseFrontmatter={parseYamlFrontmatter} components={defaultRegistry}/>defaultRegistry lists the presentational components and leaves out the ones that need callbacks, such as Modal, Menu and Input. A name that is not in the registry renders nothing. Pass your own map to add components or to narrow the set.
Restyle one Markdown element with rendererTheme
Each Markdown element has a slot in rendererTheme that takes VaneUI boolean props. A slot changes that element only, so quotes and code blocks can differ although both render a Card:
<Md content={source} rendererTheme={{ mdBlockquote: { info: true }, mdCode: { success: true }, mdHeading: { fontMono: true }, }}/>The slots are named after the element: mdHeading, mdParagraph, mdLink, mdList, mdItem, mdBlockquote, mdCode for inline code, mdFence for code blocks, mdTable, mdImage and mdHr. A change for every Card in the app, in Markdown and outside it, belongs in themeDefaults on ThemeProvider.
To replace an element's component, pass your own in config.components:
import type { ReactNode } from 'react';import { Md } from '@vaneui/md';import { Link } from '@vaneui/ui';
// Links to other sites open in a new tabfunction DocLink({ href, children }: { href?: string; children?: ReactNode }) { return <Link href={href} external={href?.startsWith('http')}>{children}</Link>;}
<Md content={source} config={{ components: { MdLink: DocLink } }} />Syntax highlighting in code blocks
A code block renders as plain text until Md gets a highlight function. Two adapters ship with the package. The Prism one needs npm install prism-react-renderer:
import { Md } from '@vaneui/md';import { prismHighlighter } from '@vaneui/md/prism';
const highlight = prismHighlighter();
<Md content={source} highlight={highlight} />@vaneui/md/shiki exports shikiHighlighter, which takes the languages and themes you import from shiki. Any function of the shape (code, language) => ReactNode works as a custom highlighter. Create the function once, outside the component, so MdStream does not highlight unchanged blocks again.
Content shared between documents
A partial is a named snippet that Md receives in config.partials and a document places with the partial tag. It can take variables:
const partials = { 'support.md': 'Questions? Write to **{% $channel %}**.',};
<Md content={'# Setup\n\n{% partial file="support.md" variables={channel: "#help"} /%}'} config={{ partials }}/>To pull in another file by path, expand the document's include tags before rendering. resolveIncludes reads from the file system, so it runs on the server or in a build step:
import { readFileSync } from 'node:fs';import { Md } from '@vaneui/md';import { resolveIncludes } from '@vaneui/md/include';
const filePath = 'docs/guide/page.md';const content = resolveIncludes(readFileSync(filePath, 'utf8'), { filePath, root: 'docs',});
<Md content={content} />An include must stay inside root and, by default, point at a .md, .mdoc or .markdown file.
Markdown written by users or by a model
Content from outside your team gets two settings. untrustedPreset limits vaneui fences to VaneUI's boolean props, text and a short list of attributes such as href and alt, with http:, https:, mailto:, tel: and relative URLs only. tagSyntax={false} leaves {% ... %} in the text as written, so the content cannot use tags, variables or partials:
import { Md, untrustedPreset } from '@vaneui/md';import { parseYamlFrontmatter } from '@vaneui/md/yaml';import { defaultRegistry } from '@vaneui/md/registry';
<Md content={userMarkdown} presets={[untrustedPreset]} tagSyntax={false} parseFrontmatter={parseYamlFrontmatter} components={defaultRegistry}/>Without the preset a fence still cannot run script: event handlers, dangerouslySetInnerHTML, javascript: URLs and elements such as script and iframe are dropped at every level. The package's README lists every prop, the sanitize policy fields and the include options.