# tidymd

Utilities for working with Markdown and MDX files in Starlight

## Installation

```bash
npm install tidymd
```

```bash
yarn add tidymd
```

```bash
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.

```ts
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.

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

### Frontmatter

Controls how frontmatter is handled.

```ts
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.

```ts
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

```ts
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.

```ts
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.

```ts
type StarlightFrontmatter = Record<string, unknown>;
```

### Example

```ts
import { extractStarlightFrontmatter } from "tidymd";

const frontmatter = extractStarlightFrontmatter(content);
```

### Type-Safe Frontmatter

Pass a generic type when your project extends Starlight frontmatter with known fields.

```ts
import { extractStarlightFrontmatter } from "tidymd";

interface DocsFrontmatter {
  title: string;
  description?: string;
  sidebar?: { order?: number };
}

const frontmatter = extractStarlightFrontmatter<DocsFrontmatter>(content);
```