Update docs

haydenbleasel · haydenbleasel · commit ff390bb11460 · 2026-03-03T15:43:20.000-08:00
diff --git a/apps/website/content/docs/code-blocks.mdx b/apps/website/content/docs/code-blocks.mdx
@@ -143,6 +143,44 @@ Streamdown supports all Shiki themes including:
 - `tokyo-night`, `slack-dark`, `slack-ochin`
 - And [many more](https://shiki.style/themes)
 
+### Custom theme objects
+
+The `shikiTheme` prop accepts `[ThemeInput, ThemeInput]` where `ThemeInput` is either a bundled theme name (`BundledTheme`) or a custom theme object (`ThemeRegistrationAny`). You can mix and match:
+
+```tsx title="app/page.tsx"
+import { Streamdown } from "streamdown";
+import { code } from "@streamdown/code";
+import myCustomDarkTheme from "./my-dark-theme.json";
+
+export default function Page() {
+  return (
+    <Streamdown
+      plugins={{ code: code }}
+      shikiTheme={["github-light", myCustomDarkTheme]}
+    >
+      {markdown}
+    </Streamdown>
+  );
+}
+```
+
+<Callout type="info">
+  Bundled theme names (strings) load from Shiki's built-in registry. Custom theme objects follow the `ThemeRegistrationAny` format from Shiki — any VS Code `.tmTheme` or JSON theme file works.
+</Callout>
+
+## Custom start line
+
+Set the starting line number for a code block using `startLine=N` in the code fence meta:
+
+````markdown
+```typescript startLine=10
+const user = await getUser(id);
+const profile = await getProfile(user);
+```
+````
+
+Line numbers begin at the value you specify instead of 1. The value must be a positive integer (>= 1).
+
 ## Interactive Features
 
 ### Copy Button
diff --git a/apps/website/content/docs/components.mdx b/apps/website/content/docs/components.mdx
@@ -306,6 +306,32 @@ Use `data*` in the attributes array to allow all `data-*` attributes on a tag:
   If you provide custom `rehypePlugins`, you'll need to configure `rehype-sanitize` yourself to allow custom tags. See the [Security](/docs/security) documentation for details.
 </Callout>
 
+### Plain text tag content
+
+By default, children of custom HTML tags are parsed as markdown. This means underscores, asterisks, and other markdown metacharacters in tag content get formatted unexpectedly — for example, `<mention>some_user_name</mention>` renders with italicized text instead of a literal underscore.
+
+Use the `literalTagContent` prop to treat the children of specific tags as plain text:
+
+```tsx title="app/page.tsx"
+<Streamdown
+  allowedTags={{
+    mention: ["user_id"],
+  }}
+  literalTagContent={["mention"]}
+  components={{
+    mention: ({ user_id, children }) => (
+      <span className="text-blue-600">@{children}</span>
+    ),
+  }}
+>
+  {markdown}
+</Streamdown>
+```
+
+<Callout type="warn">
+  Tags listed in `literalTagContent` must also be listed in `allowedTags`. Otherwise the tag is stripped by the sanitizer before literal content handling applies.
+</Callout>
+
 ### Security Considerations
 
 When allowing custom HTML tags:
diff --git a/apps/website/content/docs/configuration.mdx b/apps/website/content/docs/configuration.mdx
@@ -52,6 +52,11 @@ Streamdown can be configured to suit your needs. This guide will walk you throug
       default: "streaming",
       options: ["streaming", "static"],
     },
+    dir: {
+      description:
+        "Text direction. 'auto' detects per-block using the first strong character algorithm.",
+      type: '"auto" | "ltr" | "rtl"',
+    },
   }}
 />
 
@@ -61,8 +66,8 @@ Streamdown can be configured to suit your needs. This guide will walk you throug
   type={{
     shikiTheme: {
       description:
-        "Light and dark themes for code syntax highlighting. Any Shiki theme name can be used - bundled themes (github-light, github-dark) load instantly, others load from CDN.",
-      type: "[string, string]",
+        "Light and dark themes for code syntax highlighting. Accepts bundled theme names or custom theme objects (ThemeRegistrationAny).",
+      type: "[ThemeInput, ThemeInput]",
       default: "['github-light', 'github-dark']",
     },
     components: {
@@ -74,6 +79,16 @@ Streamdown can be configured to suit your needs. This guide will walk you throug
         "Custom HTML tags to allow through sanitization, with their permitted attributes. Use with 'components' to render custom tags like <ref> or <mention>. Only works with default rehype plugins.",
       type: "Record<string, string[]>",
     },
+    literalTagContent: {
+      description:
+        "Tags whose children are treated as plain text (no markdown parsing). Useful when tag children contain underscores or asterisks that would otherwise be formatted. Tags must also appear in allowedTags.",
+      type: "string[]",
+    },
+    prefix: {
+      description:
+        "Tailwind CSS prefix prepended to all utility classes. Enables Tailwind v4 prefix() support. User-supplied className values are also prefixed.",
+      type: "string",
+    },
   }}
 />
 
@@ -132,6 +147,16 @@ Math rendering and CJK support require installing separate plugins. See [Mathema
       description: "Plugin configuration for math, mermaid, code highlighting, and CJK support. See [Plugins](/docs/plugins).",
       type: "PluginConfig",
     },
+    icons: {
+      description:
+        "Custom icons to override the defaults used in controls. See the IconMap interface for available keys.",
+      type: "Partial<IconMap>",
+    },
+    translations: {
+      description:
+        "Override default English labels for controls and modals. See [Internationalization](/docs/internationalization).",
+      type: "Partial<StreamdownTranslations>",
+    },
     caret: {
       description: "Show a caret indicator at the end of streaming content. See [Carets](/docs/carets).",
       type: '"block" | "circle"',
diff --git a/apps/website/content/docs/internationalization.mdx b/apps/website/content/docs/internationalization.mdx
@@ -0,0 +1,253 @@
+---
+title: Internationalization
+description: Override default English labels with your own translations.
+type: reference
+summary: Localize all UI labels in Streamdown controls and modals.
+prerequisites:
+  - /docs/getting-started
+related:
+  - /docs/configuration
+  - /docs/interactivity
+---
+
+Streamdown ships with English labels for all interactive controls — copy buttons, download menus, link modals, and more. Override any label via the `translations` prop.
+
+## Basic usage
+
+Pass a partial translations object to replace specific labels:
+
+```tsx title="app/page.tsx"
+<Streamdown
+  translations={{
+    copyCode: "Copiar código",
+    close: "Cerrar",
+    openLink: "Abrir enlace",
+    downloadImage: "Descargar imagen",
+  }}
+>
+  {markdown}
+</Streamdown>
+```
+
+## Available translation keys
+
+### Code block
+
+<TypeTable
+  type={{
+    copyCode: {
+      description: "Tooltip for the code copy button",
+      type: "string",
+      default: '"Copy Code"',
+    },
+    downloadFile: {
+      description: "Tooltip for the file download button",
+      type: "string",
+      default: '"Download file"',
+    },
+  }}
+/>
+
+### Mermaid diagrams
+
+<TypeTable
+  type={{
+    downloadDiagram: {
+      description: "Label for the diagram download button",
+      type: "string",
+      default: '"Download diagram"',
+    },
+    downloadDiagramAsSvg: {
+      description: "Download diagram as SVG option",
+      type: "string",
+      default: '"Download diagram as SVG"',
+    },
+    downloadDiagramAsPng: {
+      description: "Download diagram as PNG option",
+      type: "string",
+      default: '"Download diagram as PNG"',
+    },
+    downloadDiagramAsMmd: {
+      description: "Download diagram as MMD option",
+      type: "string",
+      default: '"Download diagram as MMD"',
+    },
+    viewFullscreen: {
+      description: "Toggle fullscreen button label",
+      type: "string",
+      default: '"View fullscreen"',
+    },
+    exitFullscreen: {
+      description: "Exit fullscreen button label",
+      type: "string",
+      default: '"Exit fullscreen"',
+    },
+    mermaidFormatSvg: {
+      description: "Short format label for SVG",
+      type: "string",
+      default: '"SVG"',
+    },
+    mermaidFormatPng: {
+      description: "Short format label for PNG",
+      type: "string",
+      default: '"PNG"',
+    },
+    mermaidFormatMmd: {
+      description: "Short format label for MMD",
+      type: "string",
+      default: '"MMD"',
+    },
+  }}
+/>
+
+### Table
+
+<TypeTable
+  type={{
+    copyTable: {
+      description: "Label for the table copy button",
+      type: "string",
+      default: '"Copy table"',
+    },
+    copyTableAsMarkdown: {
+      description: "Copy as Markdown option",
+      type: "string",
+      default: '"Copy table as Markdown"',
+    },
+    copyTableAsCsv: {
+      description: "Copy as CSV option",
+      type: "string",
+      default: '"Copy table as CSV"',
+    },
+    copyTableAsTsv: {
+      description: "Copy as TSV option",
+      type: "string",
+      default: '"Copy table as TSV"',
+    },
+    downloadTable: {
+      description: "Label for the table download button",
+      type: "string",
+      default: '"Download table"',
+    },
+    downloadTableAsCsv: {
+      description: "Download table as CSV option",
+      type: "string",
+      default: '"Download table as CSV"',
+    },
+    downloadTableAsMarkdown: {
+      description: "Download table as Markdown option",
+      type: "string",
+      default: '"Download table as Markdown"',
+    },
+    tableFormatMarkdown: {
+      description: "Short format label for Markdown",
+      type: "string",
+      default: '"Markdown"',
+    },
+    tableFormatCsv: {
+      description: "Short format label for CSV",
+      type: "string",
+      default: '"CSV"',
+    },
+    tableFormatTsv: {
+      description: "Short format label for TSV",
+      type: "string",
+      default: '"TSV"',
+    },
+  }}
+/>
+
+### Image
+
+<TypeTable
+  type={{
+    imageNotAvailable: {
+      description: "Fallback text for broken images",
+      type: "string",
+      default: '"Image not available"',
+    },
+    downloadImage: {
+      description: "Tooltip for the image download button",
+      type: "string",
+      default: '"Download image"',
+    },
+  }}
+/>
+
+### Link modal
+
+<TypeTable
+  type={{
+    openExternalLink: {
+      description: "Modal title for external links",
+      type: "string",
+      default: '"Open external link?"',
+    },
+    externalLinkWarning: {
+      description: "Warning text in the link modal",
+      type: "string",
+      default: '"You\'re about to visit an external website."',
+    },
+    close: {
+      description: "Close button label",
+      type: "string",
+      default: '"Close"',
+    },
+    copyLink: {
+      description: "Copy link button label",
+      type: "string",
+      default: '"Copy link"',
+    },
+    copied: {
+      description: "Label shown after copying",
+      type: "string",
+      default: '"Copied"',
+    },
+    openLink: {
+      description: "Open link button label",
+      type: "string",
+      default: '"Open link"',
+    },
+  }}
+/>
+
+## Partial overrides
+
+The `translations` prop accepts `Partial<StreamdownTranslations>`. Any key you omit falls back to the built-in English default:
+
+```tsx title="app/page.tsx"
+// Only override what you need — everything else stays English
+<Streamdown translations={{ copyCode: "コピー", close: "閉じる" }}>
+  {markdown}
+</Streamdown>
+```
+
+## Access translations in custom components
+
+Use the `useTranslations` hook inside custom components to read the active translations:
+
+```tsx title="app/page.tsx"
+import { useTranslations } from "streamdown";
+
+function CustomCodeBlock({ children }) {
+  const translations = useTranslations();
+
+  return (
+    <div>
+      <button>{translations.copyCode}</button>
+      <pre><code>{children}</code></pre>
+    </div>
+  );
+}
+```
+
+## Exported types and values
+
+```tsx
+import type { StreamdownTranslations } from "streamdown";
+import { defaultTranslations, useTranslations } from "streamdown";
+```
+
+- `StreamdownTranslations` — interface with all 37 translation keys
+- `defaultTranslations` — the built-in English defaults
+- `useTranslations()` — React hook returning the active translations object
diff --git a/apps/website/content/docs/styling.mdx b/apps/website/content/docs/styling.mdx
