Migrate VitePress to Starlight: Markdown, URL, and Mermaid checks

Here’s a walkthrough of migrating a VitePress documentation site to Astro + Starlight. If your main site runs on Astro, unifying your docs under Starlight simplifies operations. We also cover migrating Mermaid diagrams to CDN.

Check compatibility on one page before migrating

First move one page containing headings, internal links, code, and Mermaid, then compare generated URLs and diagrams. A CDN import alone does not necessarily turn a Markdown code block into a Mermaid target. The rendering path must pass definitions to class=“mermaid” elements; inspect generated HTML before migrating everything.

Starlight：Markdown and HTML authoring specifications

Why Unify Frameworks?

Using different frameworks for the main site and documentation site creates the following problems:

• Doubled learning costs: You need to understand both VitePress and Astro specifications
• Scattered dependencies: npm package updates managed across two separate systems
• Configuration inconsistency: ESLint, Prettier, deploy settings, etc. maintained independently

Unifying on Astro + Starlight enables sharing configuration file patterns and troubleshooting knowledge.

Migration Steps: VitePress to Starlight

1. Project Structure Conversion

VitePress places documents in the docs/ directory, while Starlight uses src/content/docs/.

# Before (VitePress)
docs/
  pages/
    index.md
    business-overview.md
    market-analysis.md

# After (Starlight)
src/
  content/
    docs/
      index.md
      business-overview.md
      market-analysis.md

2. Frontmatter Adjustments

VitePress and Starlight have slightly different frontmatter formats. We migrated VitePress’s sidebar configuration to Starlight’s frontmatter sidebar field.

# Starlight frontmatter
---
title: Business Overview
sidebar:
  order: 1
---

3. astro.config.mjs Configuration

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      title: "Acecore Business Plan",
      defaultLocale: "ja",
      sidebar: [
        {
          label: "Business Plan",
          autogenerate: { directory: "/" },
        },
      ],
    }),
  ],
});

4. Removing UnoCSS

In the VitePress environment, UnoCSS was used for custom styles, but Starlight comes with sufficient built-in default styles. We removed uno.config.ts and related packages, slimming down the dependencies.

Mermaid Diagram CDN Migration

The documents used VitePress’s vitepress-plugin-mermaid. We chose CDN loading in Starlight to align dependency management. See the official plugin list for extensions; CDN loading is not the only option.

So we switched to loading Mermaid from a CDN on the browser side.

Implementation

Add the Mermaid CDN script to Starlight’s custom head:

// astro.config.mjs
starlight({
  head: [
    {
      tag: "script",
      attrs: { type: "module" },
      content: `
        import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11.16.0/dist/mermaid.esm.min.mjs'
        mermaid.initialize({ startOnLoad: true })
      `,
    },
  ],
});

The code block below defines a diagram. Rendering also needs a path that supplies it to Mermaid target elements:

```mermaid
graph TD
    A[Business Plan] --> B[Market Analysis]
    A --> C[Sales Strategy]
    A --> D[Financial Plan]
```

Benefits of the CDN Approach

• Zero build dependencies: Mermaid as an npm package is no longer needed
• Pin the version: The example selects 11.16.0; using a CDN does not automatically update it to the latest release
• No SSR required: Rendered in the browser, so no impact on build time

Migration Results

Item	Before	After
Framework	VitePress 1.x	Astro 6 + Starlight
CSS	UnoCSS	Starlight built-in
Mermaid	vitepress-plugin-mermaid	CDN (jsdelivr)
Build output	docs/.vitepress/dist	dist
Deployment	Cloudflare Pages	Cloudflare Pages (unchanged)

By unifying frameworks, astro.config.mjs configuration patterns and deployment settings can be shared across multiple projects.

Conclusion

Framework unification may not be “urgent,” but the longer you operate, the more it pays off. The migration from VitePress to Starlight itself can be completed in a few hours, and the CDN approach for Mermaid is actually a liberation from plugin management. If you’re running multiple projects, consider unifying your tech stack.