vitepress/docs/pt/guide/getting-started.md

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:

::: code-group

$ npm add -D vitepress

$ pnpm add -D vitepress

$ yarn add -D vitepress

$ bun add -D vitepress

:::

::: details Está 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"
    ]
  }
}

:::

::: tip 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:

::: code-group

$ npx vitepress init

$ pnpm vitepress init

$ yarn vitepress init

$ bun vitepress init

:::

Você será cumprimentado com algumas perguntas simples:

<<< @/snippets/init.ansi

::: tip 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.json

O 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:

::: code-group

$ npm run docs:dev

$ pnpm run docs:dev

$ yarn docs:dev

$ bun run docs:dev

:::

Em vez de scripts npm, você também pode invocar VitePress diretamente com:

::: code-group

$ npx vitepress dev docs

$ pnpm vitepress dev docs

$ yarn vitepress dev docs

$ bun vitepress dev docs

:::

Mais 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.