mirror of https://github.com/vuejs/vitepress
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
221 lines
7.1 KiB
221 lines
7.1 KiB
# 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).
|