Iniciando
Experimente Online
Você pode experimentar VitePress diretamente no seu navegador em StackBlitz.
Instalação
Pré-requisitos
- Node.js na versão 18 ou superior.
- Terminal para acessar VitePress através da sua interface de linha de comando (CLI).
- Editor de texto com suporte a sintaxe Markdown.
- VSCode é recomendado, junto com a extensão oficial Vue.
VitePress pode ser usado sozinho, ou ser instalado em um projeto já existente. Em ambos os casos, você pode instalá-lo com:
$ npm add -D vitepress$ pnpm add -D vitepress$ yarn add -D vitepress$ yarn add -D vitepress vue$ bun add -D vitepressEstá recebendo avisos sobre dependências correspondentes ausentes?
Se usar PNPM, você perceberá um aviso de ausência de @docsearch/js. Isso não evita que o VitePress funcione. Se você deseja suprimir este aviso, adicione o seguinte no seu package.json:
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"@algolia/client-search",
"search-insights"
]
}
}NOTA
VitePress é um pacote apenas para ESM. Não use require() para importá-lo, e certifique de que o package.json mais próximo contém "type": "module", ou mude a extensão do arquivo de seus arquivos releavantes como .vitepress/config.js para .mjs/.mts. Refira-se ao Guia de resolução de problemas Vite para mais detalhes. Além disso, dentro de contextos de JavaScript comum assíncronos, você pode usar await import('vitepress').
Assistente de Instalação
VitePress tem embutido um assistente de instalação pela linha de comando que irá ajudar a construir um projeto básico. Depois da instalação, inicie o assistente rodando:
$ npx vitepress init$ pnpm vitepress init$ yarn vitepress init$ bun vitepress initVocê será cumprimentado com algumas perguntas simples:
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◆ Theme:
│ ● Default Theme (Out of the box, good-looking docs)
│ ○ Default Theme + Customization
│ ○ Custom Theme
└Vue como Dependência Correspondente
Se você tem a intenção de realizar personalização que usa componentes Vue ou APIs, você deve instalar explicitamente vue como uma dependência correspondente.
Estrutura de Arquivos
Se você estiver construindo um site VitePress individual, você pode desenvolver seu site no diretório atual (./). Entretanto, se você está instalando VitePress em um projeto existente juntamente com outro código fonte, é recomendado construir o site em um diretório aninhado (e.g. ./docs) para que esteja separado do resto do seu projeto.
Assumindo qa escolha de desenvolver o projeto VitePress em ./docs, a estrutura de arquivos gerada deve parecer com a seguinte:
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.jsonO diretório docs é considerado a raiz do projeto do seu site VitePress. O diretório .vitepress é um local reservado para arquivos de configuração VitePress, cache do servidor de desenvolvimento, resultados da build, e código de personalização de tema opcional.
TIP
Por padrão, VitePress armazena o cache do servidor de desenvolvimento em .vitepress/cache, e o resultado da build de produção em .vitepress/dist. Se usar Git, você deve adicioná-los ao seu arquivo .gitignore. Estes locais também podem ser configurados.
O arquivo de configuração
O arquivo de configuração (.vitepress/config.js) permite que você personalize vários aspectos do seu site VitePress, com as opções mais básicas sendo o título e a descrição do site:
// .vitepress/config.js
export default {
// opções a nível do site
title: 'VitePress',
description: 'Só uma brincadeira.',
themeConfig: {
// opções a nível do tema
}
}Você também pode configurar o comportamento do tema através da opção themeConfig. Consulte a Referência de Configuração para detalhes completos sobre todas as opções de configuração.
Arquivos Fonte
Arquivos Markdown fora do diretório .vitepress são considerados arquivos fonte.
VitePress usa roteamento baseado em arquivos: cada arquivo .md é compilado em um arquivo correspondente .html com o mesmo caminho. Por exemplo, index.md será compilado em index.html, e pode ser visitado no caminho raiz / do site VitePress resultante.
VitePress também fornece a habilidade de gerar URLs limpas, reescrever caminhos, e gerar páginas dinamicamente. Estes serão tratados no Guia de Roteamento.
Instalado e Funcionando
A ferramenta deve ter também injetado os seguintes scripts npm no seu package.json se você permitiu isso durante o processo de instalação:
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}O script docs:dev iniciará um servidor de desenvolvimento local com atualizações instantâneas. Rode-o com o seguinte comando:
$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev$ bun run docs:devEm vez de scripts npm, você também pode invocar VitePress diretamente com:
$ npx vitepress dev docs$ pnpm vitepress dev docs$ yarn vitepress dev docs$ bun vitepress dev docsMais usos da linha de comando estão documentados na Referência CLI.
O servidor de desenvolvimento deve estar rodando em http://localhost:5173. Visite a URL no seu navegador para ver o seu novo site em ação!
O que vem depois?
Para melhor entender como arquivos markdown são mapeados no HTML gerado, prossiga para o Guia de Roteamento.
Para descobrir mais sobre o que você pode fazer em uma página, como escrever conteúdo markdown ou usar um componente Vue, refira-se a seção "Escrevendo" do guia. Um ótimo lugar para começar seria aprendendo mais sobre Extensões Markdown.
Para explorar as funcionalidades fornecidas pelo tema padrão da documentação, confira a Referência de Configuração do Tema Padrão.
Se você quer aprofundar a personalização da aparência do seu site, explore tanto em Estenda o Tema Padrão como Construa um Tema Personalizado.
Uma vez que sua documentação tomar forma, certifique-se de ler o Guia de Lançamento.