tidymd

Clean Markdown and MDX content so it can be reused as plain Markdown.

Installation

npm install tidymd

yarn add tidymd

pnpm add tidymd

cleanStarlightMarkdown

Cleans Markdown and MDX content authored for Starlight so it can be reused as plain Markdown.

This utility:

• Removes Starlight component imports.
• Removes layout-only wrappers like Steps, CardGrid, FileTree, Icon, Tabs, and TabItem.
• Converts content components like Card, LinkCard, Aside, Badge, Code, and LinkButton to Markdown.
• Supports configurable frontmatter handling.
• Supports configurable internal link rewriting.

const markdown = cleanStarlightMarkdown(content, options);

Parameters

content

Raw Markdown or MDX content from a Starlight documentation page.

options

Options for frontmatter handling and internal link rewriting.

interface CleanStarlightMarkdownOptions {
  frontmatter?: StarlightFrontmatterMode;
  internalLinks?: StarlightInternalLinkMode;
}

Frontmatter

Controls how frontmatter is handled.

type StarlightFrontmatterMode =
  | "preserve"
  | "remove"
  | "title-as-heading"
  | "keep-title-description";

• preserve: keep all frontmatter. This is the default.
• remove: remove all frontmatter.
• title-as-heading: remove frontmatter and convert title to an h1.
• keep-title-description: keep only title and description.

Internal Links

Controls how absolute internal Markdown links are handled.

type StarlightInternalLinkMode =
  | { mode: "preserve" }
  | { mode: "baseUrl"; baseUrl: string }
  | { mode: "file" };

• { mode: "preserve" }: keep internal links unchanged. This is the default.
• { mode: "baseUrl", baseUrl }: prefix internal links with a base URL.
• { mode: "file" }: rewrite internal links to local .md files.

External links are preserved.

Example

import { cleanStarlightMarkdown } from "tidymd";

const markdown = cleanStarlightMarkdown(content, {
  frontmatter: "title-as-heading",
  internalLinks: {
    mode: "baseUrl",
    baseUrl: "https://docs.example.com",
  },
});