tidymd
v0.2.0
Published
Utilities for working with Markdown and MDX files in Starlight
Readme
tidymd
Utilities for working with Markdown and MDX files in Starlight
Installation
npm install tidymdyarn add tidymdpnpm add tidymdcleanStarlightMarkdown
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, andTabItem. - Converts content components like
Card,LinkCard,Aside,Badge,Code, andLinkButtonto 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 converttitleto anh1.keep-title-description: keep onlytitleanddescription.
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.mdfiles.
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",
},
});extractStarlightFrontmatter
Extracts the YAML frontmatter from Markdown or MDX content authored for Starlight.
Starlight frontmatter can be extended by integrations or user schemas, so the default return type is Record<string, unknown>. Pass a generic type when your project has a known schema.
const frontmatter = extractStarlightFrontmatter(content);Parameters
content
Raw Markdown or MDX content from a Starlight documentation page.
Returns
Parsed frontmatter, or null when the file has no frontmatter block.
type StarlightFrontmatter = Record<string, unknown>;Example
import { extractStarlightFrontmatter } from "tidymd";
const frontmatter = extractStarlightFrontmatter(content);Type-Safe Frontmatter
Pass a generic type when your project extends Starlight frontmatter with known fields.
import { extractStarlightFrontmatter } from "tidymd";
interface DocsFrontmatter {
title: string;
description?: string;
sidebar?: { order?: number };
}
const frontmatter = extractStarlightFrontmatter<DocsFrontmatter>(content);