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

# Iniciando {#getting-started}

## Experimente Online {#try-it-online}

Você pode experimentar VitePress diretamente no seu navegador em [StackBlitz](https://vitepress.new).

## Instalação {#installation}

### Pré-requisitos {#prerequisites}

- [Node.js](https://nodejs.org/) 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](https://en.wikipedia.org/wiki/Markdown).
  - [VSCode](https://code.visualstudio.com/) é recomendado, junto com a [extensão oficial Vue](https://marketplace.visualstudio.com/items?itemName=Vue.volar).

VitePress pode ser usado sozinho, ou ser instalado em um projeto já existente. Em ambos os casos, você pode instalá-lo com:

::: code-group

```sh [npm]
$ npm add -D vitepress
```

```sh [pnpm]
$ pnpm add -D vitepress
```

```sh [yarn]
$ yarn add -D vitepress
```

```sh [yarn (pnp)]
$ yarn add -D vitepress vue
```

```sh [bun]
$ 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`:

```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](http://vitejs.dev/guide/troubleshooting.html#this-package-is-esm-only) para mais detalhes. Além disso, dentro de contextos de JavaScript comum assíncronos, você pode usar `await import('vitepress')`.

:::

### Assistente de Instalação {#setup-wizard}

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

```sh [npm]
$ npx vitepress init
```

```sh [pnpm]
$ pnpm vitepress init
```

```sh [yarn]
$ yarn vitepress init
```

```sh [bun]
$ 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 {#file-structure}

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](../reference/site-config#outdir).
:::

### O arquivo de configuração {#the-config-file}

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:

```js
// .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](../reference/site-config) para detalhes completos sobre todas as opções de configuração.

### Arquivos Fonte {#source-files}

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](./routing).

## Instalado e Funcionando {#up-and-running}

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:

```json
{
  ...
  "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

```sh [npm]
$ npm run docs:dev
```

```sh [pnpm]
$ pnpm run docs:dev
```

```sh [yarn]
$ yarn docs:dev
```

```sh [bun]
$ bun run docs:dev
```

:::

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

::: code-group

```sh [npm]
$ npx vitepress dev docs
```

```sh [pnpm]
$ pnpm vitepress dev docs
```

```sh [yarn]
$ yarn vitepress dev docs
```

```sh [bun]
$ bun vitepress dev docs
```

:::

Mais usos da linha de comando estão documentados na [Referência CLI](../reference/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? {#what-s-next}

- Para melhor entender como arquivos markdown são mapeados no HTML gerado, prossiga para o [Guia de Roteamento](./routing).

- 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](./markdown).

- Para explorar as funcionalidades fornecidas pelo tema padrão da documentação, confira a [Referência de Configuração do Tema Padrão](../reference/default-theme-config).

- Se você quer aprofundar a personalização da aparência do seu site, explore tanto em [Estenda o Tema Padrão](./extending-default-theme) como [Construa um Tema Personalizado](./custom-theme).

- Uma vez que sua documentação tomar forma, certifique-se de ler o [Guia de Lançamento](./deploy).