Migrar VitePress para Starlight: revisar Markdown, URLs e Mermaid

Resumimos o procedimento para migrar um site de documentação criado com VitePress para Astro + Starlight. Quando o site principal roda em Astro, unificar a documentação no Starlight simplifica a operação. Também apresentamos a migração dos diagramas Mermaid para CDN.

Verificar compatibilidade em uma página antes de migrar

Mova primeiro uma página com títulos, links internos, código e Mermaid; compare URLs e diagramas. Importar pelo CDN não transforma necessariamente um bloco Markdown em alvo Mermaid. O renderizador deve passar definições a elementos class=“mermaid”; confira o HTML gerado antes de migrar tudo.

Starlight：Especificações de Markdown e HTML

Por que unificar o framework

Quando o site principal e o site de documentação usam frameworks diferentes, surgem os seguintes problemas:

• Duplicação do custo de aprendizado: É necessário conhecer as especificações tanto do VitePress quanto do Astro
• Dispersão de dependências: Gerenciamento de atualizações de pacotes npm em dois sistemas
• Consistência de configuração: Manutenção individual de ESLint, Prettier, configurações de deploy etc.

Ao unificar com Astro + Starlight, é possível compartilhar padrões de arquivos de configuração e conhecimentos de troubleshooting.

Procedimento de migração do VitePress para o Starlight

1. Conversão da estrutura do projeto

VitePress coloca os documentos no diretório docs/, enquanto Starlight usa src/content/docs/.

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

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

2. Ajuste do frontmatter

O formato do frontmatter difere ligeiramente entre VitePress e Starlight. A configuração de sidebar do VitePress foi migrada para o campo sidebar do frontmatter.

# Frontmatter do Starlight
---
title: Visão geral do negócio
sidebar:
  order: 1
---

3. Configuração do astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: "Plano de Negócios Acecore",
      defaultLocale: "ja",
      sidebar: [
        {
          label: "Plano de Negócios",
          autogenerate: { directory: "/" },
        },
      ],
    }),
  ],
});

4. Remoção do UnoCSS

No ambiente VitePress, estilos personalizados eram aplicados com UnoCSS, mas o Starlight possui estilos padrão suficientes embutidos. Removemos uno.config.ts e pacotes relacionados, reduzindo as dependências.

Migração da Mermaid para CDN

Os documentos usavam vitepress-plugin-mermaid. Escolhemos CDN no Starlight para unificar dependências. Consulte a lista oficial de plugins: CDN não é a única opção.

Assim, mudamos para carregar a Mermaid via CDN no lado do navegador.

Implementação

Adicionamos o script CDN da Mermaid ao cabeçalho personalizado do Starlight.

// 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 })
      `,
    },
  ],
});

O bloco abaixo define um diagrama; também é necessário passá-lo aos elementos alvo do Mermaid:

```mermaid
graph TD
    A[Plano de Negócios] --> B[Análise de Mercado]
    A --> C[Estratégia de Vendas]
    A --> D[Plano Financeiro]
```

Benefícios da abordagem CDN

• Zero dependências de build: Mermaid como pacote npm não é necessário
• Fixar versão: O exemplo escolhe 11.16.0; usar CDN não atualiza automaticamente para a versão mais recente
• SSR desnecessário: Renderização no navegador, sem impacto no tempo de build

Resultado da migração

Item	Antes	Depois
Framework	VitePress 1.x	Astro 6 + Starlight
CSS	UnoCSS	Estilização integrada do Starlight
Mermaid	vitepress-plugin-mermaid	CDN (jsdelivr)
Saída do build	docs/.vitepress/dist	dist
Hospedagem	Cloudflare Pages	Cloudflare Pages (sem alteração)

Com a unificação do framework, é possível compartilhar padrões de configuração do astro.config.mjs e configurações de deploy entre múltiplos projetos.

Conclusão

A unificação de frameworks pode não ser “urgente”, mas quanto mais longa a operação, maior o benefício. A migração do VitePress para o Starlight pode ser concluída em poucas horas, e a migração da Mermaid para CDN é até um benefício — a liberação da gestão de plugins. Se você opera múltiplos projetos, considere unificar a stack tecnológica.