mirror of https://github.com/vuejs/vitepress
Simon East
1 year ago
committed by
GitHub
commit
14edec923d
@ -0,0 +1,15 @@
|
||||
name: Close stale issues and PRs
|
||||
on:
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
stale:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/stale@v9
|
||||
with:
|
||||
days-before-stale: 30
|
||||
days-before-close: -1
|
||||
stale-issue-label: stale
|
||||
stale-pr-label: stale
|
||||
operations-per-run: 1000
|
||||
@ -1,2 +1,2 @@
|
||||
shell-emulator=true
|
||||
resolution-mode=highest
|
||||
auto-install-peers=false
|
||||
|
||||
|
After Width: | Height: | Size: 2.4 KiB |
|
After Width: | Height: | Size: 4.3 KiB |
@ -1,227 +0,0 @@
|
||||
import { createRequire } from 'module'
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
const require = createRequire(import.meta.url)
|
||||
const pkg = require('vitepress/package.json')
|
||||
|
||||
export default defineConfig({
|
||||
lang: 'en-US',
|
||||
title: 'VitePress',
|
||||
description: 'Vite & Vue powered static site generator.',
|
||||
|
||||
lastUpdated: true,
|
||||
cleanUrls: true,
|
||||
|
||||
head: [
|
||||
['meta', { name: 'theme-color', content: '#3c8772' }],
|
||||
[
|
||||
'script',
|
||||
{
|
||||
src: 'https://cdn.usefathom.com/script.js',
|
||||
'data-site': 'AZBRSFGG',
|
||||
'data-spa': 'auto',
|
||||
defer: ''
|
||||
}
|
||||
]
|
||||
],
|
||||
|
||||
themeConfig: {
|
||||
nav: nav(),
|
||||
|
||||
sidebar: {
|
||||
'/guide/': sidebarGuide(),
|
||||
'/reference/': sidebarReference()
|
||||
},
|
||||
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
|
||||
text: 'Edit this page on GitHub'
|
||||
},
|
||||
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }
|
||||
],
|
||||
|
||||
footer: {
|
||||
message: 'Released under the MIT License.',
|
||||
copyright: 'Copyright © 2019-present Evan You'
|
||||
},
|
||||
|
||||
search: {
|
||||
provider: 'algolia',
|
||||
options: {
|
||||
appId: '8J64VVRP8K',
|
||||
apiKey: 'a18e2f4cc5665f6602c5631fd868adfd',
|
||||
indexName: 'vitepress'
|
||||
}
|
||||
},
|
||||
|
||||
carbonAds: {
|
||||
code: 'CEBDT27Y',
|
||||
placement: 'vuejsorg'
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
function nav() {
|
||||
return [
|
||||
{ text: 'Guide', link: '/guide/what-is-vitepress', activeMatch: '/guide/' },
|
||||
{
|
||||
text: 'Reference',
|
||||
link: '/reference/site-config',
|
||||
activeMatch: '/reference/'
|
||||
},
|
||||
{
|
||||
text: pkg.version,
|
||||
items: [
|
||||
{
|
||||
text: 'Changelog',
|
||||
link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md'
|
||||
},
|
||||
{
|
||||
text: 'Contributing',
|
||||
link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
function sidebarGuide() {
|
||||
return [
|
||||
{
|
||||
text: 'Introduction',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'What is VitePress?', link: '/guide/what-is-vitepress' },
|
||||
{ text: 'Getting Started', link: '/guide/getting-started' },
|
||||
{ text: 'Routing', link: '/guide/routing' },
|
||||
{ text: 'Deploy', link: '/guide/deploy' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Writing',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Markdown Extensions', link: '/guide/markdown' },
|
||||
{ text: 'Asset Handling', link: '/guide/asset-handling' },
|
||||
{ text: 'Frontmatter', link: '/guide/frontmatter' },
|
||||
{ text: 'Using Vue in Markdown', link: '/guide/using-vue' },
|
||||
{ text: 'Internationalization', link: '/guide/i18n' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Customization',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Using a Custom Theme', link: '/guide/custom-theme' },
|
||||
{
|
||||
text: 'Extending the Default Theme',
|
||||
link: '/guide/extending-default-theme'
|
||||
},
|
||||
{ text: 'Build-Time Data Loading', link: '/guide/data-loading' },
|
||||
{ text: 'SSR Compatibility', link: '/guide/ssr-compat' },
|
||||
{ text: 'Connecting to a CMS', link: '/guide/cms' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Experimental',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{
|
||||
text: 'MPA Mode',
|
||||
link: '/guide/mpa-mode'
|
||||
}
|
||||
]
|
||||
},
|
||||
// {
|
||||
// text: 'Migrations',
|
||||
// collapsed: false,
|
||||
// items: [
|
||||
// {
|
||||
// text: 'Migration from VuePress',
|
||||
// link: '/guide/migration-from-vuepress'
|
||||
// },
|
||||
// {
|
||||
// text: 'Migration from VitePress 0.x',
|
||||
// link: '/guide/migration-from-vitepress-0'
|
||||
// }
|
||||
// ]
|
||||
// },
|
||||
{
|
||||
text: 'Config & API Reference',
|
||||
link: '/reference/site-config'
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
function sidebarReference() {
|
||||
return [
|
||||
{
|
||||
text: 'Reference',
|
||||
items: [
|
||||
{ text: 'Site Config', link: '/reference/site-config' },
|
||||
{ text: 'Frontmatter Config', link: '/reference/frontmatter-config' },
|
||||
{ text: 'Runtime API', link: '/reference/runtime-api' },
|
||||
{ text: 'CLI', link: '/reference/cli' },
|
||||
{
|
||||
text: 'Default Theme',
|
||||
items: [
|
||||
{
|
||||
text: 'Overview',
|
||||
link: '/reference/default-theme-config'
|
||||
},
|
||||
{
|
||||
text: 'Nav',
|
||||
link: '/reference/default-theme-nav'
|
||||
},
|
||||
{
|
||||
text: 'Sidebar',
|
||||
link: '/reference/default-theme-sidebar'
|
||||
},
|
||||
{
|
||||
text: 'Home Page',
|
||||
link: '/reference/default-theme-home-page'
|
||||
},
|
||||
{
|
||||
text: 'Footer',
|
||||
link: '/reference/default-theme-footer'
|
||||
},
|
||||
{
|
||||
text: 'Layout',
|
||||
link: '/reference/default-theme-layout'
|
||||
},
|
||||
{
|
||||
text: 'Badge',
|
||||
link: '/reference/default-theme-badge'
|
||||
},
|
||||
{
|
||||
text: 'Team Page',
|
||||
link: '/reference/default-theme-team-page'
|
||||
},
|
||||
{
|
||||
text: 'Prev / Next Links',
|
||||
link: '/reference/default-theme-prev-next-links'
|
||||
},
|
||||
{
|
||||
text: 'Edit Link',
|
||||
link: '/reference/default-theme-edit-link'
|
||||
},
|
||||
{
|
||||
text: 'Last Updated Timestamp',
|
||||
link: '/reference/default-theme-last-updated'
|
||||
},
|
||||
{
|
||||
text: 'Search',
|
||||
link: '/reference/default-theme-search'
|
||||
},
|
||||
{
|
||||
text: 'Carbon Ads',
|
||||
link: '/reference/default-theme-carbon-ads'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -0,0 +1,139 @@
|
||||
import { createRequire } from 'module'
|
||||
import { defineConfig, type DefaultTheme } from 'vitepress'
|
||||
|
||||
const require = createRequire(import.meta.url)
|
||||
const pkg = require('vitepress/package.json')
|
||||
|
||||
export const en = defineConfig({
|
||||
lang: 'en-US',
|
||||
description: 'Vite & Vue powered static site generator.',
|
||||
|
||||
themeConfig: {
|
||||
nav: nav(),
|
||||
|
||||
sidebar: {
|
||||
'/guide/': { base: '/guide/', items: sidebarGuide() },
|
||||
'/reference/': { base: '/reference/', items: sidebarReference() }
|
||||
},
|
||||
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
|
||||
text: 'Edit this page on GitHub'
|
||||
},
|
||||
|
||||
footer: {
|
||||
message: 'Released under the MIT License.',
|
||||
copyright: 'Copyright © 2019-present Evan You'
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
function nav(): DefaultTheme.NavItem[] {
|
||||
return [
|
||||
{
|
||||
text: 'Guide',
|
||||
link: '/guide/what-is-vitepress',
|
||||
activeMatch: '/guide/'
|
||||
},
|
||||
{
|
||||
text: 'Reference',
|
||||
link: '/reference/site-config',
|
||||
activeMatch: '/reference/'
|
||||
},
|
||||
{
|
||||
text: pkg.version,
|
||||
items: [
|
||||
{
|
||||
text: 'Changelog',
|
||||
link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md'
|
||||
},
|
||||
{
|
||||
text: 'Contributing',
|
||||
link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
function sidebarGuide(): DefaultTheme.SidebarItem[] {
|
||||
return [
|
||||
{
|
||||
text: 'Introduction',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'What is VitePress?', link: 'what-is-vitepress' },
|
||||
{ text: 'Getting Started', link: 'getting-started' },
|
||||
{ text: 'Routing', link: 'routing' },
|
||||
{ text: 'Deploy', link: 'deploy' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Writing',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Markdown Extensions', link: 'markdown' },
|
||||
{ text: 'Asset Handling', link: 'asset-handling' },
|
||||
{ text: 'Frontmatter', link: 'frontmatter' },
|
||||
{ text: 'Using Vue in Markdown', link: 'using-vue' },
|
||||
{ text: 'Internationalization', link: 'i18n' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Customization',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Using a Custom Theme', link: 'custom-theme' },
|
||||
{
|
||||
text: 'Extending the Default Theme',
|
||||
link: 'extending-default-theme'
|
||||
},
|
||||
{ text: 'Build-Time Data Loading', link: 'data-loading' },
|
||||
{ text: 'SSR Compatibility', link: 'ssr-compat' },
|
||||
{ text: 'Connecting to a CMS', link: 'cms' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Experimental',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'MPA Mode', link: 'mpa-mode' },
|
||||
{ text: 'Sitemap Generation', link: 'sitemap-generation' }
|
||||
]
|
||||
},
|
||||
{ text: 'Config & API Reference', base: '/reference/', link: 'site-config' }
|
||||
]
|
||||
}
|
||||
|
||||
function sidebarReference(): DefaultTheme.SidebarItem[] {
|
||||
return [
|
||||
{
|
||||
text: 'Reference',
|
||||
items: [
|
||||
{ text: 'Site Config', link: 'site-config' },
|
||||
{ text: 'Frontmatter Config', link: 'frontmatter-config' },
|
||||
{ text: 'Runtime API', link: 'runtime-api' },
|
||||
{ text: 'CLI', link: 'cli' },
|
||||
{
|
||||
text: 'Default Theme',
|
||||
base: '/reference/default-theme-',
|
||||
items: [
|
||||
{ text: 'Overview', link: 'config' },
|
||||
{ text: 'Nav', link: 'nav' },
|
||||
{ text: 'Sidebar', link: 'sidebar' },
|
||||
{ text: 'Home Page', link: 'home-page' },
|
||||
{ text: 'Footer', link: 'footer' },
|
||||
{ text: 'Layout', link: 'layout' },
|
||||
{ text: 'Badge', link: 'badge' },
|
||||
{ text: 'Team Page', link: 'team-page' },
|
||||
{ text: 'Prev / Next Links', link: 'prev-next-links' },
|
||||
{ text: 'Edit Link', link: 'edit-link' },
|
||||
{ text: 'Last Updated Timestamp', link: 'last-updated' },
|
||||
{ text: 'Search', link: 'search' },
|
||||
{ text: 'Carbon Ads', link: 'carbon-ads' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -0,0 +1,17 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
import { shared } from './shared'
|
||||
import { en } from './en'
|
||||
import { zh } from './zh'
|
||||
import { pt } from './pt'
|
||||
import { ru } from './ru'
|
||||
|
||||
export default defineConfig({
|
||||
...shared,
|
||||
locales: {
|
||||
root: { label: 'English', ...en },
|
||||
zh: { label: '简体中文', ...zh },
|
||||
pt: { label: 'Português', ...pt },
|
||||
ru: { label: 'Русский', ...ru },
|
||||
ko: { label: '한국어', lang: 'ko-KR', link: 'https://vitepress.vuejs.kr/' }
|
||||
}
|
||||
})
|
||||
@ -0,0 +1,65 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
import { search as zhSearch } from './zh'
|
||||
import { search as ptSearch } from './pt'
|
||||
import { search as ruSearch } from './ru'
|
||||
|
||||
export const shared = defineConfig({
|
||||
title: 'VitePress',
|
||||
|
||||
lastUpdated: true,
|
||||
cleanUrls: true,
|
||||
metaChunk: true,
|
||||
|
||||
markdown: {
|
||||
math: true,
|
||||
codeTransformers: [
|
||||
// We use `[!!code` in demo to prevent transformation, here we revert it back.
|
||||
{
|
||||
postprocess(code) {
|
||||
return code.replace(/\[\!\!code/g, '[!code')
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
sitemap: {
|
||||
hostname: 'https://vitepress.dev',
|
||||
transformItems(items) {
|
||||
return items.filter((item) => !item.url.includes('migration'))
|
||||
}
|
||||
},
|
||||
|
||||
/* prettier-ignore */
|
||||
head: [
|
||||
['link', { rel: 'icon', type: 'image/svg+xml', href: '/vitepress-logo-mini.svg' }],
|
||||
['link', { rel: 'icon', type: 'image/png', href: '/vitepress-logo-mini.png' }],
|
||||
['meta', { name: 'theme-color', content: '#5f67ee' }],
|
||||
['meta', { property: 'og:type', content: 'website' }],
|
||||
['meta', { property: 'og:locale', content: 'en' }],
|
||||
['meta', { property: 'og:title', content: 'VitePress | Vite & Vue Powered Static Site Generator' }],
|
||||
['meta', { property: 'og:site_name', content: 'VitePress' }],
|
||||
['meta', { property: 'og:image', content: 'https://vitepress.dev/vitepress-og.jpg' }],
|
||||
['meta', { property: 'og:url', content: 'https://vitepress.dev/' }],
|
||||
['script', { src: 'https://cdn.usefathom.com/script.js', 'data-site': 'AZBRSFGG', 'data-spa': 'auto', defer: '' }]
|
||||
],
|
||||
|
||||
themeConfig: {
|
||||
logo: { src: '/vitepress-logo-mini.svg', width: 24, height: 24 },
|
||||
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }
|
||||
],
|
||||
|
||||
search: {
|
||||
provider: 'algolia',
|
||||
options: {
|
||||
appId: '8J64VVRP8K',
|
||||
apiKey: 'a18e2f4cc5665f6602c5631fd868adfd',
|
||||
indexName: 'vitepress',
|
||||
locales: { ...zhSearch, ...ptSearch, ...ruSearch }
|
||||
}
|
||||
},
|
||||
|
||||
carbonAds: { code: 'CEBDT27Y', placement: 'vuejsorg' }
|
||||
}
|
||||
})
|
||||
@ -0,0 +1,58 @@
|
||||
# Sitemap Generation
|
||||
|
||||
VitePress comes with out-of-the-box support for generating a `sitemap.xml` file for your site. To enable it, add the following to your `.vitepress/config.js`:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
sitemap: {
|
||||
hostname: 'https://example.com'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To have `<lastmod>` tags in your `sitemap.xml`, you can enable the [`lastUpdated`](../reference/default-theme-last-updated) option.
|
||||
|
||||
## Options
|
||||
|
||||
Sitemap support is powered by the [`sitemap`](https://www.npmjs.com/package/sitemap) module. You can pass any options supported by it to the `sitemap` option in your config file. These will be passed directly to the `SitemapStream` constructor. Refer to the [`sitemap` documentation](https://www.npmjs.com/package/sitemap#options-you-can-pass) for more details. Example:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
sitemap: {
|
||||
hostname: 'https://example.com',
|
||||
lastmodDateOnly: false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you're using `base` in your config, you should append it to the `hostname` option:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
base: '/my-site/',
|
||||
sitemap: {
|
||||
hostname: 'https://example.com/my-site/'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## `transformItems` Hook
|
||||
|
||||
You can use the `sitemap.transformItems` hook to modify the sitemap items before they are written to the `sitemap.xml` file. This hook is called with an array of sitemap items and expects an array of sitemap items to be returned. Example:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
sitemap: {
|
||||
hostname: 'https://example.com',
|
||||
transformItems: (items) => {
|
||||
// add new items or modify/filter existing items
|
||||
items.push({
|
||||
url: '/extra-page',
|
||||
changefreq: 'monthly',
|
||||
priority: 0.8
|
||||
})
|
||||
return items
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
Before Width: | Height: | Size: 18 KiB |
@ -0,0 +1,39 @@
|
||||
{
|
||||
"$schema": "./node_modules/@lunariajs/core/config.schema.json",
|
||||
"repository": {
|
||||
"name": "vuejs/vitepress",
|
||||
"rootDir": "docs"
|
||||
},
|
||||
"files": [
|
||||
{
|
||||
"location": ".vitepress/config/{en,zh,pt,ru}.ts",
|
||||
"pattern": ".vitepress/config/@lang.ts",
|
||||
"type": "universal"
|
||||
},
|
||||
{
|
||||
"location": "**/*.md",
|
||||
"pattern": "@lang/@path",
|
||||
"type": "universal"
|
||||
}
|
||||
],
|
||||
"defaultLocale": {
|
||||
"label": "English",
|
||||
"lang": "en"
|
||||
},
|
||||
"locales": [
|
||||
{
|
||||
"label": "简体中文",
|
||||
"lang": "zh"
|
||||
},
|
||||
{
|
||||
"label": "Português",
|
||||
"lang": "pt"
|
||||
},
|
||||
{
|
||||
"label": "Русский",
|
||||
"lang": "ru"
|
||||
}
|
||||
],
|
||||
"outDir": ".vitepress/dist/_translations",
|
||||
"ignoreKeywords": ["lunaria-ignore"]
|
||||
}
|
||||
@ -0,0 +1,59 @@
|
||||
# Manipulação de Ativos {#asset-handling}
|
||||
|
||||
## Referenciando Ativos Estáticos {#referencing-static-assets}
|
||||
|
||||
Todos os arquivos Markdown são compilados em componentes Vue e processados por [Vite](https://vitejs.dev/guide/assets.html). Você pode **e deve** referenciar quaisquer ativos usando URLs relativas:
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
Você pode referenciar ativos estáticos em seus arquivos markdown, seus componentes `*.vue` no tema, estilos e simples arquivos `.css`, usando caminhos públicos absolutos (com base na raiz do projeto) ou caminhos relativos (com base em seu sistema de arquivos). Este último é semelhante ao comportamento que você está acostumado se já usou Vite, Vue CLI ou o `file-loader` do webpack.
|
||||
|
||||
Tipos comuns de arquivos de imagem, mídia e fonte são detectados e incluídos automaticamente como ativos.
|
||||
|
||||
Todos os ativos referenciados, incluindo aqueles usando caminhos absolutos, serão copiados para o diretório de saída com um nome de arquivo hash na compilação de produção. Ativos nunca referenciados não serão copiados. Ativos de imagem menores que 4KB serão incorporados em base64 - isso pode ser configurado pela opção [`vite`](../reference/site-config#vite) da configuração.
|
||||
|
||||
Todas as referências de caminho **estáticas**, incluindo caminhos absolutos, devem ser baseadas na estrutura do seu diretório de trabalho.
|
||||
|
||||
## O Diretório Público {#the-public-directory}
|
||||
|
||||
Às vezes, pode ser necessário fornecer ativos estáticos que não são referenciados diretamente em nenhum de seus componentes do tema ou Markdown, ou você pode querer servir certos arquivos com o nome de arquivo original. Exemplos de tais arquivos incluem `robots.txt`, favicons e ícones PWA.
|
||||
|
||||
Você pode colocar esses arquivos no diretório `public` sob o [diretório fonte](./routing#source-directory). Por exemplo, se a raiz do seu projeto for `./docs` e estiver usando a localização padrão do diretório fonte, então o diretório público será `./docs/public`.
|
||||
|
||||
Os ativos colocados em `public` serão copiados para a raiz do diretório de saída como são.
|
||||
|
||||
Observe que você deve referenciar arquivos colocados em `public` usando o caminho absoluto da raiz - por exemplo, `public/icon.png` deve sempre ser referenciado no código fonte como `/icon.png`.
|
||||
|
||||
## URL Base {#base-url}
|
||||
|
||||
Se seu site for implantado em uma URL que não seja a raiz, será necessário definir a opção `base` em `.vitepress/config.js`. Por exemplo, se você planeja implantar seu site em `https://foo.github.io/bar/`, então `base` deve ser definido como `'/bar/'` (sempre deve começar e terminar com uma barra).
|
||||
|
||||
Todos os caminhos dos seus ativos estáticos são processados automaticamente para se ajustar aos diferentes valores de configuração `base`. Por exemplo, se você tiver uma referência absoluta a um ativo sob `public` no seu markdown:
|
||||
|
||||
```md
|
||||
|
||||
```
|
||||
|
||||
Você **não** precisa atualizá-lo quando alterar o valor de configuração `base` nesse caso.
|
||||
|
||||
No entanto, se você estiver criando um componente de tema que vincula ativos dinamicamente, por exemplo, uma imagem cujo `src` é baseado em um valor de configuração do tema:
|
||||
|
||||
```vue
|
||||
<img :src="theme.logoPath" />
|
||||
```
|
||||
|
||||
Nesse caso, é recomendável envolver o caminho com o [`auxiliar withBase`](../reference/runtime-api#withbase) fornecido por VitePress:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { withBase, useData } from 'vitepress'
|
||||
|
||||
const { theme } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<img :src="withBase(theme.logoPath)" />
|
||||
</template>
|
||||
```
|
||||
@ -0,0 +1,56 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Conectando a um CMS {#connecting-to-a-cms}
|
||||
|
||||
## Fluxo de Trabalho Geral {#general-workflow}
|
||||
|
||||
Conectar VitePress a um CMS orbitará majoritariamente sobre [Rotas Dinâmicas](./routing#dynamic-routes). Certifique-se de entender como funcionam antes de proceder.
|
||||
|
||||
Como cada CMS funcionará de forma diferente, aqui podemos fornecer apenas um fluxo de trabalho genérico que precisará ser adaptado para cada cenário específico.
|
||||
|
||||
1. Se seu CMS exige autenticação, crie um arquivo `.env` para armazenar os tokens da API e carregá-los como:
|
||||
|
||||
```js
|
||||
// posts/[id].paths.js
|
||||
import { loadEnv } from 'vitepress'
|
||||
|
||||
const env = loadEnv('', process.cwd())
|
||||
```
|
||||
|
||||
2. Obtenha os dados necessários do CMS e formate-os em caminhos de dados apropriados:
|
||||
|
||||
```js
|
||||
export default {
|
||||
async paths() {
|
||||
// use a biblitoca do cliente CMS respectiva se preciso
|
||||
const data = await (await fetch('https://my-cms-api', {
|
||||
headers: {
|
||||
// token se necessário
|
||||
}
|
||||
})).json()
|
||||
|
||||
return data.map(entry => {
|
||||
return {
|
||||
params: { id: entry.id, /* título, autores, data, etc. */ },
|
||||
content: entry.content
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Apresente o conteúdo na página:
|
||||
|
||||
```md
|
||||
# {{ $params.title }}
|
||||
|
||||
- por {{ $params.author }} em {{ $params.date }}
|
||||
|
||||
<!-- @content -->
|
||||
```
|
||||
|
||||
## Guias de Integração {#integration-guides}
|
||||
|
||||
Se você tiver escrito um guia sobre como integrar VitePress com um CMS específico, por favor use o link "Edite esta página" abaixo para enviá-lo para cá!
|
||||
@ -0,0 +1,222 @@
|
||||
# Usando um Tema Personalizado {#using-a-custom-theme}
|
||||
|
||||
## Resolução de Tema {#theme-resolving}
|
||||
|
||||
Você pode habilitar um tema personalizado criando um arquivo `.vitepress/theme/index.js` ou `.vitepress/theme/index.ts` (o "arquivo de entrada do tema"):
|
||||
|
||||
```
|
||||
.
|
||||
├─ docs # raiz do projeto
|
||||
│ ├─ .vitepress
|
||||
│ │ ├─ theme
|
||||
│ │ │ └─ index.js # entrada do tema
|
||||
│ │ └─ config.js # arquivo de configuração
|
||||
│ └─ index.md
|
||||
└─ package.json
|
||||
```
|
||||
|
||||
VitePress sempre usará o tema personalizado em vez do tema padrão quando detectar a presença de um arquivo de entrada do tema. No entanto, você pode [estender o tema padrão](./extending-default-theme) para realizar personalizações avançadas sobre ele.
|
||||
|
||||
## Interface do Tema {#theme-interface}
|
||||
|
||||
Um tema personalizado do VitePress é definido como um objeto com a seguinte interface:
|
||||
|
||||
```ts
|
||||
interface Theme {
|
||||
/**
|
||||
* Componente raiz de layout para toda página
|
||||
* @required
|
||||
*/
|
||||
Layout: Component
|
||||
/**
|
||||
* Aprimora a instância da aplicação Vue
|
||||
* @optional
|
||||
*/
|
||||
enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
|
||||
/**
|
||||
* Estende outro tema, chamando seu `enhanceApp` antes do nosso
|
||||
* @optional
|
||||
*/
|
||||
extends?: Theme
|
||||
}
|
||||
|
||||
interface EnhanceAppContext {
|
||||
app: App // instância da aplicação Vue
|
||||
router: Router // instância do roteador VitePress
|
||||
siteData: Ref<SiteData> // Metadados do nível do site
|
||||
}
|
||||
```
|
||||
|
||||
O arquivo de entrada do tema deve exportar o tema como sua exportação padrão:
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
|
||||
// Você pode importar arquivos Vue diretamente no arquivo de entrada do tema
|
||||
// VitePress já está pré-configurado com @vitejs/plugin-vue.
|
||||
import Layout from './Layout.vue'
|
||||
|
||||
export default {
|
||||
Layout,
|
||||
enhanceApp({ app, router, siteData }) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A exportação padrão é o único contrato para um tema personalizado, e apenas a propriedade `Layout` é exigida. Tecnicamente, um tema do VitePress pode ser tão simples quanto um único componente Vue.
|
||||
|
||||
Dentro do seu componente de layout, ele funciona como uma aplicação Vite + Vue 3 normal. Note que o tema também precisa ser [compatível com SSR](./ssr-compat).
|
||||
|
||||
## Construindo um Layout {#building-a-layout}
|
||||
|
||||
O componente de layout mais básico precisa conter um componente [`<Content />`](../reference/runtime-api#content):
|
||||
|
||||
```vue
|
||||
<!-- .vitepress/theme/Layout.vue -->
|
||||
<template>
|
||||
<h1>Layout Personalizado!</h1>
|
||||
|
||||
<!-- aqui é onde o conteúdo markdown será apresentado -->
|
||||
<Content />
|
||||
</template>
|
||||
```
|
||||
|
||||
O layout acima simplesmente renderiza o markdown de toda página como HTML. A primeira melhoria que podemos adicionar é lidar com erros 404:
|
||||
|
||||
```vue{1-4,9-12}
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
const { page } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>Layout Personalizado!</h1>
|
||||
|
||||
<div v-if="page.isNotFound">
|
||||
Página 404 personalizada!
|
||||
</div>
|
||||
<Content v-else />
|
||||
</template>
|
||||
```
|
||||
|
||||
O auxiliar [`useData()`](../reference/runtime-api#usedata) fornece todos os dados em tempo de execução que precisamos para mostrar layouts diferentes. Um dos outros dados que podemos acessar é o frontmatter da página atual. Podemos aproveitar isso para permitir que o usuário final controle o layout em cada página. Por exemplo, o usuário pode indicar que a página deve usar um layout especial de página inicial com:
|
||||
|
||||
```md
|
||||
---
|
||||
layout: home
|
||||
---
|
||||
```
|
||||
|
||||
E podemos ajustar nosso tema para lidar com isso:
|
||||
|
||||
```vue{3,12-14}
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
const { page, frontmatter } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>Layout Personalizado!</h1>
|
||||
|
||||
<div v-if="page.isNotFound">
|
||||
Página 404 personalizada!
|
||||
</div>
|
||||
<div v-if="frontmatter.layout === 'home'">
|
||||
Página inicial personalizada!
|
||||
</div>
|
||||
<Content v-else />
|
||||
</template>
|
||||
```
|
||||
|
||||
Você pode, é claro, dividir o layout em mais componentes:
|
||||
|
||||
```vue{3-5,12-15}
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
import NotFound from './NotFound.vue'
|
||||
import Home from './Home.vue'
|
||||
import Page from './Page.vue'
|
||||
|
||||
const { page, frontmatter } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>Layout Personalizado!</h1>
|
||||
|
||||
<NotFound v-if="page.isNotFound" />
|
||||
<Home v-if="frontmatter.layout === 'home'" />
|
||||
<Page v-else /> <!-- <Page /> renders <Content /> -->
|
||||
</template>
|
||||
```
|
||||
|
||||
Consulte a [Referência da API em Tempo de Execução](../reference/runtime-api) para tudo que está disponível em componentes de tema. Além disso, você pode aproveitar [Carregamento de Dados em Tempo de Compilação](./data-loading) para gerar layouts orientados por dados - por exemplo, uma página que lista todas as postagens do blog no projeto atual.
|
||||
|
||||
## Distribuindo um Tema Personalizado {#distributing-a-custom-theme}
|
||||
|
||||
A maneira mais fácil de distribuir um tema personalizado é fornecê-lo como um [repositório de modelo no GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository).
|
||||
|
||||
Se você deseja distribuir seu tema como um pacote npm, siga estas etapas:
|
||||
|
||||
1. Exporte o objeto do tema como a exportação padrão no seu arquivo de pacote.
|
||||
|
||||
2. Se aplicável, exporte a definição de configuração de tipo do tema como `ThemeConfig`.
|
||||
|
||||
3. Se seu tema exigir ajustes na configuração VitePress, exporte essa configuração em um subdiretório do pacote (por exemplo, `meu-tema/config`) para que o usuário possa estendê-la.
|
||||
|
||||
4. Documente as opções de configuração do tema (tanto via arquivo de configuração quanto em frontmatter).
|
||||
|
||||
5. Forneça instruções claras sobre como consumir seu tema (veja abaixo).
|
||||
|
||||
## Consumindo um Tema Personalizado {#consuming-a-custom-theme}
|
||||
|
||||
Para consumir um tema externo, importe-o e reexporte-o a partir do arquivo de entrada do tema personalizado:
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import Theme from 'awesome-vitepress-theme'
|
||||
|
||||
export default Theme
|
||||
```
|
||||
|
||||
Se o tema precisar ser estendido:
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import Theme from 'awesome-vitepress-theme'
|
||||
|
||||
export default {
|
||||
extends: Theme,
|
||||
enhanceApp(ctx) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Se o tema exigir uma configuração especial do VitePress, você também precisará estendê-lo em sua própria configuração:
|
||||
|
||||
```ts
|
||||
// .vitepress/theme/config.ts
|
||||
import baseConfig from 'awesome-vitepress-theme/config'
|
||||
|
||||
export default {
|
||||
// estenda a configuração base do tema (se preciso)
|
||||
extends: baseConfig
|
||||
}
|
||||
```
|
||||
|
||||
Finalmente, se o tema fornecer tipos para a configuração do tema:
|
||||
|
||||
```ts
|
||||
// .vitepress/theme/config.ts
|
||||
import baseConfig from 'awesome-vitepress-theme/config'
|
||||
import { defineConfigWithTheme } from 'vitepress'
|
||||
import type { ThemeConfig } from 'awesome-vitepress-theme'
|
||||
|
||||
export default defineConfigWithTheme<ThemeConfig>({
|
||||
extends: baseConfig,
|
||||
themeConfig: {
|
||||
// O tipo é `ThemeConfig`
|
||||
}
|
||||
})
|
||||
```
|
||||
@ -0,0 +1,248 @@
|
||||
# Carregamento de Dados em Tempo de Compilação {#build-time-data-loading}
|
||||
|
||||
VitePress fornece um recurso chamado **carregadores de dado** que permite carregar dados arbitrários e importá-los de páginas ou de componentes. O carregamento de dados é executado **apenas no tempo da construção**: os dados resultantes serão serializados como JSON no pacote JavaScript final.
|
||||
|
||||
Os carregadores de dados podem ser usados para buscar dados remotos ou gerar metadados com base em arquivos locais. Por exemplo, você pode usar carregadores de dados para processar todas as suas páginas API locais e gerar automaticamente um índice de todas as entradas da API.
|
||||
|
||||
## Uso Básico {#basic-usage}
|
||||
|
||||
Um arquivo de carregador de dados deve terminar com `.data.js` ou `.data.ts`. O arquivo deve fornecer uma exportação padrão de um objeto com o método `load()`:
|
||||
|
||||
```js
|
||||
// example.data.js
|
||||
export default {
|
||||
load() {
|
||||
return {
|
||||
hello: 'world'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
O módulo do carregador é avaliado apenas no Node.js, então você pode importar APIs Node e dependências npm conforme necessário.
|
||||
|
||||
Você pode então importar dados deste arquivo em páginas `.md` e componentes `.vue` usando a exportação nomeada `data`:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { data } from './example.data.js'
|
||||
</script>
|
||||
|
||||
<pre>{{ data }}</pre>
|
||||
```
|
||||
|
||||
Saída:
|
||||
|
||||
```json
|
||||
{
|
||||
"hello": "world"
|
||||
}
|
||||
```
|
||||
|
||||
Você notará que o próprio carregador de dados não exporta o `data`. É o VitePress chamando o método `load()` nos bastidores e expondo implicitamente o resultado por meio da exportação nomeada `data`.
|
||||
|
||||
Isso funciona mesmo se o carregador for assíncrono:
|
||||
|
||||
```js
|
||||
export default {
|
||||
async load() {
|
||||
// buscar dados remotos
|
||||
return (await fetch('...')).json()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dados de Arquivos Locais {#data-from-local-files}
|
||||
|
||||
Quando você precisa gerar dados com base em arquivos locais, você deve usar a opção `watch` no carregador de dados para que as alterações feitas nesses arquivos possam acionar atualizações rápidas.
|
||||
|
||||
A opção `watch` também é conveniente porque você pode usar [padrões glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para corresponder a vários arquivos. Os padrões podem ser relativos ao próprio arquivo do carregador, e a função `load()` receberá os arquivos correspondentes como caminhos absolutos.
|
||||
|
||||
O exemplo a seguir mostra o carregamento de arquivos CSV e a transformação deles em JSON usando [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Como este arquivo só é executado no tempo da construção, você não enviará o procesador CSV para o cliente!
|
||||
|
||||
```js
|
||||
import fs from 'node:fs'
|
||||
import { parse } from 'csv-parse/sync'
|
||||
|
||||
export default {
|
||||
watch: ['./data/*.csv'],
|
||||
load(watchedFiles) {
|
||||
// watchedFiles será um array de caminhos absolutos dos arquivos correspondidos.
|
||||
// gerar um array de metadados de post que pode ser usada para mostrar
|
||||
// uma lista no layout do tema
|
||||
return watchedFiles.map((file) => {
|
||||
return parse(fs.readFileSync(file, 'utf-8'), {
|
||||
columns: true,
|
||||
skip_empty_lines: true
|
||||
})
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## `createContentLoader`
|
||||
|
||||
Ao construir um site focado em conteúdo, frequentemente precisamos criar uma página de "arquivo" ou "índice": uma página onde listamos todas as entradas disponíveis em nossa coleção de conteúdo, por exemplo, artigos de blog ou páginas de API. Nós **podemos** implementar isso diretamente com a API de carregador de dados, mas como este é um caso de uso tão comum, VitePress também fornece um auxiliar `createContentLoader` para simplificar isso:
|
||||
|
||||
```js
|
||||
// posts.data.js
|
||||
import { createContentLoader } from 'vitepress'
|
||||
|
||||
export default createContentLoader('posts/*.md', /* opções */)
|
||||
```
|
||||
|
||||
O auxiliar aceita um padrão glob relativo ao [diretório fonte](./routing#source-directory) e retorna um objeto de carregador de dados `{ watch, load }` que pode ser usado como exportação padrão em um arquivo de carregador de dados. Ele também implementa cache com base nos selos de data do arquivo para melhorar o desempenho no desenvolvimento.
|
||||
|
||||
Note que o carregador só funciona com arquivos Markdown - arquivos não-Markdown correspondidos serão ignorados.
|
||||
|
||||
Os dados carregados serão um _array_ com o tipo `ContentData[]`:
|
||||
|
||||
```ts
|
||||
interface ContentData {
|
||||
// URL mapeada para a página. Ex: /posts/hello.html (não inclui a base)
|
||||
// itere manualmente ou use `transform` personalizado para normalizar os caminhos
|
||||
url: string
|
||||
// dados frontmatter da página
|
||||
frontmatter: Record<string, any>
|
||||
|
||||
// os seguintes estão presentes apenas se as opções relevantes estiverem habilitadas
|
||||
// discutiremos sobre eles abaixo
|
||||
src: string | undefined
|
||||
html: string | undefined
|
||||
excerpt: string | undefined
|
||||
}
|
||||
```
|
||||
|
||||
Por padrão, apenas `url` e `frontmatter` são fornecidos. Isso ocorre porque os dados carregados serão incorporados como JSON no pacote do cliente, então precisamos ser cautelosos com seu tamanho. Aqui está um exemplo de como usar os dados para construir uma página de índice de blog mínima:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { data as posts } from './posts.data.js'
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>Todos os posts do blog</h1>
|
||||
<ul>
|
||||
<li v-for="post of posts">
|
||||
<a :href="post.url">{{ post.frontmatter.title }}</a>
|
||||
<span>por {{ post.frontmatter.author }}</span>
|
||||
</li>
|
||||
</ul>
|
||||
</template>
|
||||
```
|
||||
|
||||
### Opções {#options}
|
||||
|
||||
Os dados padrão podem não atender a todas as necessidades - você pode optar por transformar os dados usando opções:
|
||||
|
||||
```js
|
||||
// posts.data.js
|
||||
import { createContentLoader } from 'vitepress'
|
||||
|
||||
export default createContentLoader('posts/*.md', {
|
||||
includeSrc: true, // incluir fonte markdown crua?
|
||||
render: true, // incluir HTML completo da página apresentada?
|
||||
excerpt: true, // incluir excerto?
|
||||
transform(rawData) {
|
||||
// mapeie, ordene ou filtre os dados crus conforme quiser.
|
||||
// o resultado final é o que será enviado ao cliente.
|
||||
return rawData.sort((a, b) => {
|
||||
return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
|
||||
}).map((page) => {
|
||||
page.src // fonte markdown crua
|
||||
page.html // HTML completo da página apresentada
|
||||
page.excerpt // HTML do excerto apresentado (conteúdo acima do primeiro `---`)
|
||||
return {/* ... */}
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Veja como é usado no [blog Vue.js](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts).
|
||||
|
||||
A API `createContentLoader` também pode ser usada dentro dos [ganchos de construção](../reference/site-config#build-hooks):
|
||||
|
||||
```js
|
||||
// .vitepress/config.js
|
||||
export default {
|
||||
async buildEnd() {
|
||||
const posts = await createContentLoader('posts/*.md').load()
|
||||
// gerar arquivos com base nos metadados dos posts, por exemplo, feed RSS
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Tipos**
|
||||
|
||||
```ts
|
||||
interface ContentOptions<T = ContentData[]> {
|
||||
/**
|
||||
* Incluir src?
|
||||
* @default false
|
||||
*/
|
||||
includeSrc?: boolean
|
||||
|
||||
/**
|
||||
* Renderizar src para HTML e incluir nos dados?
|
||||
* @default false
|
||||
*/
|
||||
render?: boolean
|
||||
|
||||
/**
|
||||
* Se `boolean`, deve-se processar e incluir o resumo? (apresentado como HTML)
|
||||
*
|
||||
* Se `function`, controla como o excerto é extraído do conteúdo.
|
||||
*
|
||||
* Se `string`, define um separador personalizado a ser usado para extrair o
|
||||
* excerto. O separador padrão é `---` se `excerpt` for `true`.
|
||||
*
|
||||
* @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt
|
||||
* @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator
|
||||
*
|
||||
* @default false
|
||||
*/
|
||||
excerpt?:
|
||||
| boolean
|
||||
| ((file: { data: { [key: string]: any }; content: string; excerpt?: string }, options?: any) => void)
|
||||
| string
|
||||
|
||||
/**
|
||||
* Transforma os dados. Observe que os dados serão incorporados como JSON no pacote do cliente
|
||||
* se importados de componentes ou arquivos markdown.
|
||||
*/
|
||||
transform?: (data: ContentData[]) => T | Promise<T>
|
||||
}
|
||||
```
|
||||
|
||||
## Carregadores de Dados com Tipos {#typed-data-loaders}
|
||||
|
||||
Ao usar TypeScript, você pode tipar seu carregador e exportar `data` da seguinte forma:
|
||||
|
||||
```ts
|
||||
import { defineLoader } from 'vitepress'
|
||||
|
||||
export interface Data {
|
||||
// tipo de dado
|
||||
}
|
||||
|
||||
declare const data: Data
|
||||
export { data }
|
||||
|
||||
export default defineLoader({
|
||||
// opções do carregador verificadas pelo tipo
|
||||
watch: ['...'],
|
||||
async load(): Promise<Data> {
|
||||
// ...
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Configuração {#configuration}
|
||||
|
||||
Para obter as informações de configuração dentro de um carregador, você pode usar um código como este:
|
||||
|
||||
```ts
|
||||
import type { SiteConfig } from 'vitepress'
|
||||
|
||||
const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG
|
||||
```
|
||||
@ -0,0 +1,291 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Implante seu Site VitePress {#deploy-your-vitepress-site}
|
||||
|
||||
Os guias a seguir são baseados em alguns pressupostos:
|
||||
|
||||
- O site VitePress está dentro do diretório `docs` do seu projeto.
|
||||
- Você está usando o diretório de saída de compilação padrão (`.vitepress/dist`).
|
||||
- VitePress está instalado como uma dependência local em seu projeto, e você configurou os seguintes scripts em seu `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"docs:build": "vitepress build docs",
|
||||
"docs:preview": "vitepress preview docs"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Compilar e Testar Localmente {#build-and-test-locally}
|
||||
|
||||
1. Execute este comando para compilar a documentação:
|
||||
|
||||
```sh
|
||||
$ npm run docs:build
|
||||
```
|
||||
|
||||
2. Após a compilação, veja a prévia local executando:
|
||||
|
||||
```sh
|
||||
$ npm run docs:preview
|
||||
```
|
||||
|
||||
O comando `preview` inicializará um servidor web estático local que servirá o diretório de saída `.vitepress/dist` em `http://localhost:4173`. Você pode usar isso para garantir que tudo esteja correto antes de enviar para produção.
|
||||
|
||||
3. Você pode configurar a porta do servidor passando `--port` como argumento.
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"docs:preview": "vitepress preview docs --port 8080"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Agora o método `docs:preview` implantará o servidor em `http://localhost:8080`.
|
||||
|
||||
## Configurando um Caminho Base Público {#setting-a-public-base-path}
|
||||
|
||||
Por padrão, assumimos que o site será implantado no caminho raiz de um domínio (`/`). Se seu site for servido em um subcaminho, por exemplo, `https://meusite.com/blog/`, você precisa então configurar a opção [`base`](../reference/site-config#base) para `'/blog/'` na configuração VitePress.
|
||||
|
||||
**Exemplo:** Ao usar GitHub Pages (ou GitLab Pages) e implantar em `user.github.io/repo/`, defina seu `base` como `/repo/`.
|
||||
|
||||
## Cabeçalhos de Cache HTTP {#http-cache-headers}
|
||||
|
||||
Se você tiver controle sobre os cabeçalhos HTTP de seu servidor em produção, pode-se configurar cabeçalhos `cache-control` para obter melhor desempenho em visitas repetidas.
|
||||
|
||||
A compilação de produção usa nomes de arquivos com hash para ativos estáticos (JavaScript, CSS e outros ativos importados que não estão em `public`). Se você inspecionar a prévia de produção usando as ferramentas de desenvolvedor do seu nevegador na aba rede, verá arquivos como `app.4f283b18.js`.
|
||||
|
||||
Este hash `4f283b18` é gerado a partir do conteúdo deste arquivo. A mesma URL com hash é garantida para servir o mesmo conteúdo do arquivo - se o conteúdo mudar, as URLs também mudam. Isso significa que você pode usar com segurança os cabeçalhos de cache mais fortes para esses arquivos. Todos esses arquivos serão colocados em `assets/` no diretório de saída, então você pode configurar o seguinte cabeçalho para eles:
|
||||
|
||||
```
|
||||
Cache-Control: max-age=31536000,immutable
|
||||
```
|
||||
|
||||
::: details Exemplo de arquivo `_headers` do Netlify
|
||||
|
||||
```
|
||||
/assets/*
|
||||
cache-control: max-age=31536000
|
||||
cache-control: immutable
|
||||
```
|
||||
|
||||
Nota: o arquivo `_headers` deve ser colocado no [diretório public](./asset-handling#the-public-directory) - em nosso caso, `docs/public/_headers` - para que ele seja copiado exatamente para o diretório de saída.
|
||||
|
||||
[Documentação de cabeçalhos personalizados do Netlify](https://docs.netlify.com/routing/headers/)
|
||||
|
||||
:::
|
||||
|
||||
::: details Exemplo de configuração Vercel em `vercel.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"headers": [
|
||||
{
|
||||
"source": "/assets/(.*)",
|
||||
"headers": [
|
||||
{
|
||||
"key": "Cache-Control",
|
||||
"value": "max-age=31536000, immutable"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Nota: o arquivo `vercel.json` deve ser colocado na raiz do seu **repositório**.
|
||||
|
||||
[Documentação Vercel sobre configuração de cabeçalhos](https://vercel.com/docs/concepts/projects/project-configuration#headers)
|
||||
|
||||
:::
|
||||
|
||||
## Guias de Plataforma {#platform-guides}
|
||||
|
||||
### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render
|
||||
|
||||
Configure um novo projeto e altere estas configurações usando seu painel:
|
||||
|
||||
- **Comando de Compilação:** `npm run docs:build`
|
||||
- **Diretório de Saída:** `docs/.vitepress/dist`
|
||||
- **Versão do Node:** `18` (ou superior)
|
||||
|
||||
::: warning
|
||||
Não ative opções como _Auto Minify_ para código HTML. Isso removerá comentários da saída que têm significado para Vue. Haverão erros de incompatibilidade de hidratação se forem removidos.
|
||||
:::
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
1. Crie um arquivo chamado `deploy.yml` dentro do diretório `.github/workflows` do seu projeto com algum conteúdo como este:
|
||||
|
||||
```yaml
|
||||
# Exemplo de fluxo de trabalho para compilar e implantar um site VitePress no GitHub Pages
|
||||
#
|
||||
name: Implante o site VitePress no Pages
|
||||
|
||||
on:
|
||||
# Executa em pushes direcionados à branch `main`.
|
||||
# Altere para `master` se estiver usando a branch `master` como padrão.
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
# Permite executar manualmente este fluxo de trabalho na guia Actions
|
||||
workflow_dispatch:
|
||||
|
||||
# Define permissões GITHUB_TOKEN para a implantação no GitHub Pages
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# Permite apenas uma implantação simultânea, pulando execuções em fila entre a execução em andamento e a última da fila.
|
||||
# No entanto, NÃO cancela execuções em andamento, pois queremos permitir que essas implantações de produção sejam concluídas.
|
||||
concurrency:
|
||||
group: pages
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
# Trabalho de compilação
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0 # Não necessário se lastUpdated não estiver habilitado
|
||||
# - uses: pnpm/action-setup@v3 # Descomente isso se estiver usando pnpm
|
||||
# - uses: oven-sh/setup-bun@v1 # Descomente isso se estiver usando Bun
|
||||
- name: Setup Node
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: npm # ou pnpm / yarn
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v4
|
||||
- name: Install dependencies
|
||||
run: npm ci # ou pnpm install / yarn install / bun install
|
||||
- name: Build with VitePress
|
||||
run: |
|
||||
npm run docs:build # ou pnpm docs:build / yarn docs:build / bun run docs:build
|
||||
touch docs/.vitepress/dist/.nojekyll
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: docs/.vitepress/dist
|
||||
|
||||
# Trabalho de implantação
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
name: Deploy
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
::: warning
|
||||
Certifique-se de que a opção `base` em seu VitePress esteja configurada corretamente. Veja [Configurando um Caminho Base Público](#setting-a-public-base-path) para mais detalhes.
|
||||
:::
|
||||
|
||||
2. Nas configurações do seu repositório sob o item do menu "Pages", selecione "GitHub Actions" em "Build and deployment > Source".
|
||||
|
||||
3. Envie suas alterações para a branch `main` e aguarde a conclusão do fluxo de trabalho do GitHub Actions. Você verá seu site implantado em `https://<username>.github.io/[repository]/` ou `https://<custom-domain>/` dependendo das suas configurações. Seu site será implantado automaticamente em cada push para a branch `main`.
|
||||
|
||||
### GitLab Pages
|
||||
|
||||
1. Defina `outDir` na configuração VitePress como `../public`. Configure a opção `base` para `'/<repository>/'` se você deseja implantar em `https://<username>.gitlab.io/<repository>/`.
|
||||
|
||||
2. Crie um arquivo chamado `.gitlab-ci.yml` na raiz do seu projeto com o conteúdo abaixo. Isso construirá e implantará seu site sempre que você fizer alterações no conteúdo:
|
||||
|
||||
```yaml
|
||||
image: node:18
|
||||
pages:
|
||||
cache:
|
||||
paths:
|
||||
- node_modules/
|
||||
script:
|
||||
# - apk add git # Descomente isso se estiver usando imagens pequenas do Docker como o Alpine e tiver lastUpdated habilitado
|
||||
- npm install
|
||||
- npm run docs:build
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
only:
|
||||
- main
|
||||
```
|
||||
|
||||
### Azure Static Web Apps {#azure-static-web-apps}
|
||||
|
||||
1. Siga a [documentação oficial](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration).
|
||||
|
||||
2. Configure esses valores em seu arquivo de configuração (e remova aqueles que você não precisa, como `api_location`):
|
||||
|
||||
- **`app_location`**: `/`
|
||||
- **`output_location`**: `docs/.vitepress/dist`
|
||||
- **`app_build_command`**: `npm run docs:build`
|
||||
|
||||
### Firebase {#firebase}
|
||||
|
||||
1. Crie `firebase.json` e `.firebaserc` na raiz do seu projeto:
|
||||
|
||||
`firebase.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hosting": {
|
||||
"public": "docs/.vitepress/dist",
|
||||
"ignore": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`.firebaserc`:
|
||||
|
||||
```json
|
||||
{
|
||||
"projects": {
|
||||
"default": "<SEU_ID_FIREBASE>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Após executar `npm run docs:build`, execute este comando para implantar:
|
||||
|
||||
```sh
|
||||
firebase deploy
|
||||
```
|
||||
|
||||
### Surge
|
||||
|
||||
1. Após executar `npm run docs:build`, execute este comando para implantar:
|
||||
|
||||
```sh
|
||||
npx surge docs/.vitepress/dist
|
||||
```
|
||||
|
||||
### Heroku
|
||||
|
||||
1. Siga a documentação e o guia fornecidos em [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static).
|
||||
|
||||
2. Crie um arquivo chamado `static.json` na raiz do seu projeto com o conteúdo abaixo:
|
||||
|
||||
```json
|
||||
{
|
||||
"root": "docs/.vitepress/dist"
|
||||
}
|
||||
```
|
||||
|
||||
### Edgio
|
||||
|
||||
Consulte [Criar e Implantar um Aplicativo VitePress no Edgio](https://docs.edg.io/guides/vitepress).
|
||||
|
||||
### Kinsta Static Site Hosting {#kinsta-static-site-hosting}
|
||||
|
||||
Você pode implantar seu site Vitepress em [Kinsta](https://kinsta.com/static-site-hosting/) seguindo estas [instruções](https://kinsta.com/docs/vitepress-static-site-example/).
|
||||
@ -0,0 +1,340 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Estendendo o Tema Padrão {#extending-the-default-theme}
|
||||
|
||||
O tema padrão do VitePress é otimizado para documentação e pode ser personalizado. Consulte a [Visão Geral de Configuração do Tema Padrão](../reference/default-theme-config) para uma lista abrangente de opções.
|
||||
|
||||
No entanto, há casos em que apenas a configuração não será suficiente. Por exemplo:
|
||||
|
||||
1. É necessário ajustar a estilização CSS;
|
||||
2. É necessário modificar a instância da aplicação Vue, por exemplo para registrar componentes globais;
|
||||
3. É necessário injetar conteúdo personalizado no tema por meio de _slots_ no layout.
|
||||
|
||||
Essas personalizações avançadas exigirão o uso de um tema personalizado que "estende" o tema padrão.
|
||||
|
||||
::: tip
|
||||
Antes de prosseguir, certifique-se de ler primeiro [Usando um Tema Personalizado](./custom-theme) para entender como temas personalizados funcionam.
|
||||
:::
|
||||
|
||||
## Personalizando o CSS {#customizing-css}
|
||||
|
||||
O CSS do tema padrão pode ser personalizado substituindo as variáveis CSS no nível raiz:
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import './custom.css'
|
||||
|
||||
export default DefaultTheme
|
||||
```
|
||||
|
||||
```css
|
||||
/* .vitepress/theme/custom.css */
|
||||
:root {
|
||||
--vp-c-brand-1: #646cff;
|
||||
--vp-c-brand-2: #747bff;
|
||||
}
|
||||
```
|
||||
|
||||
Veja as [variáveis CSS do tema padrão](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) que podem ser substituídas.
|
||||
|
||||
## Usando Fontes Diferentes {#using-different-fonts}
|
||||
|
||||
VitePress usa [Inter](https://rsms.me/inter/) como fonte padrão e incluirá as fontes na saída de compilação. A fonte também é pré-carregada automaticamente em produção. No entanto, isso pode não ser desejável se você quiser usar uma fonte principal diferente.
|
||||
|
||||
Para evitar a inclusão de Inter na saída de compilação, importe o tema de `vitepress/theme-without-fonts`:
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import DefaultTheme from 'vitepress/theme-without-fonts'
|
||||
import './my-fonts.css'
|
||||
|
||||
export default DefaultTheme
|
||||
```
|
||||
|
||||
```css
|
||||
/* .vitepress/theme/custom.css */
|
||||
:root {
|
||||
--vp-font-family-base: /* fonte de texto normal */
|
||||
--vp-font-family-mono: /* fonte de código */
|
||||
}
|
||||
```
|
||||
|
||||
::: warning
|
||||
Se estiver usando componentes opcionais como os componentes da [Página da Equipe](../reference/default-theme-team-page), certifique-se de também importá-los de `vitepress/theme-without-fonts`!
|
||||
:::
|
||||
|
||||
Se a sua fonte é um arquivo local referenciado via `@font-face`, ela será processada como um ativo e incluída em `.vitepress/dist/assets` com um nome de arquivo hash. Para pré-carregar esse arquivo, use o gancho de construção [transformHead](../reference/site-config#transformhead):
|
||||
|
||||
```js
|
||||
// .vitepress/config.js
|
||||
export default {
|
||||
transformHead({ assets }) {
|
||||
// ajuste o regex para corresponder à sua fonte
|
||||
const myFontFile = assets.find(file => /font-name\.\w+\.woff2/)
|
||||
if (myFontFile) {
|
||||
return [
|
||||
[
|
||||
'link',
|
||||
{
|
||||
rel: 'preload',
|
||||
href: myFontFile,
|
||||
as: 'font',
|
||||
type: 'font/woff2',
|
||||
crossorigin: ''
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Registrando Componentes Globais {#registering-global-components}
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
|
||||
/** @type {import('vitepress').Theme} */
|
||||
export default {
|
||||
extends: DefaultTheme,
|
||||
enhanceApp({ app }) {
|
||||
// registre seus componentes globais personalizados
|
||||
app.component('MyGlobalComponent' /* ... */)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Se estiver usando TypeScript:
|
||||
```ts
|
||||
// .vitepress/theme/index.ts
|
||||
import type { Theme } from 'vitepress'
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
|
||||
export default {
|
||||
extends: DefaultTheme,
|
||||
enhanceApp({ app }) {
|
||||
// registre seus componentes globais personalizados
|
||||
app.component('MyGlobalComponent' /* ... */)
|
||||
}
|
||||
} satisfies Theme
|
||||
```
|
||||
|
||||
Como estamos usando Vite, você também pode aproveitar a [funcionalidade de importação glob](https://vitejs.dev/guide/features.html#glob-import) do Vite para registrar automaticamente um diretório de componentes.
|
||||
|
||||
## _Slots_ no Layout {#layout-slots}
|
||||
|
||||
O componente `<Layout/>` do tema padrão possui alguns _slots_ que podem ser usados para injetar conteúdo em locais específicos da página. Aqui está um exemplo de como injetar um componente antes do esquema :
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import MyLayout from './MyLayout.vue'
|
||||
|
||||
export default {
|
||||
extends: DefaultTheme,
|
||||
// substitua o Layout por um componente envolvente que
|
||||
// injeta os slots
|
||||
Layout: MyLayout
|
||||
}
|
||||
```
|
||||
|
||||
```vue
|
||||
<!--.vitepress/theme/MyLayout.vue-->
|
||||
<script setup>
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
|
||||
const { Layout } = DefaultTheme
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<Layout>
|
||||
<template #aside-outline-before>
|
||||
Meu conteúdo personalizado superior da barra lateral
|
||||
</template>
|
||||
</Layout>
|
||||
</template>
|
||||
```
|
||||
|
||||
Ou você também pode usar a função _render_.
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
import { h } from 'vue'
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import MyComponent from './MyComponent.vue'
|
||||
|
||||
export default {
|
||||
extends: DefaultTheme,
|
||||
Layout() {
|
||||
return h(DefaultTheme.Layout, null, {
|
||||
'aside-outline-before': () => h(MyComponent)
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Lista completa de _slots_ disponíveis no layout do tema padrão:
|
||||
|
||||
- Quando `layout: 'doc'` (padrão) está habilitado via frontmatter:
|
||||
- `doc-top`
|
||||
- `doc-bottom`
|
||||
- `doc-footer-before`
|
||||
- `doc-before`
|
||||
- `doc-after`
|
||||
- `sidebar-nav-before`
|
||||
- `sidebar-nav-after`
|
||||
- `aside-top`
|
||||
- `aside-bottom`
|
||||
- `aside-outline-before`
|
||||
- `aside-outline-after`
|
||||
- `aside-ads-before`
|
||||
- `aside-ads-after`
|
||||
- Quando `layout: 'home'` está habilitado via frontmatter:
|
||||
- `home-hero-before`
|
||||
- `home-hero-info-before`
|
||||
- `home-hero-info`
|
||||
- `home-hero-actions-after`
|
||||
- `home-hero-image`
|
||||
- `home-hero-after`
|
||||
- `home-features-before`
|
||||
- `home-features-after`
|
||||
- Quando `layout: 'page'` está habilitado via frontmatter:
|
||||
- `page-top`
|
||||
- `page-bottom`
|
||||
- Na página não encontrada (404):
|
||||
- `not-found`
|
||||
- Sempre:
|
||||
- `layout-top`
|
||||
- `layout-bottom`
|
||||
- `nav-bar-title-before`
|
||||
- `nav-bar-title-after`
|
||||
- `nav-bar-content-before`
|
||||
- `nav-bar-content-after`
|
||||
- `nav-screen-content-before`
|
||||
- `nav-screen-content-after`
|
||||
|
||||
## Usando a API View Transitions
|
||||
|
||||
### Na Alternância de Aparência {#on-appearance-toggle}
|
||||
|
||||
Você pode estender o tema padrão para fornecer uma transição personalizada quando o modo de cor é alternado. Um exemplo:
|
||||
|
||||
```vue
|
||||
<!-- .vitepress/theme/Layout.vue -->
|
||||
|
||||
<script setup lang="ts">
|
||||
import { useData } from 'vitepress'
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import { nextTick, provide } from 'vue'
|
||||
|
||||
const { isDark } = useData()
|
||||
|
||||
const enableTransitions = () =>
|
||||
'startViewTransition' in document &&
|
||||
window.matchMedia('(prefers-reduced-motion: no-preference)').matches
|
||||
|
||||
provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
|
||||
if (!enableTransitions()) {
|
||||
isDark.value = !isDark.value
|
||||
return
|
||||
}
|
||||
|
||||
const clipPath = [
|
||||
`circle(0px at ${x}px ${y}px)`,
|
||||
`circle(${Math.hypot(
|
||||
Math.max(x, innerWidth - x),
|
||||
Math.max(y, innerHeight - y)
|
||||
)}px at ${x}px ${y}px)`
|
||||
]
|
||||
|
||||
await document.startViewTransition(async () => {
|
||||
isDark.value = !isDark.value
|
||||
await nextTick()
|
||||
}).ready
|
||||
|
||||
document.documentElement.animate(
|
||||
{ clipPath: isDark.value ? clipPath.reverse() : clipPath },
|
||||
{
|
||||
duration: 300,
|
||||
easing: 'ease-in',
|
||||
pseudoElement: `::view-transition-${isDark.value ? 'old' : 'new'}(root)`
|
||||
}
|
||||
)
|
||||
})
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<DefaultTheme.Layout />
|
||||
</template>
|
||||
|
||||
<style>
|
||||
::view-transition-old(root),
|
||||
::view-transition-new(root) {
|
||||
animation: none;
|
||||
mix-blend-mode: normal;
|
||||
}
|
||||
|
||||
::view-transition-old(root),
|
||||
.dark::view-transition-new(root) {
|
||||
z-index: 1;
|
||||
}
|
||||
|
||||
::view-transition-new(root),
|
||||
.dark::view-transition-old(root) {
|
||||
z-index: 9999;
|
||||
}
|
||||
|
||||
.VPSwitchAppearance {
|
||||
width: 22px !important;
|
||||
}
|
||||
|
||||
.VPSwitchAppearance .check {
|
||||
transform: none !important;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
Resultado (**atenção!**: cores piscantes, movimentos súbitos, luzes brilhantes):
|
||||
|
||||
<details>
|
||||
<summary>Demo</summary>
|
||||
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
Consulte [Chrome Docs](https://developer.chrome.com/docs/web-platform/view-transitions/) para mais detalhes sobre _view transitions_.
|
||||
|
||||
### Na Mudança de Rota {#on-route-change}
|
||||
|
||||
Em breve.
|
||||
|
||||
## Substituindo Componentes Internos {#overriding-internal-components}
|
||||
|
||||
Você pode usar os [aliases](https://vitejs.dev/config/shared-options.html#resolve-alias) Vite para substituir os componentes do tema padrão pelos seus personalizados:
|
||||
|
||||
```ts
|
||||
import { fileURLToPath, URL } from 'node:url'
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
vite: {
|
||||
resolve: {
|
||||
alias: [
|
||||
{
|
||||
find: /^.*\/VPNavBar\.vue$/,
|
||||
replacement: fileURLToPath(
|
||||
new URL('./components/CustomNavBar.vue', import.meta.url)
|
||||
)
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Para saber o nome exato do componente consulte [nosso código fonte](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components). Como os componentes são internos, há uma pequena chance de que o nome deles seja atualizado entre lançamentos secundários.
|
||||
@ -0,0 +1,48 @@
|
||||
# Frontmatter
|
||||
|
||||
## Utilização {#usage}
|
||||
|
||||
VitePress suporta frontmatter YAML em todos os arquivos Markdown, processando-os com [gray-matter](https://github.com/jonschlinkert/gray-matter). O frontmatter deve estar no topo do arquivo Markdown (antes de qualquer elemento, incluindo tags `<script>`), e deve ter a forma de um YAML válido entre linhas com traços triplos. Exemplo:
|
||||
|
||||
```md
|
||||
---
|
||||
title: Documentação com VitePress
|
||||
editLink: true
|
||||
---
|
||||
```
|
||||
|
||||
Muitas opções de configuração do site ou do tema padrão têm opções correspondentes no frontmatter. Você pode usar o frontmatter para sobrepor um comportamento específico apenas para a página atual. Para mais detalhes, veja [Referência de Configuração do Frontmatter](../reference/frontmatter-config).
|
||||
|
||||
Você também pode definir dados próprios frontmatter personalizados, para serem usados em expressões Vue dinâmicas na página.
|
||||
|
||||
## Acesso aos Dados do Frontmatter {#accessing-frontmatter-data}
|
||||
|
||||
Os dados do frontmatter podem ser acessados por meio da variável global especial `$frontmatter`:
|
||||
|
||||
Aqui está um exemplo de como você poderia usá-lo em seu arquivo Markdown:
|
||||
|
||||
```md
|
||||
---
|
||||
title: Documentação com VitePress
|
||||
editLink: true
|
||||
---
|
||||
|
||||
# {{ $frontmatter.title }}
|
||||
|
||||
Conteúdo do guia
|
||||
```
|
||||
|
||||
Você também pode acessar os dados do frontmatter da página atual em `<script setup>` com o auxiliar [`useData()`](../reference/runtime-api#usedata).
|
||||
|
||||
## Formatos Alternativos do Frontmatter {#alternative-frontmatter-formats}
|
||||
|
||||
VitePress também suporta a sintaxe frontmatter JSON, começando e terminando com chaves:
|
||||
|
||||
```json
|
||||
---
|
||||
{
|
||||
"title": "Criando blog como um hacker",
|
||||
"editLink": true
|
||||
}
|
||||
---
|
||||
```
|
||||
@ -0,0 +1,216 @@
|
||||
# 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 [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).
|
||||
@ -0,0 +1,113 @@
|
||||
# Internacionalização {#internationalization}
|
||||
|
||||
Para usar recursos de i18n integrados, é necessário criar uma estrutura de diretórios da seguinte forma:
|
||||
|
||||
```
|
||||
docs/
|
||||
├─ es/
|
||||
│ ├─ foo.md
|
||||
├─ fr/
|
||||
│ ├─ foo.md
|
||||
├─ foo.md
|
||||
```
|
||||
|
||||
Em seguida, no arquivo `docs/.vitepress/config.ts`:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
// propriedades compartilhadas e outras coisas de nível superior...
|
||||
|
||||
locales: {
|
||||
root: {
|
||||
label: 'English',
|
||||
lang: 'en'
|
||||
},
|
||||
fr: {
|
||||
label: 'French',
|
||||
lang: 'fr', // opcional, será adicionado como atributo `lang` na tag `html`
|
||||
link: '/fr/guide' // padrão /fr/ -- aparece no menu de traduções da barra de navegação, pode ser externo
|
||||
|
||||
// outras propriedades específicas de cada idioma...
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
As seguintes propriedades podem ser substituídas para cada idioma (incluindo a raiz):
|
||||
|
||||
```ts
|
||||
interface LocaleSpecificConfig<ThemeConfig = any> {
|
||||
lang?: string
|
||||
dir?: string
|
||||
title?: string
|
||||
titleTemplate?: string | boolean
|
||||
description?: string
|
||||
head?: HeadConfig[] // será mesclado com as entradas head existentes, as metatags duplicadas são removidas automaticamente
|
||||
themeConfig?: ThemeConfig // será mesclado superficialmente, coisas comuns podem ser colocadas na entrada de n[ivel superior de themeConfig
|
||||
}
|
||||
```
|
||||
|
||||
Consulte a interface [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) para obter detalhes sobre a personalização dos textos marcadores do tema padrão. Não substitua `themeConfig.algolia` ou `themeConfig.carbonAds` no nível do idioma. Consulte a [documentação Algolia](../reference/default-theme-search#i18n) para usar a pesquisa multilínguas.
|
||||
|
||||
**Dica profissional:** O arquivo de configuração pode ser armazenado em `docs/.vitepress/config/index.ts` também. Isso pode ajudar a organizar as coisas criando um arquivo de configuração por idioma e então mesclá-los e exportá-los a partir de `index.ts`.
|
||||
|
||||
## Diretório separado para cada localização {#separate-directory-for-each-locale}
|
||||
|
||||
A seguinte estrutura é totalmente válida:
|
||||
|
||||
```
|
||||
docs/
|
||||
├─ en/
|
||||
│ ├─ foo.md
|
||||
├─ es/
|
||||
│ ├─ foo.md
|
||||
├─ fr/
|
||||
├─ foo.md
|
||||
```
|
||||
|
||||
No entanto, VitePress não redirecionará `/` para `/en/` por padrão. Você precisará configurar seu servidor para isso. Por exemplo, no Netlify, você pode adicionar um arquivo `docs/public/_redirects` assim:
|
||||
|
||||
```
|
||||
/* /es/:splat 302 Language=es
|
||||
/* /fr/:splat 302 Language=fr
|
||||
/* /en/:splat 302
|
||||
```
|
||||
|
||||
**Dica profissional:** Se estiver usando a abordagem acima, você pode usar o cookie `nf_lang` para persistir a escolha de idioma do usuário:
|
||||
|
||||
```ts
|
||||
// docs/.vitepress/theme/index.ts
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import Layout from './Layout.vue'
|
||||
|
||||
export default {
|
||||
extends: DefaultTheme,
|
||||
Layout
|
||||
}
|
||||
```
|
||||
|
||||
```vue
|
||||
<!-- docs/.vitepress/theme/Layout.vue -->
|
||||
<script setup lang="ts">
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import { useData } from 'vitepress'
|
||||
import { watchEffect } from 'vue'
|
||||
|
||||
const { lang } = useData()
|
||||
watchEffect(() => {
|
||||
if (inBrowser) {
|
||||
document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2030 00:00:00 UTC; path=/`
|
||||
}
|
||||
})
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<DefaultTheme.Layout />
|
||||
</template>
|
||||
```
|
||||
|
||||
## Suporte a RTL (Experimental) {#rtl-support-experimental}
|
||||
|
||||
Para suporte a RTL (Right to Left), especifique `dir: 'rtl'` na configuração e use algum plugin RTLCSS PostCSS como <https://github.com/MohammadYounes/rtlcss>, <https://github.com/vkalinichev/postcss-rtl> ou <https://github.com/elchininet/postcss-rtlcss>. Você precisará configurar seu plugin PostCSS para usar `:where([dir="ltr"])` e `:where([dir="rtl"])` como prefixos para evitar problemas de especificidade CSS.
|
||||
@ -0,0 +1,929 @@
|
||||
# Extensões Markdown {#markdown-extensions}
|
||||
|
||||
VitePress vem com Extensões Markdown embutidas.
|
||||
|
||||
## Âncoras de Cabeçalho {#header-anchors}
|
||||
|
||||
Cabeçalhos recebem a aplicação automaticamente de links âncora. A apresentação das âncoras pode ser configurada usando a opção `markdown.anchor`.
|
||||
|
||||
### Âncoras personalizadas {#custom-anchors}
|
||||
|
||||
Para especificar uma _tag_ âncora personalizada para um cabeçalho em vez de usar aquela gerada automaticamente, adicione um sufixo ao cabeçalho:
|
||||
|
||||
```
|
||||
# Usando âncoras personalizadas {#minha-ancora}
|
||||
```
|
||||
|
||||
Isso permite que você tenha um link do cabeçalho como `#minha-ancora` em vez do padrão `#usando-ancoras-personalizadas`.
|
||||
|
||||
## Links {#links}
|
||||
|
||||
Ambos os links internos e externos recebem tratamento especial.
|
||||
|
||||
### Links Internos {#internal-links}
|
||||
|
||||
Os links internos são convertidos em links de roteador para navegação SPA. Além disso, todo arquivo `index.md` contido em cada subdiretório será automaticamente convertido para `index.html`, com a URL correspondente `/`.
|
||||
|
||||
Por exemplo, dada a seguinte estrutura de diretórios:
|
||||
|
||||
```
|
||||
.
|
||||
├─ index.md
|
||||
├─ foo
|
||||
│ ├─ index.md
|
||||
│ ├─ one.md
|
||||
│ └─ two.md
|
||||
└─ bar
|
||||
├─ index.md
|
||||
├─ three.md
|
||||
└─ four.md
|
||||
```
|
||||
|
||||
E supondo que você esteja em `foo/one.md`:
|
||||
|
||||
```md
|
||||
[Página Inicial](/) <!-- leva o usuário ao index.md raiz -->
|
||||
[foo](/foo/) <!-- leva o usuário ao index.html do diretório foo -->
|
||||
[foo heading](./#heading) <!-- ancora o usuário a um cabeçalho do arquivo índice foo -->
|
||||
[bar - three](../bar/three) <!-- você pode omitir a extensão -->
|
||||
[bar - three](../bar/three.md) <!-- você pode adicionar .md -->
|
||||
[bar - four](../bar/four.html) <!-- ou você pode adicionar .html -->
|
||||
```
|
||||
|
||||
### Sufixo de Página {#page-suffix}
|
||||
|
||||
Páginas e links internos são gerados com o sufixo `.html` por padrão.
|
||||
|
||||
### Links Externos {#external-links}
|
||||
|
||||
Links externos recebem automaticamente `target="_blank" rel="noreferrer"`:
|
||||
|
||||
- [vuejs.org](https://vuejs.org)
|
||||
- [VitePress no GitHub](https://github.com/vuejs/vitepress)
|
||||
|
||||
## Frontmatter {#frontmatter}
|
||||
|
||||
[YAML frontmatter](https://jekyllrb.com/docs/front-matter/) é suportado por padrão:
|
||||
|
||||
```yaml
|
||||
---
|
||||
título: Escrevendo como um Hacker
|
||||
idioma: pt-BR
|
||||
---
|
||||
```
|
||||
|
||||
Esses dados estarão disponíveis para o restante da página, junto com todos os componentes personalizados e de temas.
|
||||
|
||||
Para mais detalhes, veja [Frontmatter](../reference/frontmatter-config).
|
||||
|
||||
## Tabelas ao Estilo GitHub {#github-style-tables}
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
| Tabelas | São | Legais |
|
||||
| ------------- | :-----------: | ----: |
|
||||
| col 3 está | à direita | $1600 |
|
||||
| col 2 está | centralizada | $12 |
|
||||
| listras | são legais | $1 |
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
| Tabelas | São | Legais |
|
||||
| ------------- | :-----------: | -----: |
|
||||
| col 3 está | à direita | \$1600 |
|
||||
| col 2 está | centralizada | \$12 |
|
||||
| listras | são legais | \$1 |
|
||||
|
||||
## Emoji :tada:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```
|
||||
:tada: :100:
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
:tada: :100:
|
||||
|
||||
Uma [lista de todos os emojis](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs) está disponível.
|
||||
|
||||
## Tabela de Conteúdo (TOC)
|
||||
|
||||
**Entrada**
|
||||
|
||||
```
|
||||
[[toc]]
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
[[toc]]
|
||||
|
||||
A apresentação de TOC (Table of Contents) pode ser configurada usando a opção `markdown.toc`.
|
||||
|
||||
## Recipientes Personalizados {#custom-containers}
|
||||
|
||||
Recipientes personalizados podem ser definidos por seus tipos, títulos e conteúdos.
|
||||
|
||||
### Título Padrão {#default-title}
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
::: info
|
||||
Este é um bloco de informações.
|
||||
:::
|
||||
|
||||
::: tip
|
||||
Este é um aviso.
|
||||
:::
|
||||
|
||||
::: warning
|
||||
Este é um aviso.
|
||||
:::
|
||||
|
||||
::: danger
|
||||
Este é um aviso de perigo.
|
||||
:::
|
||||
|
||||
::: details
|
||||
Este é um bloco de detalhes.
|
||||
:::
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
::: info
|
||||
Este é um bloco de informações.
|
||||
:::
|
||||
|
||||
::: tip
|
||||
Este é um aviso.
|
||||
:::
|
||||
|
||||
::: warning
|
||||
Este é um aviso.
|
||||
:::
|
||||
|
||||
::: danger
|
||||
Este é um aviso de perigo.
|
||||
:::
|
||||
|
||||
::: details
|
||||
Este é um bloco de detalhes.
|
||||
:::
|
||||
|
||||
### Título Personalizado {#custom-title}
|
||||
|
||||
Você pode definir um título personalizado adicionando o texto imediatamente após o "tipo" do recipiente.
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
::: danger STOP
|
||||
Zona de perigo, não prossiga
|
||||
:::
|
||||
|
||||
::: details Clique para ver o código
|
||||
```js
|
||||
console.log('Olá, VitePress!')
|
||||
```
|
||||
:::
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
::: danger STOP
|
||||
Zona de perigo, não prossiga
|
||||
:::
|
||||
|
||||
::: details Clique para ver o código
|
||||
```js
|
||||
console.log('Olá, VitePress!')
|
||||
```
|
||||
:::
|
||||
|
||||
Além disso, você pode definir títulos personalizados globalmente adicionando o seguinte conteúdo no arquivo de configuração do site, útil se não estiver escrevendo em inglês:
|
||||
|
||||
```ts
|
||||
// config.ts
|
||||
export default defineConfig({
|
||||
// ...
|
||||
markdown: {
|
||||
container: {
|
||||
tipLabel: '提示',
|
||||
warningLabel: '警告',
|
||||
dangerLabel: '危险',
|
||||
infoLabel: '信息',
|
||||
detailsLabel: '详细信息'
|
||||
}
|
||||
}
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### `raw`
|
||||
|
||||
Este é um recipiente especial que pode ser usado para evitar conflitos de estilo e roteador com VitePress. Isso é especialmente útil ao documentar bibliotecas de componentes. Você também pode verificar [whyframe](https://whyframe.dev/docs/integrations/vitepress) para melhor isolamento.
|
||||
|
||||
**Sintaxe**
|
||||
|
||||
```md
|
||||
::: raw
|
||||
Envolve em um <div class="vp-raw">
|
||||
:::
|
||||
```
|
||||
|
||||
A classe `vp-raw` também pode ser usada diretamente em elementos. O isolamento de estilo é atualmente opcional:
|
||||
|
||||
- Instale o `postcss` com seu gerenciador de pacotes preferido:
|
||||
|
||||
```sh
|
||||
$ npm add -D postcss
|
||||
```
|
||||
|
||||
- Crie um arquivo chamado `docs/postcss.config.mjs` e adicione o seguinte:
|
||||
|
||||
```js
|
||||
import { postcssIsolateStyles } from 'vitepress'
|
||||
|
||||
export default {
|
||||
plugins: [postcssIsolateStyles()]
|
||||
}
|
||||
```
|
||||
|
||||
Ele utiliza [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config) internamente. Você pode passar opções assim:
|
||||
|
||||
```js
|
||||
postcssIsolateStyles({
|
||||
includeFiles: [/vp-doc\.css/] // o padrão é /base\.css/
|
||||
})
|
||||
```
|
||||
|
||||
## Alertas no estilo GitHub {#github-flavored-alerts}
|
||||
|
||||
VitePress também suporta [alertas no estilo GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) para apresentar como um bloco de chamada. Eles serão apresentados da mesma forma que [elementos personalizados](#custom-containers).
|
||||
|
||||
```md
|
||||
> [!NOTE]
|
||||
> Destaca informações que os usuários devem levar em consideração, mesmo ao ler rapidamente.
|
||||
|
||||
> [!TIP]
|
||||
> Informações opcionais para ajudar o usuário a ter mais sucesso.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Informações cruciais necessárias para que os usuários tenham sucesso.
|
||||
|
||||
> [!WARNING]
|
||||
> Conteúdo crítico exigindo atenção imediata do usuário devido a riscos potenciais.
|
||||
|
||||
> [!CAUTION]
|
||||
> Potenciais consequências negativas de uma ação.
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Destaca informações que os usuários devem levar em consideração, mesmo ao ler rapidamente.
|
||||
|
||||
> [!TIP]
|
||||
> Informações opcionais para ajudar o usuário a ter mais sucesso.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Informações cruciais necessárias para que os usuários tenham sucesso.
|
||||
|
||||
> [!WARNING]
|
||||
> Conteúdo crítico exigindo atenção imediata do usuário devido a riscos potenciais.
|
||||
|
||||
> [!CAUTION]
|
||||
> Potenciais consequências negativas de uma ação.
|
||||
|
||||
## Destaque de Sintaxe em Blocos de Código {#syntax-highlighting-in-code-blocks}
|
||||
|
||||
VitePress utiliza [Shiki](https://github.com/shikijs/shiki) para destacar a sintaxe da linguagem em blocos de código Markdown, usando texto colorido. Shiki suporta uma ampla variedade de linguagens de programação. Tudo o que você precisa fazer é adicionar um _alias_ de linguagem válido após os crases iniciais do bloco de código:
|
||||
|
||||
**Entrada**
|
||||
|
||||
````
|
||||
```js
|
||||
export default {
|
||||
name: 'MyComponent',
|
||||
// ...
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
````
|
||||
```html
|
||||
<ul>
|
||||
<li v-for="todo in todos" :key="todo.id">
|
||||
{{ todo.text }}
|
||||
</li>
|
||||
</ul>
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js
|
||||
export default {
|
||||
name: 'MyComponent'
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li v-for="todo in todos" :key="todo.id">
|
||||
{{ todo.text }}
|
||||
</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
Uma [lista de linguagens válidas](https://shiki.style/languages) está disponível no repositório Shiki.
|
||||
|
||||
Você também pode personalizar o tema de destaque de sintaxe na configuração do aplicativo. Consulte as [opções `markdown`](../reference/site-config#markdown) para mais detalhes.
|
||||
|
||||
## Destaque de Linha em Blocos de Código {#line-highlighting-in-code-blocks}
|
||||
|
||||
**Entrada**
|
||||
|
||||
````
|
||||
```js{4}
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Destacado!'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js{4}
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Destacado!'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Além de uma única linha, você também pode especificar múltiplas linhas únicas, intervalos, ou ambos:
|
||||
|
||||
- Intervalos de linha: por exemplo, `{5-8}`, `{3-10}`, `{10-17}`
|
||||
- Múltiplas linhas únicas: por exemplo, `{4,7,9}`
|
||||
- Intervalos de linha e linhas únicas: por exemplo, `{4,7-13,16,23-27,40}`
|
||||
|
||||
**Entrada**
|
||||
|
||||
````
|
||||
```js{1,4,6-8}
|
||||
export default { // Destacado
|
||||
data () {
|
||||
return {
|
||||
msg: `Destacado!
|
||||
Esta linha não está destacada,
|
||||
mas esta e as próximas 2 estão.`,
|
||||
motd: 'VitePress é incrível',
|
||||
lorem: 'ipsum'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js{1,4,6-8}
|
||||
export default { // Destacado
|
||||
data () {
|
||||
return {
|
||||
msg: `Destacado!
|
||||
Esta linha não está destacada,
|
||||
mas esta e as próximas 2 estão.`,
|
||||
motd: 'VitePress é incrível',
|
||||
lorem: 'ipsum',
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Alternativamente, é possível destacar diretamente na linha usando o comentário `// [!code highlight]`.
|
||||
|
||||
**Entrada**
|
||||
|
||||
````
|
||||
```js
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Destacado!' // [!!code highlight]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
msg: 'Destacado!' // [!code destaque]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Foco em Blocos de Código {#focus-in-code-blocks}
|
||||
|
||||
Adicionando o comentário `// [!code focus]` em uma linha irá destacá-la e desfocar as outras partes do código.
|
||||
|
||||
Além disso, você pode definir o número de linhas para focar usando `// [!code focus:<linhas>]`.
|
||||
|
||||
**Entrada**
|
||||
|
||||
````
|
||||
```js
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Focado!' // [!!code focus]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
msg: 'Focado!' // [!code focus]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Diferenças Coloridas em Blocos de Código {#colored-diffs-in-code-blocks}
|
||||
|
||||
Adicionar os comentários `// [!code --]` ou `// [!code ++]` em uma linha criará uma diferença nessa linha, mantendo as cores do bloco de código.
|
||||
|
||||
**Entrada**
|
||||
|
||||
````
|
||||
```js
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Removido' // [!!code --]
|
||||
msg: 'Adicionado' // [!!code ++]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Removido' // [!code --]
|
||||
msg: 'Adicionado' // [!code ++]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Erros e Avisos em Blocos de Código {#errors-and-warnings-in-code-blocks}
|
||||
|
||||
Adicionar os comentários `// [!code warning]` ou `// [!code error]` em uma linha colorirá os blocos conforme apropriado.
|
||||
|
||||
**Entrada**
|
||||
|
||||
````
|
||||
```js
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Erro', // [!!code error]
|
||||
msg: 'Aviso' // [!!code warning]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
msg: 'Erro', // [!code error]
|
||||
msg: 'Aviso' // [!code warning]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Números de Linha {#line-numbers}
|
||||
|
||||
Você pode habilitar números de linha para cada bloco de código através do arquivo de configuração:
|
||||
|
||||
```js
|
||||
export default {
|
||||
markdown: {
|
||||
lineNumbers: true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Consulte as [opções markdown](../reference/site-config#markdown) para mais detalhes.
|
||||
|
||||
Você pode adicionar a marca `:line-numbers` / `:no-line-numbers` em seus blocos de código para substituir o valor definido na configuração.
|
||||
|
||||
Você também pode personalizar o número inicial da linha adicionando `=` após `:line-numbers`. Por exemplo, `:line-numbers=2` significa que os números das linhas nos blocos de código começarão a partir de `2`.
|
||||
|
||||
**Entrada**
|
||||
|
||||
````md
|
||||
```ts {1}
|
||||
// números de linha desativados por padrão
|
||||
const line2 = 'Esta é a linha 2'
|
||||
const line3 = 'Esta é a linha 3'
|
||||
```
|
||||
|
||||
```ts:line-numbers {1}
|
||||
// números de linha ativados
|
||||
const line2 = 'Esta é a linha 2'
|
||||
const line3 = 'Esta é a linha 3'
|
||||
```
|
||||
|
||||
```ts:line-numbers=2 {1}
|
||||
// números de linha ativados e começam do 2
|
||||
const line3 = 'Esta é a linha 3'
|
||||
const line4 = 'Esta é a linha 4'
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```ts {1}
|
||||
// números de linha desativados por padrão
|
||||
const line2 = 'Esta é a linha 2'
|
||||
const line3 = 'Esta é a linha 3'
|
||||
```
|
||||
|
||||
```ts:line-numbers {1}
|
||||
// números de linha ativados
|
||||
const line2 = 'Esta é a linha 2'
|
||||
const line3 = 'Esta é a linha 3'
|
||||
```
|
||||
|
||||
```ts:line-numbers=2 {1}
|
||||
// números de linha ativados e começam do 2
|
||||
const line3 = 'Esta é a linha 3'
|
||||
const line4 = 'Esta é a linha 4'
|
||||
```
|
||||
|
||||
## Importar _Snippets_ de Código {#import-code-snippets}
|
||||
|
||||
Você pode importar trechos de código de arquivos existentes usando a seguinte sintaxe:
|
||||
|
||||
```md
|
||||
<<< @/filepath
|
||||
```
|
||||
|
||||
Também suporta [destaque de linha](#line-highlighting-in-code-blocks):
|
||||
|
||||
```md
|
||||
<<< @/filepath{highlightLines}
|
||||
```
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
<<< @/snippets/snippet.js{2}
|
||||
```
|
||||
|
||||
**Arquivo de Código**
|
||||
|
||||
<<< @/snippets/snippet.js
|
||||
|
||||
**Saída**
|
||||
|
||||
<<< @/snippets/snippet.js{2}
|
||||
|
||||
::: dica
|
||||
O valor de `@` corresponde à raiz do código fonte. Por padrão, é a raiz do projeto VitePress, a menos que `srcDir` seja configurado. Alternativamente, você também pode importar de caminhos relativos:
|
||||
|
||||
```md
|
||||
<<< ../snippets/snippet.js
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
Você também pode usar uma [região VS Code](https://code.visualstudio.com/docs/editor/codebasics#_folding) para incluir apenas a parte correspondente do arquivo de código. Você pode fornecer um nome de região personalizado após um `#` seguindo o caminho do arquivo:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
<<< @/snippets/snippet-with-region.js#snippet{1}
|
||||
```
|
||||
|
||||
**Arquivo de Código**
|
||||
|
||||
<<< @/snippets/snippet-with-region.js
|
||||
|
||||
**Saída**
|
||||
|
||||
<<< @/snippets/snippet-with-region.js#snippet{1}
|
||||
|
||||
Você também pode especificar o idioma dentro das chaves (`{}`), assim:
|
||||
|
||||
```md
|
||||
<<< @/snippets/snippet.cs{c#}
|
||||
|
||||
<!-- com destaque de linha: -->
|
||||
|
||||
<<< @/snippets/snippet.cs{1,2,4-6 c#}
|
||||
|
||||
<!-- com números de linha: -->
|
||||
|
||||
<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}
|
||||
```
|
||||
|
||||
Isso é útil se a linguagem original não puder ser inferida pela extensão do arquivo.
|
||||
|
||||
## Grupos de Código {#code-groups}
|
||||
|
||||
Você pode agrupar vários blocos de código assim:
|
||||
|
||||
**Entrada**
|
||||
|
||||
````md
|
||||
::: code-group
|
||||
|
||||
```js [config.js]
|
||||
/**
|
||||
* @type {import('vitepress').UserConfig}
|
||||
*/
|
||||
const config = {
|
||||
// ...
|
||||
}
|
||||
|
||||
export default config
|
||||
```
|
||||
|
||||
```ts [config.ts]
|
||||
import type { UserConfig } from 'vitepress'
|
||||
|
||||
const config: UserConfig = {
|
||||
// ...
|
||||
}
|
||||
|
||||
export default config
|
||||
```
|
||||
|
||||
:::
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
::: code-group
|
||||
|
||||
```js [config.js]
|
||||
/**
|
||||
* @type {import('vitepress').UserConfig}
|
||||
*/
|
||||
const config = {
|
||||
// ...
|
||||
}
|
||||
|
||||
export default config
|
||||
```
|
||||
|
||||
```ts [config.ts]
|
||||
import type { UserConfig } from 'vitepress'
|
||||
|
||||
const config: UserConfig = {
|
||||
// ...
|
||||
}
|
||||
|
||||
export default config
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
Você também pode [importar _snippets_ de código](#import-code-snippets) em grupos de código:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
::: code-group
|
||||
|
||||
<!-- nome de arquivo usado como título por padrão -->
|
||||
|
||||
<<< @/snippets/snippet.js
|
||||
|
||||
<!-- você pode fornecer um personalizado também -->
|
||||
|
||||
<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
|
||||
|
||||
:::
|
||||
```
|
||||
|
||||
**Output**
|
||||
|
||||
::: code-group
|
||||
|
||||
<<< @/snippets/snippet.js
|
||||
|
||||
<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]
|
||||
|
||||
:::
|
||||
|
||||
## Inclusão de Arquivo Markdown {#markdown-file-inclusion}
|
||||
|
||||
Você pode incluir um arquivo markdown em outro arquivo markdown, mesmo aninhado.
|
||||
|
||||
::: dica
|
||||
Você também pode prefixar o caminho do markdown com `@`, ele atuará como a raiz de origem. Por padrão, é a raiz do projeto VitePress, a menos que `srcDir` seja configurado.
|
||||
:::
|
||||
|
||||
Por exemplo, você pode incluir um arquivo markdown relativo usando isto:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
# Documentação
|
||||
|
||||
## Conceitos Básicos
|
||||
|
||||
<!--@include: ./parts/basics.md-->
|
||||
```
|
||||
|
||||
**Arquivo da Parte** (`parts/basics.md`)
|
||||
|
||||
```md
|
||||
Algumas coisas básicas.
|
||||
|
||||
### Configuração
|
||||
|
||||
Pode ser criada usando `.foorc.json`.
|
||||
```
|
||||
|
||||
**Código Equivalente**
|
||||
|
||||
```md
|
||||
# Documentação
|
||||
|
||||
## Conceitos Básicos
|
||||
|
||||
Algumas coisas básicas.
|
||||
|
||||
### Configuração
|
||||
|
||||
Pode ser criada usando `.foorc.json`.
|
||||
```
|
||||
|
||||
Também suporta a seleção de um intervalo de linhas:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
# Documentação
|
||||
|
||||
## Conceitos Básicos
|
||||
|
||||
<!--@include: ./parts/basics.md{3,}-->
|
||||
```
|
||||
|
||||
**Arquivo da Parte** (`parts/basics.md`)
|
||||
|
||||
```md
|
||||
Algumas coisas básicas.
|
||||
|
||||
### Configuração
|
||||
|
||||
Pode ser criada usando `.foorc.json`.
|
||||
```
|
||||
|
||||
**Código Equivalente**
|
||||
|
||||
```md
|
||||
# Documentação
|
||||
|
||||
## Conceitos Básicos
|
||||
|
||||
### Configuração
|
||||
|
||||
Pode ser criada usando `.foorc.json`.
|
||||
```
|
||||
|
||||
O formato do intervalo de linhas selecionado pode ser: `{3,}`, `{,10}`, `{1,10}`
|
||||
|
||||
::: aviso
|
||||
Observe que isso não gera erros se o arquivo não estiver presente. Portanto, ao usar esse recurso, certifique-se de que o conteúdo está sendo mostrado como esperado.
|
||||
:::
|
||||
|
||||
## Equações Matemáticas {#math-equations}
|
||||
|
||||
Isso é atualmente opcional. Para ativá-lo, você precisa instalar `markdown-it-mathjax3` e definir `markdown.math` como `true` no seu arquivo de configuração:
|
||||
|
||||
```sh
|
||||
npm add -D markdown-it-mathjax3
|
||||
```
|
||||
|
||||
```ts
|
||||
// .vitepress/config.ts
|
||||
export default {
|
||||
markdown: {
|
||||
math: true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
Quando $a \ne 0$, existem duas soluções para $(ax^2 + bx + c = 0)$ e elas são
|
||||
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
|
||||
|
||||
**Equações de Maxwell:**
|
||||
|
||||
| equação | descrição |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | a divergência de $\vec{\mathbf{B}}$ é zero |
|
||||
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | a rotacional de $\vec{\mathbf{E}}$ é proporcional à taxa de variação de $\vec{\mathbf{B}}$ |
|
||||
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _hã?_ |
|
||||
|
||||
**Saída**
|
||||
|
||||
Quando $a \ne 0$, existem duas soluções para $(ax^2 + bx + c = 0)$ e são
|
||||
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
|
||||
|
||||
**Equações de Maxwell:**
|
||||
|
||||
| equação | descrição |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| $\nabla \cdot \vec{\mathbf{B}} = 0$ | a divergência de $\vec{\mathbf{B}}$ é zero |
|
||||
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | a rotacional de $\vec{\mathbf{E}}$ é proporcional à taxa de variação de $\vec{\mathbf{B}}$ |
|
||||
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _hã?_ |
|
||||
|
||||
## _Lazy Loading_ de Imagens {#image-lazy-loading}
|
||||
|
||||
Você pode ativar o "carregamento folgado" para cada imagem adicionada via markdown definindo `lazyLoading` como `true` no seu arquivo de configuração:
|
||||
|
||||
```js
|
||||
export default {
|
||||
markdown: {
|
||||
image: {
|
||||
// o carregamento folgado de imagens está desativado por padrão
|
||||
lazyLoading: true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuração Avançada {#advanced-configuration}
|
||||
|
||||
VitePress usa [markdown-it](https://github.com/markdown-it/markdown-it) como interpretador Markdown. Muitas das extensões acima são implementadas por meio de _plugins_ personalizados. Você pode personalizar ainda mais a instância `markdown-it` usando a opção `markdown` em `.vitepress/config.js`:
|
||||
|
||||
```js
|
||||
import { defineConfig } from 'vitepress'
|
||||
import markdownItAnchor from 'markdown-it-anchor'
|
||||
import markdownItFoo from 'markdown-it-foo'
|
||||
|
||||
export default defineConfig({
|
||||
markdown: {
|
||||
// opções para markdown-it-anchor
|
||||
// https://github.com/valeriangalliat/markdown-it-anchor#usage
|
||||
anchor: {
|
||||
permalink: markdownItAnchor.permalink.headerLink()
|
||||
},
|
||||
|
||||
// opções para @mdit-vue/plugin-toc
|
||||
// https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
|
||||
toc: { level: [1, 2] },
|
||||
|
||||
config: (md) => {
|
||||
// use mais plugins markdown-it!
|
||||
md.use(markdownItFoo)
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Consulte a lista completa de propriedades configuráveis em [Referência de Configuração: Configuração da Aplicação](../reference/site-config#markdown).
|
||||
@ -0,0 +1,23 @@
|
||||
# Modo MPA <Badge type="warning" text="experimental" /> {#mpa-mode}
|
||||
|
||||
O modo MPA (Aplicação Multipáginas) pode ser habilitado pela linha de comando com `vitepress build --mpa`, ou através da configuração pela opção `mpa: true`.
|
||||
|
||||
No modo MPA, todas as páginas são apresentadas por padrão sem qualquer JavaScript incluído. Como resultado, o site em produção provavelmente terá uma nota de desempenho de visita inicial superior com ferramentas de auditoria.
|
||||
|
||||
Entretanto, devido a ausência de navegação SPA, links entre páginas acarretarão em recarregamentos de página completos. Navegações pós-carregamento no modo MPA não parecerão tão instantâneas quanto no modo SPA.
|
||||
|
||||
Também note que não ter JavaScript por padrão significa que você está essencialmente utilizando Vue como modelo de linguagem no lado do servidor. Nenhum manipulador de evento será embutido no navegador, então não haverá interatividade. Para carregar JavaScript no lado do cliente, você precisará usar a tag especial `<script client>`:
|
||||
|
||||
```html
|
||||
<script client>
|
||||
document.querySelector('h1').addEventListener('click', () => {
|
||||
console.log('JavaScript no lado do cliente!')
|
||||
})
|
||||
</script>
|
||||
|
||||
# Olá
|
||||
```
|
||||
|
||||
`<script client>` é uma funcionalidade exclusiva VitePress, não uma funcionalidade Vue. Funciona tanto em arquivos `.md` quanto em arquivos `.vue`, mas apenas no modo MPA. Scripts de cliente em todos os componentes do tema serão empacotados juntos, enquanto o script do cliente para uma página específica será dividido apenas para aquela página.
|
||||
|
||||
Note que `<script client>` **não é avaliado como código de componente Vue**: é processado como um simples módulo JavaScript. Por esta razão, o modo MPA deve ser usado apenas se seu site exige o mínimo absoluto de interatividade no lado do cliente.
|
||||
@ -0,0 +1,372 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Roteamento {#routing}
|
||||
|
||||
## Roteamento baseado em Arquivos {#file-based-routing}
|
||||
|
||||
VitePress utiliza roteamento baseado em arquivos, isso significa que as páginas HTML geradas são mapeadas da estrutura de diretórios dos arquivos fonte Markdown. Por exemplo, dada a seguinte estrutura de diretório:
|
||||
|
||||
```
|
||||
.
|
||||
├─ guide
|
||||
│ ├─ getting-started.md
|
||||
│ └─ index.md
|
||||
├─ index.md
|
||||
└─ prologue.md
|
||||
```
|
||||
|
||||
As páginas HTML geradas serão:
|
||||
|
||||
```
|
||||
index.md --> /index.html (acessível por /)
|
||||
prologue.md --> /prologue.html
|
||||
guide/index.md --> /guide/index.html (acessível por /guide/)
|
||||
guide/getting-started.md --> /guide/getting-started.html
|
||||
```
|
||||
|
||||
O HTML resultante pode ser hospedado em qualquer servidor web que possa servir arquivos estáticos.
|
||||
|
||||
## Diretório Raiz e Fonte {#root-and-source-directory}
|
||||
|
||||
Existem dois conceitos importantes na estrutura de arquivos de um projeto VitePress: o **diretório raiz** e o **diretório fonte**.
|
||||
|
||||
### Diretório Raiz {#project-root}
|
||||
|
||||
O diretório raiz é onde o VitePress procura pelo diretório especial `.vitepress`. O diretório `.vitepress` é um local reservado para o arquivo de configuração do VitePress, o cache do servidor de desenvolvimento, o resultado da compilação e o código de personalização de tema opcional.
|
||||
|
||||
Ao executar `vitepress dev` ou `vitepress build` no terminal, VitePress usará o diretório atual como diretório raiz do projeto. Para especificar um subdiretório como raiz, é necessário passar o caminho relativo para o comando. Por exemplo, se o projeto VitePress estiver localizado em `./docs`, deve-se executar `vitepress dev docs`:
|
||||
|
||||
```
|
||||
.
|
||||
├─ docs # diretório raiz
|
||||
│ ├─ .vitepress # diretório de configuração
|
||||
│ ├─ getting-started.md
|
||||
│ └─ index.md
|
||||
└─ ...
|
||||
```
|
||||
|
||||
```sh
|
||||
vitepress dev docs
|
||||
```
|
||||
|
||||
Isso resultará no seguinte mapeamento da fonte para HTML:
|
||||
|
||||
```
|
||||
docs/index.md --> /index.html (acessível como /)
|
||||
docs/getting-started.md --> /getting-started.html
|
||||
```
|
||||
|
||||
### Diretório Fonte {#source-directory}
|
||||
|
||||
O diretório fonte é onde seus arquivos fonte em Markdown estão. Por padrão, é o mesmo que o diretório raiz. No entanto, você pode configurá-lo por meio da opção de configuração [`srcDir`](../reference/site-config#srcdir).
|
||||
|
||||
A opção `srcDir` é resolvida em relação ao diretório raiz do projeto. Por exemplo, com `srcDir: 'src'`, sua estrutura de arquivos ficará assim:
|
||||
|
||||
```
|
||||
. # diretório raiz
|
||||
├─ .vitepress # diretório de configuração
|
||||
└─ src # diretório fonte
|
||||
├─ getting-started.md
|
||||
└─ index.md
|
||||
```
|
||||
|
||||
O mapeamento resultante da fonte para HTML:
|
||||
|
||||
```
|
||||
src/index.md --> /index.html (acessível como /)
|
||||
src/getting-started.md --> /getting-started.html
|
||||
```
|
||||
|
||||
## Links Entre Páginas {#linking-between-pages}
|
||||
|
||||
Você pode usar tanto caminhos absolutos quanto relativos ao vincular páginas. Note que, embora ambas as extensões `.md` e `.html` funcionem, a prática recomendada é omitir as extensões de arquivo para que o VitePress possa gerar as URLs finais com base na sua configuração.
|
||||
|
||||
```md
|
||||
<!-- Fazer -->
|
||||
[Getting Started](./getting-started)
|
||||
[Getting Started](../guide/getting-started)
|
||||
|
||||
<!-- Não Fazer -->
|
||||
[Getting Started](./getting-started.md)
|
||||
[Getting Started](./getting-started.html)
|
||||
```
|
||||
|
||||
Saiba mais sobre a vinculação de ativos, como imagens, em [Manipulação de Ativos](./asset-handling).
|
||||
|
||||
### Vinculação a Páginas Não VitePress {#linking-to-non-vitepress-pages}
|
||||
|
||||
Se você deseja vincular a uma página em seu site que não é gerada pelo VitePress, será necessário usar a URL completa (abre em uma nova guia) ou especificar explicitamente o destino:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
[Link para pure.html](/pure.html){target="_self"}
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
[Link para pure.html](/pure.html){target="_self"}
|
||||
|
||||
::: dica Nota
|
||||
|
||||
Nos links Markdown, a `base` é automaticamente adicionada à URL. Isso significa que, se você deseja vincular a uma página fora da sua base, será necessário algo como `../../pure.html` no link (resolvido em relação à página atual pelo navegador).
|
||||
|
||||
Alternativamente, pode-se usar diretamente a sintaxe da tag âncora:
|
||||
|
||||
```md
|
||||
<a href="/pure.html" target="_self">Link para pure.html</a>
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Geração de URL Limpa {#generating-clean-url}
|
||||
|
||||
::: aviso Suporte do Servidor Necessário
|
||||
Para servir URLs limpas com VitePress, é necessário suporte no lado do servidor.
|
||||
:::
|
||||
|
||||
Por padrão, VitePress resolve links de entrada para URLs que terminam com `.html`. No entanto, alguns usuários podem preferir "URLs limpas" sem a extensão `.html`, por exemplo, `example.com/caminho` em vez de `example.com/caminho.html`.
|
||||
|
||||
Alguns servidores ou plataformas de hospedagem (por exemplo, Netlify, Vercel, GitHub Pages) fornecem a habilidade de mapear uma URL como `/foo` para `/foo.html` se ela existir, sem redirecionamento:
|
||||
|
||||
- Netlify e GitHub Pages suportam isso por padrão.
|
||||
- Vercel requer a ativação da opção [`cleanUrls` no `vercel.json`](https://vercel.com/docs/concepts/projects/project-configuration#cleanurls).
|
||||
|
||||
Se essa funcionalidade estiver disponível para você, também se pode ativar a própria opção de configuração [`cleanUrls`](../reference/site-config#cleanurls) de VitePress para que:
|
||||
|
||||
- Links de entrada entre páginas sejam gerados sem a extensão `.html`.
|
||||
- Se o caminho atual terminar com `.html`, o roteador realizará um redirecionamento no lado do cliente para o caminho sem extensão.
|
||||
|
||||
No entanto, se você não puder configurar o servidor com esse suporte, será necessário recorrer manualmente à seguinte estrutura de diretório:
|
||||
|
||||
```
|
||||
.
|
||||
├─ getting-started
|
||||
│ └─ index.md
|
||||
├─ installation
|
||||
│ └─ index.md
|
||||
└─ index.md
|
||||
```
|
||||
# Reescrita de Rota {#route-rewrites}
|
||||
|
||||
Você pode personalizar o mapeamento entre a estrutura de diretórios fonte e as páginas geradas. Isso é útil quando você tem uma estrutura de projeto complexa. Por exemplo, digamos que você tenha um monorepo com vários pacotes e gostaria de colocar as documentações junto com os arquivos fonte desta forma:
|
||||
|
||||
```
|
||||
.
|
||||
├─ packages
|
||||
│ ├─ pkg-a
|
||||
│ │ └─ src
|
||||
│ │ ├─ pkg-a-code.ts
|
||||
│ │ └─ pkg-a-docs.md
|
||||
│ └─ pkg-b
|
||||
│ └─ src
|
||||
│ ├─ pkg-b-code.ts
|
||||
│ └─ pkg-b-docs.md
|
||||
```
|
||||
|
||||
E você deseja que as páginas VitePress sejam geradas assim:
|
||||
|
||||
```
|
||||
packages/pkg-a/src/pkg-a-docs.md --> /pkg-a/index.html
|
||||
packages/pkg-b/src/pkg-b-docs.md --> /pkg-b/index.html
|
||||
```
|
||||
|
||||
Você pode realizar isso configurando a opção [`rewrites`](../reference/site-config#rewrites) assim:
|
||||
|
||||
```ts
|
||||
// .vitepress/config.js
|
||||
export default {
|
||||
rewrites: {
|
||||
'packages/pkg-a/src/pkg-a-docs.md': 'pkg-a/index.md',
|
||||
'packages/pkg-b/src/pkg-b-docs.md': 'pkg-b/index.md'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A opção `rewrites` também suporta parâmetros de rota dinâmicos. No exemplo acima, seria verboso listar todos os caminhos se você tiver muitos pacotes. Dado que todos eles têm a mesma estrutura de arquivo, você pode simplificar a configuração assim:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
rewrites: {
|
||||
'packages/:pkg/src/(.*)': ':pkg/index.md'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Os caminhos de reescrita são compilados usando o pacote `path-to-regexp` - consulte [sua documentação](https://github.com/pillarjs/path-to-regexp#parameters) para uma sintaxe mais avançada.
|
||||
|
||||
::: warning Links Relativos com Reescritas
|
||||
|
||||
Quando as reescritas estão habilitadas, **links relativos devem ser baseados nos caminhos reescritos**. Por exemplo, para criar um link relativo de `packages/pkg-a/src/pkg-a-code.md` para `packages/pkg-b/src/pkg-b-code.md`, deve-se usar:
|
||||
|
||||
```md
|
||||
[Link para PKG B](../pkg-b/pkg-b-code)
|
||||
```
|
||||
:::
|
||||
|
||||
## Rotas Dinâmicas {#dynamic-routes}
|
||||
|
||||
Você pode gerar muitas páginas usando um único arquivo Markdown e dados dinâmicos. Por exemplo, você pode criar um arquivo `packages/[pkg].md` que gera uma página correspondente para cada pacote em um projeto. Aqui, o segmento `[pkg]` é um **parâmetro** de rota que diferencia cada página das outras.
|
||||
|
||||
### Arquivo de Carregamento de Caminhos {#paths-loader-file}
|
||||
|
||||
Como VitePress é um gerador de site estático, os caminhos possíveis das páginas devem ser determinados no momento da compilação. Portanto, uma página de rota dinâmica **deve** ser acompanhada por um **arquivo de carregamento de caminhos**. Para `packages/[pkg].md`, precisaremos de `packages/[pkg].paths.js` (`.ts` também é suportado):
|
||||
|
||||
```
|
||||
.
|
||||
└─ packages
|
||||
├─ [pkg].md # modelo de rota
|
||||
└─ [pkg].paths.js # carregador de caminhos da rota
|
||||
```
|
||||
|
||||
O carregador de caminhos deve fornecer um objeto com um método `paths` como sua exportação padrão. O método `paths` deve retornar um _array_ de objetos com uma propriedade `params`. Cada um desses objetos gerará uma página correspondente.
|
||||
|
||||
Dado o seguinte _array_ `paths`:
|
||||
|
||||
```js
|
||||
// packages/[pkg].paths.js
|
||||
export default {
|
||||
paths() {
|
||||
return [
|
||||
{ params: { pkg: 'foo' }},
|
||||
{ params: { pkg: 'bar' }}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
As páginas HTML geradas serão:
|
||||
|
||||
```
|
||||
.
|
||||
└─ packages
|
||||
├─ foo.html
|
||||
└─ bar.html
|
||||
```
|
||||
|
||||
### Múltiplos Parâmetros {#multiple-params}
|
||||
|
||||
Uma rota dinâmica pode conter múltiplos parâmetros:
|
||||
|
||||
**Estrutura de Arquivo**
|
||||
|
||||
```
|
||||
.
|
||||
└─ packages
|
||||
├─ [pkg]-[version].md
|
||||
└─ [pkg]-[version].paths.js
|
||||
```
|
||||
|
||||
**Carregador de Caminhos**
|
||||
|
||||
```js
|
||||
export default {
|
||||
paths: () => [
|
||||
{ params: { pkg: 'foo', version: '1.0.0' }},
|
||||
{ params: { pkg: 'foo', version: '2.0.0' }},
|
||||
{ params: { pkg: 'bar', version: '1.0.0' }},
|
||||
{ params: { pkg: 'bar', version: '2.0.0' }}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
```
|
||||
.
|
||||
└─ packages
|
||||
├─ foo-1.0.0.html
|
||||
├─ foo-2.0.0.html
|
||||
├─ bar-1.0.0.html
|
||||
└─ bar-2.0.0.html
|
||||
```
|
||||
|
||||
### Gerando Caminhos Dinamicamente {#dynamically-generating-paths}
|
||||
|
||||
O módulo de carregamento de caminhos é executado no Node.js e apenas durante o momento de compilação. Você pode gerar dinamicamente o _array_ de caminhos usando qualquer dado, seja local ou remoto.
|
||||
|
||||
Gerando caminhos a partir de arquivos locais:
|
||||
|
||||
```js
|
||||
import fs from 'fs'
|
||||
|
||||
export default {
|
||||
paths() {
|
||||
return fs
|
||||
.readdirSync('packages')
|
||||
.map((pkg) => {
|
||||
return { params: { pkg }}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Gerando caminhos a partir de dados remotos:
|
||||
|
||||
```js
|
||||
export default {
|
||||
async paths() {
|
||||
const pkgs = await (await fetch('https://my-api.com/packages')).json()
|
||||
|
||||
return pkgs.map((pkg) => {
|
||||
return {
|
||||
params: {
|
||||
pkg: pkg.name,
|
||||
version: pkg.version
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Acessando Parâmetros na Página {#accessing-params-in-page}
|
||||
|
||||
Você pode usar os parâmetros para passar dados adicionais para cada página. O arquivo de rota Markdown pode acessar os parâmetros da página atual em expressões Vue através da propriedade global `$params`:
|
||||
|
||||
```md
|
||||
- nome do pacote: {{ $params.pkg }}
|
||||
- versão: {{ $params.version }}
|
||||
```
|
||||
|
||||
Você também pode acessar os parâmetros da página atual através da API de tempo de execução [`useData`](../reference/runtime-api#usedata). Isso está disponível tanto em arquivos Markdown quanto em componentes Vue:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
|
||||
// params é uma ref Vue
|
||||
const { params } = useData()
|
||||
|
||||
console.log(params.value)
|
||||
</script>
|
||||
```
|
||||
|
||||
### Apresentando Conteúdo Cru {#rendering-raw-content}
|
||||
|
||||
Parâmetros passados para a página serão serializados na carga JavaScript do cliente, portanto, evite passar dados pesados nos parâmetros, como Markdown cru ou conteúdo HTML obtido de um CMS remoto.
|
||||
|
||||
Em vez disso, você pode passar tal conteúdo para cada página usando a propriedade `content` em cada objeto de caminho:
|
||||
|
||||
```js
|
||||
export default {
|
||||
async paths() {
|
||||
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
|
||||
|
||||
return posts.map((post) => {
|
||||
return {
|
||||
params: { id: post.id },
|
||||
content: post.content // Markdown ou HTML cru
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Em seguida, use a seguinte sintaxe especial para apresentar o conteúdo como parte do próprio arquivo Markdown:
|
||||
|
||||
```md
|
||||
<!-- @content -->
|
||||
```
|
||||
@ -0,0 +1,53 @@
|
||||
# Geração de Sitemap {#sitemap-generation}
|
||||
|
||||
VitePress vem com suporte embutido para gerar um arquivo `sitemap.xml` para seu site. Para habilitar, adicione o seguinte ao seu `.vitepress/config.js`:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
sitemap: {
|
||||
hostname: 'https://example.com'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Para ter tags `<lastmod>` em seu `sitemap.xml`, você pode habilitar a opção [`lastUpdated`](../reference/default-theme-last-updated).
|
||||
|
||||
## Opções {#options}
|
||||
|
||||
O suporte de Sietmap é alimentado pelo módulo [`sitemap`](https://www.npmjs.com/package/sitemap). Você pode passar qualquer uma das opções suportadas por ele na opção `sitemap` do seu arquivo de configuração. Esses serão passados diretamente ao construtor `SitemapStream`. Refira-se a [documentação `sitemap`](https://www.npmjs.com/package/sitemap#options-you-can-pass) para mais detalhes. Exemplo:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
sitemap: {
|
||||
hostname: 'https://example.com',
|
||||
lastmodDateOnly: false
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Gancho `transformItems`
|
||||
|
||||
Você pode usar o gancho `sitemap.transformItems` para modificar os itens do sitemap antes de eles serem escritos no arquivo `sitemap.xml`. Este gancho é chamado com um _array_ de itens sitemap e espera um _array_ de itens sitemap como retorno. Exemplo:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
sitemap: {
|
||||
hostname: 'https://example.com',
|
||||
transformItems: (items) => {
|
||||
// adiciona novos itens ou modifica/filtra itens existentes
|
||||
items.push({
|
||||
url: '/extra-page',
|
||||
changefreq: 'monthly',
|
||||
priority: 0.8
|
||||
})
|
||||
return items
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
@ -0,0 +1,136 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Compatibilidade SSR {#ssr-compatibility}
|
||||
|
||||
VitePress pré-interpreta a aplicação no Node.js durante a compilação de produção, utilizando as capacidades de Interpretação do Lado do Servidor (SSR) do Vue. Isso significa que todo o código personalizado nos componentes do tema está sujeito à Compatibilidade SSR.
|
||||
|
||||
A [seção SSR na documentação Vue oficial](https://vuejs.org/guide/scaling-up/ssr.html) fornece mais contexto sobre o que é SSR, a relação entre SSR / SSG e notas comuns sobre escrever código amigável a SSR. A regra geral é acessar apenas APIs do navegador / DOM nos gatilhos `beforeMount` ou `mounted` dos componentes Vue.
|
||||
|
||||
## `<ClientOnly>`
|
||||
|
||||
Se você estiver usando ou demonstrando componentes que não são compatíveis com SSR (por exemplo, contêm diretivas personalizadas), você pode envolvê-los no componente embutido `<ClientOnly>`:
|
||||
|
||||
```md
|
||||
<ClientOnly>
|
||||
<ComponenteNaoCompativelComSSR />
|
||||
</ClientOnly>
|
||||
```
|
||||
|
||||
## Bibliotecas que Acessam a API do Navegador na Importação {#libraries-that-access-browser-api-on-import}
|
||||
|
||||
Alguns componentes ou bibliotecas acessam APIs do navegador **na importação**. Para usar código que assume um ambiente de navegador na importação, você precisa importá-los dinamicamente.
|
||||
|
||||
### Importando no Gatilho `mounted` {#importing-in-mounted-hook}
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { onMounted } from 'vue'
|
||||
|
||||
onMounted(() => {
|
||||
import('./lib-que-acessa-window-na-importacao').then((module) => {
|
||||
// usar código
|
||||
})
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
### Importação Condicional {#conditional-import}
|
||||
|
||||
Você também pode importar condicionalmente uma dependência usando o sinalizador `import.meta.env.SSR` (parte das [variáveis de ambiente Vite](https://vitejs.dev/guide/env-and-mode.html#env-variables)):
|
||||
|
||||
```js
|
||||
if (!import.meta.env.SSR) {
|
||||
import('./lib-que-acessa-window-na-importacao').then((module) => {
|
||||
// usar código
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Como [`Theme.enhanceApp`](./custom-theme#theme-interface) pode ser assíncrono, você pode importar condicionalmente e registrar plugins Vue que acessam APIs do navegador na importação:
|
||||
|
||||
```js
|
||||
// .vitepress/theme/index.js
|
||||
/** @type {import('vitepress').Theme} */
|
||||
export default {
|
||||
// ...
|
||||
async enhanceApp({ app }) {
|
||||
if (!import.meta.env.SSR) {
|
||||
const plugin = await import('plugin-que-acessa-window-na-importacao')
|
||||
app.use(plugin.default)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Se estiver usando TypeScript:
|
||||
```ts
|
||||
// .vitepress/theme/index.ts
|
||||
import type { Theme } from 'vitepress'
|
||||
|
||||
export default {
|
||||
// ...
|
||||
async enhanceApp({ app }) {
|
||||
if (!import.meta.env.SSR) {
|
||||
const plugin = await import('plugin-que-acessa-window-na-importacao')
|
||||
app.use(plugin.default)
|
||||
}
|
||||
}
|
||||
} satisfies Theme
|
||||
```
|
||||
|
||||
### `defineClientComponent`
|
||||
|
||||
VitePress fornece um auxiliar de conveniência para importar componentes Vue que acessam APIs do navegador na importação.
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { defineClientComponent } from 'vitepress'
|
||||
|
||||
const ClientComp = defineClientComponent(() => {
|
||||
return import('componente-que-acessa-window-na-importacao')
|
||||
})
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<ClientComp />
|
||||
</template>
|
||||
```
|
||||
|
||||
Você também pode passar propriedades/filhos/_slots_ para o componente alvo:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { ref } from 'vue'
|
||||
import { defineClientComponent } from 'vitepress'
|
||||
|
||||
const clientCompRef = ref(null)
|
||||
const ClientComp = defineClientComponent(
|
||||
() => import('componente-que-acessa-window-na-importacao'),
|
||||
|
||||
// os argumentos são passados para h() - https://vuejs.org/api/render-function.html#h
|
||||
[
|
||||
{
|
||||
ref: clientCompRef
|
||||
},
|
||||
{
|
||||
default: () => 'slot padrão',
|
||||
foo: () => h('div', 'foo'),
|
||||
bar: () => [h('span', 'um'), h('span', 'dois')]
|
||||
}
|
||||
],
|
||||
|
||||
// retorno de chamada depois que o componente é carregado, pode ser assíncrono
|
||||
() => {
|
||||
console.log(clientCompRef.value)
|
||||
}
|
||||
)
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<ClientComp />
|
||||
</template>
|
||||
```
|
||||
|
||||
O componente alvo só será importado no gatilho `mounted` do componente que o envolve.
|
||||
@ -0,0 +1,255 @@
|
||||
# Usando Vue em Markdown {#using-vue-in-markdown}
|
||||
|
||||
Em VitePress, cada arquivo Markdown é compilado para HTML e então processado como um [Componente de Arquivo Único Vue](https://vuejs.org/guide/scaling-up/sfc.html). Isso significa que você pode usar qualquer funcionalidade Vue dentro do Markdown, incluindo a interpolação dinâmica, usar componentes Vue ou lógica arbitrária de componentes Vue dentro da página adicionando uma tag `<script>`.
|
||||
|
||||
Vale ressaltar que VitePress aproveita o compilador Vue para detectar e otimizar automaticamente as partes puramente estáticas do conteúdo Markdown. Os conteúdos estáticos são otimizados em nós de espaço reservado únicos e eliminados da carga JavaScript da página para visitas iniciais. Eles também são ignorados durante a hidratação no lado do cliente. Em resumo, você só paga pelas partes dinâmicas em qualquer página específica.
|
||||
|
||||
::: tip Compatibilidade SSR
|
||||
Todo uso do Vue precisa ser compatível com SSR. Consulte [Compatibilidade SSR](./ssr-compat) para detalhes e soluções comuns.
|
||||
:::
|
||||
|
||||
## Criação de _Templates_ {#templating}
|
||||
|
||||
### Interpolação {#interpolation}
|
||||
|
||||
Cada arquivo Markdown é primeiro compilado para HTML e depois passado como um componente Vue para a canalização de processos Vite. Isso significa que você pode usar interpolação no estilo Vue no texto:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
{{ 1 + 1 }}
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
<div class="language-text"><pre><code>{{ 1 + 1 }}</code></pre></div>
|
||||
|
||||
### Diretivas {#directives}
|
||||
|
||||
Diretivas também funcionam (observe que, por definiçào, HTML cru também é válido em Markdown):
|
||||
|
||||
**Entrada**
|
||||
|
||||
```html
|
||||
<span v-for="i in 3">{{ i }}</span>
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
<div class="language-text"><pre><code><span v-for="i in 3">{{ i }} </span></code></pre></div>
|
||||
|
||||
## `<script>` e `<style>`
|
||||
|
||||
As tags `<script>` e `<style>` em nível raiz nos arquivos Markdown funcionam igualmente como nos Componentes de Arquivo Único Vue, incluindo `<script setup>`, `<style module>`, e etc. A principal diferença aqui é que não há uma tag `<template>`: todo outro conteúdo em nível raiz é Markdown. Além disso, observe que todas as tags devem ser colocadas **após** o frontmatter:
|
||||
|
||||
```html
|
||||
---
|
||||
hello: world
|
||||
---
|
||||
|
||||
<script setup>
|
||||
import { ref } from 'vue'
|
||||
|
||||
const count = ref(0)
|
||||
</script>
|
||||
|
||||
## Conteúdo Markdown
|
||||
|
||||
A contagem é: {{ count }}
|
||||
|
||||
<button :class="$style.button" @click="count++">Incrementar</button>
|
||||
|
||||
<style module>
|
||||
.button {
|
||||
color: red;
|
||||
font-weight: bold;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
::: warning Evite `<style scoped>` no Markdown
|
||||
Quando usado no Markdown, `<style scoped>` exige a adição de atributos especiais a cada elemento na página atual, o que aumentará significativamente o tamanho da página. `<style module>` é preferido quando é necessária uma estilização localizada em uma página.
|
||||
:::
|
||||
|
||||
Você também tem acesso às APIs de tempo de execução VitePress, como o [auxiliar `useData`](../reference/runtime-api#usedata), que fornece acesso aos metadados da página atual:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```html
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
|
||||
const { page } = useData()
|
||||
</script>
|
||||
|
||||
<pre>{{ page }}</pre>
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/usando-vue.html",
|
||||
"title": "Usando Vue em Markdown",
|
||||
"frontmatter": {},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Usando Componentes {#using-components}
|
||||
|
||||
Você pode importar e usar componentes Vue diretamente nos arquivos Markdown.
|
||||
|
||||
### Importando no Markdown {#importing-in-markdown}
|
||||
|
||||
Se um componente é usado apenas por algumas páginas, é recomendável importá-los explicitamente onde são usados. Isso permite que eles sejam divididos adequadamente e carregados apenas quando as páginas relevantes são mostradas:
|
||||
|
||||
```md
|
||||
<script setup>
|
||||
import CustomComponent from '../components/CustomComponent.vue'
|
||||
</script>
|
||||
|
||||
# Documentação
|
||||
|
||||
Este é um arquivo .md usando um componente personalizado
|
||||
|
||||
<CustomComponent />
|
||||
|
||||
## Mais documentação
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
### Registrando Componentes Globalmente {#registering-components-globally}
|
||||
|
||||
Se um componente for usado na maioria das páginas, eles podem ser registrados globalmente personalizando a instância do aplicativo Vue. Consulte a seção relevante em [Estendendo o Tema Padrão](./extending-default-theme#registering-global-components) para um exemplo.
|
||||
|
||||
::: warning IMPORTANT
|
||||
Certifique-se de que o nome de um componente personalizado contenha um hífen ou esteja em PascalCase. Caso contrário, ele será tratado como um elemento alinhado e envolvido dentro de uma tag `<p>`, o que levará a uma incompatibilidade de hidratação pois `<p>` não permite que elementos de bloco sejam colocados dentro dele.
|
||||
:::
|
||||
|
||||
### Usando Componentes Em Cabeçalhos <ComponenteNoCabeçalho /> {#using-components-in-headers}
|
||||
|
||||
Você pode usar componentes Vue nos cabeçalhos, mas observe a diferença entre as seguintes sintaxes:
|
||||
|
||||
| Markdown | HTML de Saída | Cabeçalho Processado |
|
||||
| ------------------------------------------------------- | ----------------------------------------- | ------------- |
|
||||
| <pre v-pre><code> # texto <Tag/> </code></pre> | `<h1>texto <Tag/></h1>` | `texto` |
|
||||
| <pre v-pre><code> # texto \`<Tag/>\` </code></pre> | `<h1>texto <code><Tag/></code></h1>` | `texto <Tag/>` |
|
||||
|
||||
O HTML envolvido por `<code>` será exibido como é; somente o HTML que **não** estiver envolvido será analisado pelo Vue.
|
||||
|
||||
::: tip
|
||||
O HTML de saída é realizado por [Markdown-it](https://github.com/Markdown-it/Markdown-it), enquanto os cabeçalhos processados são manipulados pelo VitePress (e usados tanto na barra lateral quanto no título do documento).
|
||||
:::
|
||||
|
||||
## Escapes {#escaping}
|
||||
|
||||
Você pode escapar de interpolações Vue envolvendo-as em um `<span>` ou outros elementos com a diretiva `v-pre`:
|
||||
|
||||
**Entrada**
|
||||
|
||||
```md
|
||||
Isto <span v-pre>{{ será exibido como é }}</span>
|
||||
```
|
||||
|
||||
**Saída**
|
||||
|
||||
<div class="escape-demo">
|
||||
<p>Isto <span v-pre>{{ será exibido como é }}</span></p>
|
||||
</div>
|
||||
|
||||
Alternativamente, você pode envolver todo o parágrafo em um container personalizado `v-pre`:
|
||||
|
||||
```md
|
||||
::: v-pre
|
||||
{{ Isto será exibido como é }}
|
||||
:::
|
||||
```
|
||||
|
||||
**Output**
|
||||
|
||||
<div class="escape-demo">
|
||||
|
||||
::: v-pre
|
||||
{{ Isto será exibido como é }}
|
||||
:::
|
||||
|
||||
</div>
|
||||
|
||||
## "Des-escape" em Blocos de Código {#unescape-in-code-blocks}
|
||||
|
||||
Por padrão, todos os blocos de código cercados são automaticamente envolvidos com `v-pre`, então nenhuma sintaxe Vue será processada dentro deles. Para permitir a interpolação no estilo Vue dentro do cercado, você pode adicionar a linguagem com o sufixo `-vue` , por exemplo, `js-vue`:
|
||||
|
||||
**Entrada**
|
||||
|
||||
````md
|
||||
```js-vue
|
||||
Olá {{ 1 + 1 }}
|
||||
```
|
||||
````
|
||||
|
||||
**Saída**
|
||||
|
||||
```js-vue
|
||||
Olá {{ 1 + 1 }}
|
||||
```
|
||||
|
||||
Observe que isso pode impedir que certos tokens sejam realçados corretamente.
|
||||
|
||||
## Usando Pré-processadores CSS {#using-css-pre-processors}
|
||||
|
||||
O VitePress possui [suporte embutido](https://vitejs.dev/guide/features.html#css-pre-processors) para pré-processadores CSS: arquivos `.scss`, `.sass`, `.less`, `.styl` e `.stylus`. Não é necessário instalar plugins específicos do Vite para eles, mas o próprio pré-processador correspondente deve ser instalado:
|
||||
|
||||
```
|
||||
# .scss e .sass
|
||||
npm install -D sass
|
||||
|
||||
# .less
|
||||
npm install -D less
|
||||
|
||||
# .styl e .stylus
|
||||
npm install -D stylus
|
||||
```
|
||||
|
||||
Então você pode usar o seguinte em Markdown e nos componentes do tema:
|
||||
|
||||
```vue
|
||||
<style lang="sass">
|
||||
.title
|
||||
font-size: 20px
|
||||
</style>
|
||||
```
|
||||
|
||||
## Usando _Teleports_ {#using-teleports}
|
||||
|
||||
Vitepress atualmente oferece suporte a SSG para _teleports_ apenas para o corpo. Para outros alvos, você pode envolvê-los dentro do componente embutido `<ClientOnly>` ou injetar a marcação de _teleport_ na localização correta em sua página final HTML por meio do [gancho `postRender`](../reference/site-config#postrender).
|
||||
|
||||
<ModalDemo />
|
||||
|
||||
::: details
|
||||
<<< @/components/ModalDemo.vue
|
||||
:::
|
||||
|
||||
```md
|
||||
<ClientOnly>
|
||||
<Teleport to="#modal">
|
||||
<div>
|
||||
// ...
|
||||
</div>
|
||||
</Teleport>
|
||||
</ClientOnly>
|
||||
```
|
||||
|
||||
<script setup>
|
||||
import ModalDemo from '../../components/ModalDemo.vue'
|
||||
import ComponentInHeader from '../../components/ComponentInHeader.vue'
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.escape-demo {
|
||||
border: 1px solid var(--vp-c-border);
|
||||
border-radius: 8px;
|
||||
padding: 0 20px;
|
||||
}
|
||||
</style>
|
||||
@ -0,0 +1,57 @@
|
||||
# O que é VitePress? {#what-is-vitepress}
|
||||
|
||||
O VitePress é um [Gerador de Site Estático](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) projetado para criar sites rápidos e centrados em conteúdo. Em suma, VitePress utiliza seu conteúdo-fonte escrito em [Markdown](https://en.wikipedia.org/wiki/Markdown), aplica um tema a ele e gera páginas HTML estáticas que podem ser facilmente implantadas em qualquer lugar.
|
||||
|
||||
<div class="tip custom-block" style="padding-top: 8px">
|
||||
|
||||
Quer apenas experimentar? Pule para o [Início Rápido](./getting-started).
|
||||
|
||||
</div>
|
||||
|
||||
## Casos de Uso {#use-cases}
|
||||
|
||||
- **Documentação**
|
||||
|
||||
VitePress vem com um tema padrão projetado para documentação técnica. Ele alimenta esta página que você está lendo agora, juntamente com a documentação [Vite](https://vitejs.dev/), [Rollup](https://rollupjs.org/), [Pinia](https://pinia.vuejs.org/), [VueUse](https://vueuse.org/), [Vitest](https://vitest.dev/), [D3](https://d3js.org/), [UnoCSS](https://unocss.dev/), [Iconify](https://iconify.design/) e [muitos outros](https://www.vuetelescope.com/explore?framework.slug=vitepress).
|
||||
|
||||
A [documentação oficial Vue.js](https://vuejs.org/) também é baseada em VitePress, mas usa um tema personalizado compartilhado entre várias traduções.
|
||||
|
||||
- **Blogs, Portfólios e Sites de Marketing**
|
||||
|
||||
VitePress suporta [temas totalmente personalizáveis](./custom-theme), com a experiência de desenvolvedor padrão de uma aplicação Vite + Vue. A construção com Vite significa que você pode aproveitar diretamente plugins Vite de seu rico ecossistema. Adicionalmente, VitePress fornece APIs flexíveis para [carregar dados](./data-loading) (locais ou remotos) e [gerar rotas dinamicamente](./routing#dynamic-routes). Você pode usá-lo para construir praticamente qualquer coisa desde que os dados possam ser determinados no momento da construção.
|
||||
|
||||
O [blog oficial Vue.js](https://blog.vuejs.org/) é um blog simples que gera sua página inicial baseada em conteúdo local.
|
||||
|
||||
## Experiência de Desenvolvedor {#developer-experience}
|
||||
|
||||
VitePress visa proporcionar excelente Experiência de Desenvolvedor (DX) ao trabalhar com conteúdo em Markdown.
|
||||
|
||||
- **[Alimentado por Vite:](https://vitejs.dev/)** inicialização instantânea do servidor, com edições sempre refletidas instantaneamente (<100ms) sem recarregamento de página.
|
||||
|
||||
- **[Extensões Markdown Integradas:](./markdown)** Frontmatter, tabelas, destaque de sintaxe... você escolhe. Especificamente, VitePress fornece muitos recursos avançados para trabalhar com blocos de código, tornando-o ideal para documentação altamente técnica.
|
||||
|
||||
- **[Markdown Aprimorado por Vue:](./using-vue)** cada página Markdown é também um [Componente de Arquivo Único Vue](https://pt.vuejs.org/guide/scaling-up/sfc.html), graças à compatibilidade de sintaxe de 100% do template Vue com HTML. Você pode incorporar interatividade em seu conteúdo estático usando recursos de template Vue ou componentes Vue importados.
|
||||
|
||||
## Desempenho {#performance}
|
||||
|
||||
Ao contrário de muitos SSGs tradicionais, um site gerado pelo VitePress é na verdade uma [Aplicação de Página Única](https://en.wikipedia.org/wiki/Single-page_application) (SPA).
|
||||
|
||||
- **Carregamento Inicial Rápido**
|
||||
|
||||
A visita inicial a qualquer página será servida com o HTML estático pré-renderizado para velocidade de carregamento rápida e SEO otimizado. A página então carrega um pacote JavaScript que transforma a página em uma SPA Vue ("hidratação"). O processo de hidratação é extremamente rápido: no [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F), sites típicos VitePress alcançam pontuações de desempenho quase perfeitas, mesmo em dispositivos móveis de baixo desempenho com uma rede lenta.
|
||||
|
||||
- **Navegação Rápida pós-carregamento**
|
||||
|
||||
Mais importante ainda, o modelo SPA leva a uma melhor experiência do usuário **após** o carregamento inicial. A navegação subsequente dentro do site não causará mais uma recarga completa da página. Em vez disso, o conteúdo da página de entrada será buscado e atualizado dinamicamente. VitePress também pré-carrega automaticamente pedaços de página para links que estão dentro do viewport. Na maioria dos casos, a navegação pós-carregamento parecerá instantânea.
|
||||
|
||||
- **Interatividade Sem Penalidades**
|
||||
|
||||
Para ser capaz de hidratar as partes dinâmicas Vue incorporadas dentro do Markdown estático, cada página Markdown é processada como um componente Vue e compilada em JavaScript. Isso pode parecer ineficiente, mas o compilador Vue é inteligente o suficiente para separar as partes estáticas e dinâmicas, minimizando tanto o custo de hidratação quanto o tamanho da carga. Para o carregamento inicial da página, as partes estáticas são automaticamente eliminadas da carga JavaScript e puladas durante a hidratação.
|
||||
|
||||
## E o VuePress? {#what-about-vuepress}
|
||||
|
||||
VitePress é o sucessor espiritual de VuePress. VuePress era orginalmente baseado em Vue 2 e webpack. Com Vue 3 e Vite, VitePress oferece uma experiência de desenvolvedor significativamente melhor, melhor desempenho em produção, um tema padrão mais polido e uma API de personalização mais flexível.
|
||||
|
||||
A diferença da API entre VitePress e VuePress reside principalmente em temas e personalização. Se você estiver usando VuePress 1 com o tema padrão, a migração para VitePress deve ser relativamente simples.
|
||||
|
||||
Também houve esforço investido em VuePress 2, que também suporta Vue 3 e Vite com melhor compatibilidade do que VuePress 1. No entanto, manter dois SSGs em paralelo não é sustentável, então a equipe Vue decidiu focar em VitePress como o principal SSG recomendado a longo prazo.
|
||||
@ -0,0 +1,60 @@
|
||||
---
|
||||
layout: home
|
||||
|
||||
title: VitePress
|
||||
titleTemplate: Gerador de Site Estático desenvolvido com Vite & Vue
|
||||
|
||||
hero:
|
||||
name: VitePress
|
||||
text: Gerador de Site Estático Vite & Vue
|
||||
tagline: Markdown para Lindos Documentos em Minutos
|
||||
actions:
|
||||
- theme: brand
|
||||
text: O que é VitePress?
|
||||
link: /pt/guide/what-is-vitepress
|
||||
- theme: alt
|
||||
text: Iniciar
|
||||
link: /pt/guide/getting-started
|
||||
- theme: alt
|
||||
text: GitHub
|
||||
link: https://github.com/vuejs/vitepress
|
||||
image:
|
||||
src: /vitepress-logo-large.webp
|
||||
alt: VitePress
|
||||
|
||||
features:
|
||||
- icon: 📝
|
||||
title: Foco no seu conteúdo
|
||||
details: Cria sites de documentação belos e sem esforço apenas com markdown.
|
||||
- icon: <svg xmlns="http://www.w3.org/2000/svg" width="30" viewBox="0 0 256 256.32"><defs><linearGradient id="a" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"/><stop offset="100%" stop-color="#BD34FE"/></linearGradient><linearGradient id="b" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"/><stop offset="8.333%" stop-color="#FFDD35"/><stop offset="100%" stop-color="#FFA800"/></linearGradient></defs><path fill="url(#a)" d="M255.153 37.938 134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"/><path fill="url(#b)" d="M185.432.063 96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028 72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"/></svg>
|
||||
title: Aproveite a experiência Vite
|
||||
details: Início de servidor instantâneo, atualizações ultrarrápidas, e plugins do ecossistema Vite.
|
||||
- icon: <svg xmlns="http://www.w3.org/2000/svg" width="30" viewBox="0 0 256 220.8"><path fill="#41B883" d="M204.8 0H256L128 220.8 0 0h97.92L128 51.2 157.44 0h47.36Z"/><path fill="#41B883" d="m0 0 128 220.8L256 0h-51.2L128 132.48 50.56 0H0Z"/><path fill="#35495E" d="M50.56 0 128 133.12 204.8 0h-47.36L128 51.2 97.92 0H50.56Z"/></svg>
|
||||
title: Personalize com Vue
|
||||
details: Use sintaxe e componentes Vue diretamente em markdown, ou construa temas personalizados com Vue.
|
||||
- icon: 🚀
|
||||
title: Entregue Sites Rápidos
|
||||
details: Carregamento inicial rápido com HTML estático, navegação rápida com roteamento no lado do cliente.
|
||||
---
|
||||
|
||||
<style>
|
||||
:root {
|
||||
--vp-home-hero-name-color: transparent;
|
||||
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff);
|
||||
|
||||
--vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe 50%, #47caff 50%);
|
||||
--vp-home-hero-image-filter: blur(44px);
|
||||
}
|
||||
|
||||
@media (min-width: 640px) {
|
||||
:root {
|
||||
--vp-home-hero-image-filter: blur(56px);
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-width: 960px) {
|
||||
:root {
|
||||
--vp-home-hero-image-filter: blur(68px);
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@ -0,0 +1,74 @@
|
||||
# Interface de Linha de Comando {#command-line-interface}
|
||||
|
||||
## `vitepress dev`
|
||||
|
||||
Inicia o servidor de desenvolvimento VitePress com o diretório designado como raiz. Por padrão usa o diretório atual. O comando `dev` pode também ser omitido ao rodar no diretório atual.
|
||||
|
||||
### Uso
|
||||
|
||||
```sh
|
||||
# inicia no diretório atual, omitindo `dev`
|
||||
vitepress
|
||||
|
||||
# inicia em um subdiretório
|
||||
vitepress dev [root]
|
||||
```
|
||||
|
||||
### Opções {#options}
|
||||
|
||||
| Opção | Descrição |
|
||||
| --------------- | ----------------------------------------------------------------- |
|
||||
| `--open [path]` | Abre o navegador na inicialização (`boolean \| string`) |
|
||||
| `--port <port>` | Especifica porta (`number`) |
|
||||
| `--base <path>` | Caminho base público (padrão: `/`) (`string`) |
|
||||
| `--cors` | Habilita CORS |
|
||||
| `--strictPort` | Interrompe se a porta especificada já está em uso (`boolean`) |
|
||||
| `--force` | Força o otimizador a ignorar o cache e reempacotar (`boolean`) |
|
||||
|
||||
## `vitepress build`
|
||||
|
||||
Compila o site VitePress para produção.
|
||||
|
||||
### Uso
|
||||
|
||||
```sh
|
||||
vitepress build [root]
|
||||
```
|
||||
|
||||
### Opções
|
||||
|
||||
| Opção | Descrição |
|
||||
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--mpa` (experimental) | Compila no [Modo MPA](../guide/mpa-mode) sem hidratação no lado do cliente (`boolean`) |
|
||||
| `--base <path>` | Caminho base público (padrão: `/`) (`string`) |
|
||||
| `--target <target>` | Transpila o alvo (padrão: `"modules"`) (`string`) |
|
||||
| `--outDir <dir>` | Diretório de saída relativo ao **cwd** (padrão: `<root>/.vitepress/dist`) (`string`) |
|
||||
| `--minify [minifier]` | Habilita/desabilita minificação, ou especifica um minificador para usar (padrão: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) |
|
||||
| `--assetsInlineLimit <number>` | Limite em bytes para alinhar ativos em base64 (padrão: `4096`) (`number`) |
|
||||
|
||||
## `vitepress preview`
|
||||
|
||||
Prevê localmente a compilação de produção.
|
||||
|
||||
### Uso
|
||||
|
||||
```sh
|
||||
vitepress preview [root]
|
||||
```
|
||||
|
||||
### Opções
|
||||
|
||||
| Opção | Descrição |
|
||||
| --------------- | ------------------------------------------ |
|
||||
| `--base <path>` | Caminho base público (padrão: `/`) (`string`) |
|
||||
| `--port <port>` | Especifica porta (`number`) |
|
||||
|
||||
## `vitepress init`
|
||||
|
||||
Inicia o [Assistente de Instalação](../guide/getting-started#setup-wizard) no diretório atual.
|
||||
|
||||
### Uso
|
||||
|
||||
```sh
|
||||
vitepress init
|
||||
```
|
||||
@ -0,0 +1,22 @@
|
||||
# Carbon Ads {#carbon-ads}
|
||||
|
||||
VitePress tem suporte embutido para [Carbon Ads](https://www.carbonads.net/). Ao definir as credenciais Carbon Ads na configuração, VitePress mostrará anúncios na página.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
carbonAds: {
|
||||
code: 'seu-código-carbon',
|
||||
placement: 'sua-veiculação-carbon'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Esses valores são usados para chamar o sript em CDN do carbon como mostrado abaixo.
|
||||
|
||||
```js
|
||||
`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}`
|
||||
```
|
||||
|
||||
Para aprender mais sobre a configuração Carbon Ads, por favor visite [Site Carbon Ads](https://www.carbonads.net/).
|
||||
@ -0,0 +1,452 @@
|
||||
# Configuração do Tema Padrão {#default-theme-config}
|
||||
|
||||
A configuração do tema permite que você personalize seu tema. Você pode definir a configuração do tema através da opção `themeConfig` no arquivo de configuração:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
lang: 'pt-BR',
|
||||
title: 'VitePress',
|
||||
description: 'Gerador de site estático Vite & Vue.',
|
||||
|
||||
// Configurações relacionadas ao tema.
|
||||
themeConfig: {
|
||||
logo: '/logo.svg',
|
||||
nav: [...],
|
||||
sidebar: { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**As opções documentadas nesta página se aplicam apenas ao tema padrão.** Temas diferentes esperam configurações de tema diferentes. Ao usar um tema personalizado, o objeto de configuração do tema será passado para o tema para que se possam definir comportamentos condicionais.
|
||||
|
||||
## i18nRouting
|
||||
|
||||
- Tipo: `boolean`
|
||||
|
||||
Alterar o local para, por exemplo, `zh` alterará a URL de `/foo` (ou `/en/foo/`) para `/zh/foo`. Você pode desativar esse comportamento definindo `themeConfig.i18nRouting` como `false`.
|
||||
|
||||
## logo
|
||||
|
||||
- Tipo: `ThemeableImage`
|
||||
|
||||
Arquivo de logo a ser exibido na barra de navegação, logo antes do título do site. Aceita um caminho em string, ou um objeto para definir um logo diferente para os modos claro/escuro.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
logo: '/logo.svg'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
type ThemeableImage =
|
||||
| string
|
||||
| { src: string; alt?: string }
|
||||
| { light: string; dark: string; alt?: string }
|
||||
```
|
||||
|
||||
## siteTitle
|
||||
|
||||
- Tipo: `string | false`
|
||||
|
||||
Você pode personalizar este item para substituir o título padrão do site (`title` na configuração da aplicação) na navegação. Quando definido como `false`, o título na navegação será desativado. Útil quando você tem um `logo` que já contém o título do site.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
siteTitle: 'Olá Mundo'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## nav
|
||||
|
||||
- Tipo: `NavItem`
|
||||
|
||||
A configuração para o item do menu de navegação. Mais detalhes em [Tema Padrão: Navegação](./default-theme-nav#navigation-links).
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Guia', link: '/guide' },
|
||||
{
|
||||
text: 'Menu Dropdown',
|
||||
items: [
|
||||
{ text: 'Item A', link: '/item-1' },
|
||||
{ text: 'Item B', link: '/item-2' },
|
||||
{ text: 'Item C', link: '/item-3' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
type NavItem = NavItemWithLink | NavItemWithChildren
|
||||
|
||||
interface NavItemWithLink {
|
||||
text: string
|
||||
link: string
|
||||
activeMatch?: string
|
||||
target?: string
|
||||
rel?: string
|
||||
noIcon?: boolean
|
||||
}
|
||||
|
||||
interface NavItemChildren {
|
||||
text?: string
|
||||
items: NavItemWithLink[]
|
||||
}
|
||||
|
||||
interface NavItemWithChildren {
|
||||
text?: string
|
||||
items: (NavItemChildren | NavItemWithLink)[]
|
||||
activeMatch?: string
|
||||
}
|
||||
```
|
||||
|
||||
## sidebar
|
||||
|
||||
- Tipo: `Sidebar`
|
||||
|
||||
A configuração para o item do menu da barra lateral. Mais detalhes em [Tema Padrão: Barra Lateral](./default-theme-sidebar).
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Guia',
|
||||
items: [
|
||||
{ text: 'Introdução', link: '/introduction' },
|
||||
{ text: 'Começando', link: '/getting-started' },
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export type Sidebar = SidebarItem[] | SidebarMulti
|
||||
|
||||
export interface SidebarMulti {
|
||||
[path: string]: SidebarItem[]
|
||||
}
|
||||
|
||||
export type SidebarItem = {
|
||||
/**
|
||||
* O rótulo de texto do item.
|
||||
*/
|
||||
text?: string
|
||||
|
||||
/**
|
||||
* O link do item.
|
||||
*/
|
||||
link?: string
|
||||
|
||||
/**
|
||||
* Os filhos do item.
|
||||
*/
|
||||
items?: SidebarItem[]
|
||||
|
||||
/**
|
||||
* Se não especificado, o grupo não é retrátil.
|
||||
*
|
||||
* Se `true`, o grupo é retrátil e é colapsado por padrão.
|
||||
*
|
||||
* Se `false`, o grupo é retrátil, mas expandido por padrão.
|
||||
*/
|
||||
collapsed?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
## aside
|
||||
|
||||
- Tipo: `boolean | 'left'`
|
||||
- Padrão: `true`
|
||||
- Pode ser anulado por página via [frontmatter](./frontmatter-config#aside)
|
||||
|
||||
Definir este valor como `false` impede a apresentação do elemento aside.\
|
||||
Definir este valor como `true` apresenta o aside à direita.\
|
||||
Definir este valor como `left` apresenta o aside à esquerda.
|
||||
|
||||
Se você quiser desativá-lo para todas as visualizações, você deve usar `outline: false` em vez disso.
|
||||
|
||||
## outline
|
||||
|
||||
- Tipo: `Outline | Outline['level'] | false`
|
||||
- O nível pode ser sobreposto por página via [frontmatter](./frontmatter-config#outline)
|
||||
|
||||
Definir este valor como `false` impede a apresentação do elemento _outline_. Consulte a interface para obter mais detalhes:
|
||||
|
||||
```ts
|
||||
interface Outline {
|
||||
/**
|
||||
* Os níveis de títulos a serem exibidos na outline.
|
||||
* Um único número significa que apenas os títulos desse nível serão exibidos.
|
||||
* Se uma tupla for passada, o primeiro número é o nível mínimo e o segundo número é o nível máximo.
|
||||
* `'deep'` é o mesmo que `[2, 6]`, o que significa que todos os títulos de `<h2>` a `<h6>` serão exibidos.
|
||||
*
|
||||
* @default 2
|
||||
*/
|
||||
level?: number | [number, number] | 'deep'
|
||||
|
||||
/**
|
||||
* O título a ser exibido na outline.
|
||||
*
|
||||
* @default 'On this page'
|
||||
*/
|
||||
label?: string
|
||||
}
|
||||
```
|
||||
|
||||
## socialLinks
|
||||
|
||||
- Tipo: `SocialLink[]`
|
||||
|
||||
Você pode definir esta opção para mostrar os links de redes sociais com ícones na navegação.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' },
|
||||
{ icon: 'twitter', link: '...' },
|
||||
// Você também pode adicionar ícones personalizados passando SVG como string:
|
||||
{
|
||||
icon: {
|
||||
svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
|
||||
},
|
||||
link: '...',
|
||||
// Você também pode incluir um rótulo personalizado para acessibilidade (opcional mas recomendado):
|
||||
ariaLabel: 'cool link'
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
interface SocialLink {
|
||||
icon: SocialLinkIcon
|
||||
link: string
|
||||
ariaLabel?: string
|
||||
}
|
||||
|
||||
type SocialLinkIcon =
|
||||
| 'discord'
|
||||
| 'facebook'
|
||||
| 'github'
|
||||
| 'instagram'
|
||||
| 'linkedin'
|
||||
| 'mastodon'
|
||||
| 'npm'
|
||||
| 'slack'
|
||||
| 'twitter'
|
||||
| 'x'
|
||||
| 'youtube'
|
||||
| { svg: string }
|
||||
```
|
||||
|
||||
## footer
|
||||
|
||||
- Tipo: `Footer`
|
||||
- Pode ser sobreposto por página via [frontmatter](./frontmatter-config#footer)
|
||||
|
||||
Configuração do rodapé. Você pode adicionar uma mensagem ou texto de direitos autorais no rodapé, no entanto, ela só será exibida quando a página não contiver uma barra lateral. Isso se deve a preocupações de design.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
footer: {
|
||||
message: 'Lançado sob a Licença MIT.',
|
||||
copyright: 'Direitos autorais © 2019-presente Evan You'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface Footer {
|
||||
message?: string
|
||||
copyright?: string
|
||||
}
|
||||
```
|
||||
|
||||
## editLink
|
||||
|
||||
- Tipo: `EditLink`
|
||||
- Pode ser sobreposto por página via [frontmatter](./frontmatter-config#editlink)
|
||||
|
||||
O _EditLink_ permite exibir um link para editar a página em serviços de gerenciamento Git, como GitHub ou GitLab. Consulte [Tema Padrão: Editar Link](./default-theme-edit-link) para mais detalhes.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
|
||||
text: 'Editar esta página no GitHub'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface EditLink {
|
||||
pattern: string
|
||||
text?: string
|
||||
}
|
||||
```
|
||||
|
||||
## lastUpdated
|
||||
|
||||
- Tipo: `LastUpdatedOptions`
|
||||
|
||||
Permite personalização para o texto de última atualização e o formato de data.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
lastUpdated: {
|
||||
text: 'Atualizado em',
|
||||
formatOptions: {
|
||||
dateStyle: 'full',
|
||||
timeStyle: 'medium'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface LastUpdatedOptions {
|
||||
/**
|
||||
* @default 'Last updated'
|
||||
*/
|
||||
text?: string
|
||||
|
||||
/**
|
||||
* @default
|
||||
* { dateStyle: 'short', timeStyle: 'short' }
|
||||
*/
|
||||
formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
|
||||
}
|
||||
```
|
||||
|
||||
## algolia
|
||||
|
||||
- Tipo: `AlgoliaSearch`
|
||||
|
||||
Uma opção para dar suporte à pesquisa em seu site de documentação usando [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Saiba mais em [Tema Padrão: Pesquisa](./default-theme-search).
|
||||
|
||||
```ts
|
||||
export interface AlgoliaSearchOptions extends DocSearchProps {
|
||||
locales?: Record<string, Partial<DocSearchProps>>
|
||||
}
|
||||
```
|
||||
|
||||
Veja todas as opções [aqui](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts).
|
||||
|
||||
## carbonAds {#carbon-ads}
|
||||
|
||||
- Tipo: `CarbonAdsOptions`
|
||||
|
||||
Uma opção para mostrar [Carbon Ads](https://www.carbonads.net/).
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
carbonAds: {
|
||||
code: 'seu-código-carbon',
|
||||
placement: 'sua-veiculação-carbon'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface CarbonAdsOptions {
|
||||
code: string
|
||||
placement: string
|
||||
}
|
||||
```
|
||||
|
||||
Saiba mais em [Tema Padrão: Carbon Ads](./default-theme-carbon-ads).
|
||||
|
||||
## docFooter
|
||||
|
||||
- Tipo: `DocFooter`
|
||||
|
||||
Pode ser usado para personalizar o texto que aparece acima dos links anterior e próximo. Útil se não estiver escrevendo documentação em inglês. Também pode ser usado para desabilitar globalmente os links anterior/próximo. Se você quiser ativar/desativar seletivamente os links anterior/próximo, pode usar [frontmatter](./default-theme-prev-next-links).
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
docFooter: {
|
||||
prev: 'Página anterior',
|
||||
next: 'Próxima página'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface DocFooter {
|
||||
prev?: string | false
|
||||
next?: string | false
|
||||
}
|
||||
```
|
||||
|
||||
## darkModeSwitchLabel
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `Appearance`
|
||||
|
||||
Pode ser usado para personalizar o rótulo do botão de modo escuro. Esse rótulo é exibido apenas na visualização móvel.
|
||||
|
||||
## lightModeSwitchTitle
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `Switch to light theme`
|
||||
|
||||
Pode ser usado para personalizar o título do botão de modo claro que aparece ao passar o mouse.
|
||||
|
||||
## darkModeSwitchTitle
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `Switch to dark theme`
|
||||
|
||||
Pode ser usado para personalizar o título do botão de modo escuro que aparece ao passar o mouse.
|
||||
|
||||
## sidebarMenuLabel
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `Menu`
|
||||
|
||||
Pode ser usado para personalizar o rótulo do menu da barra lateral. Esse rótulo é exibido apenas na visualização móvel.
|
||||
|
||||
## returnToTopLabel
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `Return to top`
|
||||
|
||||
Pode ser usado para personalizar o rótulo do botão de retorno ao topo. Esse rótulo é exibido apenas na visualização móvel.
|
||||
|
||||
## langMenuLabel
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `Change language`
|
||||
|
||||
Pode ser usado para personalizar o aria-label do botão de idioma na barra de navegação. Isso é usado apenas se você estiver usando [i18n](../guide/i18n).
|
||||
|
||||
## externalLinkIcon
|
||||
|
||||
- Tipo: `boolean`
|
||||
- Padrão: `false`
|
||||
|
||||
Se deve mostrar um ícone de link externo ao lado de links externos no markdown.
|
||||
@ -0,0 +1,60 @@
|
||||
# Editar Link {#edit-link}
|
||||
|
||||
## Configuração a nível de Site {#site-level-config}
|
||||
|
||||
Editar Link permite que você mostre um link para editar a página com serviços de gerenciamento Git, como GitHub ou GitLab. Para habilitar, adicione a opção `themeConfig.editLink` na sua configuração.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A opção `pattern` define a estrutura da URL para o link, e `:path` será substituído com o mesmo caminho de página.
|
||||
|
||||
Você também pode colocar uma função pura que aceita [`PageData`](./runtime-api#usedata) como argumento e retorna uma URL em string.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: ({ filePath }) => {
|
||||
if (filePath.startsWith('packages/')) {
|
||||
return `https://github.com/acme/monorepo/edit/main/${filePath}`
|
||||
} else {
|
||||
return `https://github.com/acme/monorepo/edit/main/docs/${filePath}`
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Isso não deve gerar efeitos colaterais ou acessar qualquer coisa fora do seu escopo, uma vez que será serializado e executado no navegador.
|
||||
|
||||
Por padrão, isso irá adicionar o link com texto "Edite essa página" no final da página de documentação. Você pode personalizar esse texto ao definir a opção `text`.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
editLink: {
|
||||
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
|
||||
text: 'Edite essa página no GitHub'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuração Frontmatter {#frontmatter-config}
|
||||
|
||||
A funcionalidade pode ser desabilitada por página usando a opção `editLink` no frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
editLink: false
|
||||
---
|
||||
```
|
||||
@ -0,0 +1,53 @@
|
||||
# Rodapé {#footer}
|
||||
|
||||
VitePress irá mostrar o rodapé global na parte inferior da página quando `themeConfig.footer` está presente.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
footer: {
|
||||
message: 'Lançado sob Licença MIT.',
|
||||
copyright: 'Direitos Reservados © 2019-present Evan You'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
export interface Footer {
|
||||
// A mensagem mostrada logo antes do copyright.
|
||||
message?: string
|
||||
|
||||
// O próprio texto de copyright.
|
||||
copyright?: string
|
||||
}
|
||||
```
|
||||
|
||||
A configuração acima também suporta strings HTML. Então, por exemplo, se você quiser configurar o texto de rodapé para ter alguns links, você pode ajustar a configuração como o seguinte:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
themeConfig: {
|
||||
footer: {
|
||||
message: 'Lançado sob <a href="https://github.com/vuejs/vitepress/blob/main/LICENSE">Licença MIT</a>.',
|
||||
copyright: 'Direitos Reservados © 2019-present <a href="https://github.com/yyx990803">Evan You</a>'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: warning
|
||||
Apenas elementos _inline_ serão usados em `message` e `copyright` conforme eles são apresentados dentro do elemento `<p>`. Se você quiser adicionar elementos de tipo _block_, considere usar o _slot_ [`layout-bottom`](../guide/extending-default-theme#layout-slots).
|
||||
:::
|
||||
|
||||
Note que o rodapé não será mostrado quando a [Barra Lateral](./default-theme-sidebar) estiver visível.
|
||||
|
||||
## Configuração Frontmatter {#frontmatter-config}
|
||||
|
||||
Isso pode ser desabilitado por página usando a opção `footer` em frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
footer: false
|
||||
---
|
||||
```
|
||||
@ -0,0 +1,168 @@
|
||||
# Página Inicial {#home-page}
|
||||
|
||||
O tema padrão VitePress fornece um layout de página inicial, que você também pode ver em uso [na página inicial deste site](../). Você pode usá-lo em qualquer uma de suas páginas especificando `layout: home` em [frontmatter](./frontmatter-config).
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: home
|
||||
---
|
||||
```
|
||||
|
||||
No entanto, essa opção sozinha não faz muito. Você pode adicionar várias "seções" diferentes pré-modeladas à página inicial definindo opções adicionais como `hero` e `features`.
|
||||
|
||||
## Seção Hero {#hero-section}
|
||||
|
||||
A seção _Hero_ fica no topo da página inicial. Aqui segue como você pode configurar a seção _Hero_.
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: VitePress
|
||||
text: Gerador de site estático com Vite & Vue.
|
||||
tagline: Lorem ipsum...
|
||||
image:
|
||||
src: /logo.png
|
||||
alt: VitePress
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Iniciar
|
||||
link: /guide/what-is-vitepress
|
||||
- theme: alt
|
||||
text: Ver no GitHub
|
||||
link: https://github.com/vuejs/vitepress
|
||||
---
|
||||
```
|
||||
|
||||
```ts
|
||||
interface Hero {
|
||||
// A string mostrada acima de `text`. Vem com a cor da marca
|
||||
// e espera-se que seja curta, como o nome do produto.
|
||||
name?: string
|
||||
|
||||
// O texto principal para a seção hero.
|
||||
// Isso será definido como uma tag `h1`.
|
||||
text: string
|
||||
|
||||
// Slogan exibido abaixo de `text`.
|
||||
tagline?: string
|
||||
|
||||
// A imagem é exibida ao lado da área de texto e slogan.
|
||||
image?: ThemeableImage
|
||||
|
||||
// Botões acionáveis para exibir na seção hero da página inicial.
|
||||
actions?: HeroAction[]
|
||||
}
|
||||
|
||||
type ThemeableImage =
|
||||
| string
|
||||
| { src: string; alt?: string }
|
||||
| { light: string; dark: string; alt?: string }
|
||||
|
||||
interface HeroAction {
|
||||
// Tema de cor do botão. Padrão: `brand`.
|
||||
theme?: 'brand' | 'alt'
|
||||
|
||||
// Rótulo do botão.
|
||||
text: string
|
||||
|
||||
// Destino do link do botão.
|
||||
link: string
|
||||
|
||||
// Atributo target do link.
|
||||
target?: string
|
||||
|
||||
// Atributo rel do link.
|
||||
rel?: string
|
||||
}
|
||||
```
|
||||
|
||||
### Personalizando a cor do nome {#customizing-the-name-color}
|
||||
|
||||
VitePress usa a cor da marca (`--vp-c-brand-1`) para `name`. No entanto, você pode personalizar essa cor sobrescrevendo a variável `--vp-home-hero-name-color`.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--vp-home-hero-name-color: blue;
|
||||
}
|
||||
```
|
||||
|
||||
Você também pode personalizá-la ainda mais combinando `--vp-home-hero-name-background` para dar ao `name` uma cor degradê.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--vp-home-hero-name-color: transparent;
|
||||
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);
|
||||
}
|
||||
```
|
||||
|
||||
## Seção de Funcionalidades {#features-section}
|
||||
|
||||
Na seção de funcionalidades, você pode listar qualquer número de funcionalidades que deseja mostrar imediatamente após a seção _Hero_. Para configurá-la, passe a opção `features` para o frontmatter.
|
||||
|
||||
Você pode fornecer um ícone para cada funcionalidade, que pode ser um emoji ou qualquer tipo de imagem. Quando o ícone configurado é uma imagem (svg, png, jpeg...), você deve fornecer o ícone com a largura e altura apropriadas; você também pode fornecer a descrição, seu tamanho intrínseco, bem como suas variantes para temas escuros e claros quando necessário.
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: home
|
||||
|
||||
features:
|
||||
- icon: 🛠️
|
||||
title: Simples e minimalista, sempre
|
||||
details: Lorem ipsum...
|
||||
- icon:
|
||||
src: /cool-feature-icon.svg
|
||||
title: Outro recurso legal
|
||||
details: Lorem ipsum...
|
||||
- icon:
|
||||
dark: /dark-feature-icon.svg
|
||||
light: /light-feature-icon.svg
|
||||
title: Outro recurso legal
|
||||
details: Lorem ipsum...
|
||||
---
|
||||
```
|
||||
|
||||
```ts
|
||||
interface Feature {
|
||||
// Mostra ícone em cada bloco de funcionalide.
|
||||
icon?: FeatureIcon
|
||||
|
||||
// Título da funcionalidade.
|
||||
title: string
|
||||
|
||||
// Detalhes da funcionalidade.
|
||||
details: string
|
||||
|
||||
// Link quando clicado no componente de funcionalidade.
|
||||
// O link pode ser interno ou externo.
|
||||
//
|
||||
// ex. `guide/reference/default-theme-home-page` ou `https://example.com`
|
||||
link?: string
|
||||
|
||||
// Texto do link a ser exibido dentro do componente de funcionalidade.
|
||||
// Melhor usado com a opção `link`.
|
||||
//
|
||||
// ex. `Saiba mais`, `Visitar página`, etc.
|
||||
linkText?: string
|
||||
|
||||
// Atributo rel do link para a opção `link`.
|
||||
//
|
||||
// ex. `external`
|
||||
rel?: string
|
||||
|
||||
// Atributo target do link para a opção `link`.
|
||||
target?: string
|
||||
}
|
||||
|
||||
type FeatureIcon =
|
||||
| string
|
||||
| { src: string; alt?: string; width?: string; height: string }
|
||||
| {
|
||||
light: string
|
||||
dark: string
|
||||
alt?: string
|
||||
width?: string
|
||||
height: string
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,27 @@
|
||||
# Última Atualização {#last-updated}
|
||||
|
||||
O tempo em que o conteúdo foi atualizado pela última vez será mostrado no canto inferior direito da página. Para habilitar, adicione a opção `lastUpdated` na sua configuração.
|
||||
|
||||
::: tip
|
||||
Você precisa fazer _commit_ no arquivo markdown para ver o tempo atualizado.
|
||||
:::
|
||||
|
||||
## Configuração a nível de Site {#site-level-config}
|
||||
|
||||
```js
|
||||
export default {
|
||||
lastUpdated: true
|
||||
}
|
||||
```
|
||||
|
||||
## Configuração Frontmatter {#frontmatter-config}
|
||||
|
||||
Isso pode ser desabilitado por página usando a opção `lastUpdated` no frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
lastUpdated: false
|
||||
---
|
||||
```
|
||||
|
||||
Refira-se ao [Tema Padrão: Última Atualização](./default-theme-config#lastupdated) para mais detalhes. Qualquer valor positivo a nível de tema também habilitará a funcionalidade a não ser que esteja explicitamente desabilitada a nível de página ou de site.
|
||||
@ -0,0 +1,62 @@
|
||||
# Layout {#layout}
|
||||
|
||||
Você pode escolher o layout da página definindo a opção de `layout` para o [frontmatter](./frontmatter-config) da página. Há três opções de layout: `doc`, `page` e `home`. Se nada for especificado, a página será tratada como página `doc`.
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: doc
|
||||
---
|
||||
```
|
||||
|
||||
## Layout do documento {#doc-layout}
|
||||
|
||||
A opção `doc` é o layout padrão e estiliza todo o conteúdo Markdown com o visual de "documentação". Ela funciona agrupando todo o conteúdo na classe CSS `vp-doc`, e aplicando os estilos aos elementos abaixo dela.
|
||||
|
||||
Quase todos os elementos genéricos, como `p` ou `h2`, recebem um estilo especial. Portanto, lembre-se de que se você adicionar qualquer HTML personalizado dentro de um conteúdo Markdown, ele também será afetado por esses estilos.
|
||||
|
||||
Ele também fornece recursos específicos de documentação listados abaixo. Esses recursos estão habilitados apenas neste layout.
|
||||
|
||||
- Editar link
|
||||
- Links Anterior e Próximo
|
||||
- _Outline_
|
||||
- [Carbon Ads](./default-theme-carbon-ads)
|
||||
|
||||
## Layout da Página {#page-layout}
|
||||
|
||||
A opção `page` é tratada como "página em branco". O Markdown ainda será processado e todas as [Extensões Markdown](../guide/markdown) funcionarão da mesma forma que o layout `doc`, mas este não receberá nenhum estilo padrão.
|
||||
|
||||
O layout da página permitirá que você estilize tudo sem que o tema VitePress afete a marcação. Isso é útil quando você deseja criar sua própria página personalizada.
|
||||
|
||||
Observe que mesmo neste layout, a barra lateral ainda aparecerá se a página tiver uma configuração de barra lateral correspondente.
|
||||
|
||||
## Layout da Home {#home-layout}
|
||||
|
||||
A opção `home` gerará um modelo de _"Homepage"_. Nesse layout você pode definir opções extras, como `hero` e `features`, para personalizar ainda mais o conteúdo. Visite [Tema padrão: Página Inicial](./default-theme-home-page) para obter mais detalhes.
|
||||
|
||||
## Sem Layout {#no-layout}
|
||||
|
||||
Se você não quiser nenhum layout, pode passar `layout: false` pelo frontmatter. Esta opção é útil se você deseja uma página de destino totalmente personalizável (sem barra lateral, barra de navegação ou rodapé por padrão).
|
||||
|
||||
## Layout Personalizado {#custom-layout}
|
||||
|
||||
Você também pode usar um layout personalizado:
|
||||
|
||||
```md
|
||||
---
|
||||
layout: foo
|
||||
---
|
||||
```
|
||||
|
||||
Isto irá procurar um componente chamado `foo` registrado no contexto. Por exemplo, você pode registrar seu componente globalmente em `.vitepress/theme/index.ts`:
|
||||
|
||||
```ts
|
||||
import DefaultTheme from 'vitepress/theme'
|
||||
import Foo from './Foo.vue'
|
||||
|
||||
export default {
|
||||
extends: DefaultTheme,
|
||||
enhanceApp({ app }) {
|
||||
app.component('foo', Foo)
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,162 @@
|
||||
# Navegação {#nav}
|
||||
|
||||
Referente a barra de navegação exibida no topo da página. Ela contém o título do site, links do menu global, e etc.
|
||||
|
||||
## Título do Site e Logo {#site-title-and-logo}
|
||||
|
||||
Por padrão, a navegação mostra o título do site referenciando o valor de [`config.title`](./site-config#title). Se desejar alterar o que é exibido na navegação, você pode definir um texto personalizado na opção `themeConfig.siteTitle`.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
siteTitle: 'Meu Título Personalizado'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Se você tiver um logo para seu site, pode mostrá-lo passando o caminho para a imagem. Você deve colocar o logo diretamente dentro da pasta `public`, e definir o caminho absoluto para ele.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
logo: '/my-logo.svg'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Ao adicionar um logo, ele é mostrado juntamente com o título do site. Se seu logo tem tudo o que você precisa e se você desejar ocultar o texto do título, defina `false` na opção `siteTitle`.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
logo: '/my-logo.svg',
|
||||
siteTitle: false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Você também pode passar um objeto como logo se quiser adicionar um atributo `alt` ou personalizá-lo com base no modo claro/escuro. Consulte [`themeConfig.logo`](./default-theme-config#logo) para obter detalhes.
|
||||
|
||||
## Links de Navegação {#navigation-links}
|
||||
|
||||
Você pode definir a opção `themeConfig.nav` para adicionar links à sua navegação.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Guia', link: '/guide' },
|
||||
{ text: 'Configuração', link: '/config' },
|
||||
{ text: 'Registro de Alterações', link: 'https://github.com/...' }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`text` é o próprio texto mostrado na navegação, e o `link` é o link para o qual será navegado quando o texto for clicado. Para o link, defina o caminho para o próprio arquivo sem o prefixo `.md` e sempre comece com `/`.
|
||||
|
||||
Links de navegação também podem ser menus _dropdown_. Para fazer isso, defina a chave `items` na opção do link.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Guia', link: '/guide' },
|
||||
{
|
||||
text: 'Menu Dropdown',
|
||||
items: [
|
||||
{ text: 'Item A', link: '/item-1' },
|
||||
{ text: 'Item B', link: '/item-2' },
|
||||
{ text: 'Item C', link: '/item-3' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note que o título do menu _dropdown_ (`Menu Dropdown` no exemplo acima) não pode ter a propriedade `link`, pois ele se torna um botão para abrir o diálogo dropdown.
|
||||
|
||||
Você também pode adicionar "seções" aos itens do menu _dropdown_ passando mais itens aninhados.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Guia', link: '/guia' },
|
||||
{
|
||||
text: 'Menu Dropdown',
|
||||
items: [
|
||||
{
|
||||
// Título da seção.
|
||||
text: 'Título da Seção A',
|
||||
items: [
|
||||
{ text: 'Item A da Seção A', link: '...' },
|
||||
{ text: 'Item B da Seção B', link: '...' }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Menu Dropdown',
|
||||
items: [
|
||||
{
|
||||
// Você também pode omitir o título.
|
||||
items: [
|
||||
{ text: 'Item A da Seção A', link: '...' },
|
||||
{ text: 'Item B da Seção B', link: '...' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Personalizar o estado "ativo" do link {#customize-link-s-active-state}
|
||||
|
||||
Os itens do menu de navegação serão destacados quando a página atual estiver no caminho correspondente. Se desejar personalizar o caminho a ser correspondido, defina a propriedade `activeMatch` e regex como um valor em string.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
nav: [
|
||||
// Este link fica no estado ativo quando
|
||||
// o usuário está no caminho `/config/`.
|
||||
{
|
||||
text: 'Guia',
|
||||
link: '/guide',
|
||||
activeMatch: '/config/'
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
::: warning
|
||||
`activeMatch` deve ser uma string regex, mas você deve defini-la como uma string. Não podemos usar um objeto RegExp real aqui porque ele não é serializável durante o momento de construção.
|
||||
:::
|
||||
|
||||
### Personalizar os atributos "target" e "rel" de links {#customize-link-s-target-and-rel-attributes}
|
||||
|
||||
Por padrão, VitePress determina automaticamente os atributos `target` e `rel` baseado em um link externo ou não. Mas se você quiser, também pode personalizá-los.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{
|
||||
text: 'Merchandise',
|
||||
link: 'https://www.thegithubshop.com/',
|
||||
target: '_self',
|
||||
rel: 'sponsored'
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Links Sociais {#social-links}
|
||||
|
||||
Consulte [`socialLinks`](./default-theme-config#sociallinks).
|
||||
@ -0,0 +1,43 @@
|
||||
# Links Anterior e Próximo {#prev-next-links}
|
||||
|
||||
Você pode personalizar o texto e o link para os botões de Anterior e Próximo mostrados ao fim da página. Isso é útil quando você quer mostrar um texto diferente daquele que você tem na barra lateral. Além disso, você pode achar útil desabilitar o rodapé ou link para a página para ela não ser incluída na sua barra lateral.
|
||||
|
||||
## prev
|
||||
|
||||
- Tipo: `string | false | { text?: string; link?: string }`
|
||||
|
||||
- Detalhes:
|
||||
|
||||
Especifica o texto/link para mostrar no link para a página anterior. Se você não ver isso no frontmatter, o texto/link será inferido da configuração da barra lateral.
|
||||
|
||||
- Exemplos:
|
||||
|
||||
- Para personalizar apenas o texto:
|
||||
|
||||
```yaml
|
||||
---
|
||||
prev: 'Iniciar | Markdown'
|
||||
---
|
||||
```
|
||||
|
||||
- Para personalizar ambos texto e link:
|
||||
|
||||
```yaml
|
||||
---
|
||||
prev:
|
||||
text: 'Markdown'
|
||||
link: '/guide/markdown'
|
||||
---
|
||||
```
|
||||
|
||||
- Para esconder a página anterior:
|
||||
|
||||
```yaml
|
||||
---
|
||||
prev: false
|
||||
---
|
||||
```
|
||||
|
||||
## next
|
||||
|
||||
O mesmo que `prev` mas para a próxima página.
|
||||
@ -0,0 +1,379 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Pesquisa {#search}
|
||||
|
||||
## Pesquisa Local {#local-search}
|
||||
|
||||
VitePress oferece suporte à pesquisa de texto completa usando um índice no navegador graças ao [minisearch](https://github.com/lucaong/minisearch/). Para habilitar esse recurso, basta definir a opção `themeConfig.search.provider` como `'local'` no arquivo `.vitepress/config.ts`:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local'
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Exemplo de resultado:
|
||||
|
||||
|
||||
|
||||
Alternativamente, você pode usar [Algolia DocSearch](#algolia-search) ou alguns plugins da comunidade como <https://www.npmjs.com/package/vitepress-plugin-search> ou <https://www.npmjs.com/package/vitepress-plugin-pagefind>.
|
||||
|
||||
### i18n {#local-search-i18n}
|
||||
|
||||
Você pode usar uma configuração como esta para usar a pesquisa multilínguas:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
locales: {
|
||||
zh: {
|
||||
translations: {
|
||||
button: {
|
||||
buttonText: '搜索文档',
|
||||
buttonAriaLabel: '搜索文档'
|
||||
},
|
||||
modal: {
|
||||
noResultsText: '无法找到相关结果',
|
||||
resetButtonTitle: '清除查询条件',
|
||||
footer: {
|
||||
selectText: '选择',
|
||||
navigateText: '切换'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Opções MiniSearch {#mini-search-options}
|
||||
|
||||
Você pode configurar o MiniSearch assim:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
miniSearch: {
|
||||
/**
|
||||
* @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
|
||||
*/
|
||||
options: {
|
||||
/* ... */
|
||||
},
|
||||
/**
|
||||
* @type {import('minisearch').SearchOptions}
|
||||
* @default
|
||||
* { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
|
||||
*/
|
||||
searchOptions: {
|
||||
/* ... */
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Saiba mais na [documentação do MiniSearch](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html).
|
||||
|
||||
### Apresentador de Conteúdo Personalizado {#custom-content-renderer}
|
||||
|
||||
Você pode personalizar a função usada para apresentar o conteúdo markdown antes de indexá-lo:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
/**
|
||||
* @param {string} src
|
||||
* @param {import('vitepress').MarkdownEnv} env
|
||||
* @param {import('markdown-it')} md
|
||||
*/
|
||||
_render(src, env, md) {
|
||||
// retorne a string HTML
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Essa função será removida dos dados do site no lado do cliente, então você pode usar APIs do Node.js nela.
|
||||
|
||||
#### Exemplo: Excluindo páginas da pesquisa {#example-excluding-pages-from-search}
|
||||
|
||||
Você pode excluir páginas da pesquisa adicionando `search: false` ao frontmatter da página. Alternativamente:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
_render(src, env, md) {
|
||||
const html = md.render(src, env)
|
||||
if (env.frontmatter?.search === false) return ''
|
||||
if (env.relativePath.startsWith('algum/caminho')) return ''
|
||||
return html
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::: warning Nota
|
||||
No caso uma função `_render` personalizada ser fornecida, você precisa manipular o `search: false` do frontmatter por conta própria. Além disso, o objeto `env` não estará completamente populado antes que `md.render` seja chamado, então verificações em propriedades opcionais `env`, como `frontmatter`, devem ser feitas após isso.
|
||||
:::
|
||||
|
||||
#### Exemplo: Transformando conteúdo - adicionando âncoras {#example-transforming-content-adding-anchors}
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'local',
|
||||
options: {
|
||||
_render(src, env, md) {
|
||||
const html = md.render(src, env)
|
||||
if (env.frontmatter?.title)
|
||||
return md.render(`# ${env.frontmatter.title}`) + html
|
||||
return html
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Pesquisa Algolia {#algolia-search}
|
||||
|
||||
VitePress oferece suporte à pesquisa em seu site de documentação usando [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Consulte o guia de início deles. Em seu arquivo `.vitepress/config.ts`, você precisará fornecer pelo menos o seguinte para que funcione:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'algolia',
|
||||
options: {
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
indexName: '...'
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### i18n {#algolia-search-i18n} {#algolia-search-i18n}
|
||||
|
||||
Você pode usar uma configuração como esta para usar a pesquisa multilínguas:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
search: {
|
||||
provider: 'algolia',
|
||||
options: {
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
indexName: '...',
|
||||
locales: {
|
||||
zh: {
|
||||
placeholder: '搜索文档',
|
||||
translations: {
|
||||
button: {
|
||||
buttonText: '搜索文档',
|
||||
buttonAriaLabel: '搜索文档'
|
||||
},
|
||||
modal: {
|
||||
searchBox: {
|
||||
resetButtonTitle: '清除查询条件',
|
||||
resetButtonAriaLabel: '清除查询条件',
|
||||
cancelButtonText: '取消',
|
||||
cancelButtonAriaLabel: '取消'
|
||||
},
|
||||
startScreen: {
|
||||
recentSearchesTitle: '搜索历史',
|
||||
noRecentSearchesText: '没有搜索历史',
|
||||
saveRecentSearchButtonTitle: '保存至搜索历史',
|
||||
removeRecentSearchButtonTitle: '从搜索历史中移除',
|
||||
favoriteSearchesTitle: '收藏',
|
||||
removeFavoriteSearchButtonTitle: '从收藏中移除'
|
||||
},
|
||||
errorScreen: {
|
||||
titleText: '无法获取结果',
|
||||
helpText: '你可能需要检查你的网络连接'
|
||||
},
|
||||
footer: {
|
||||
selectText: '选择',
|
||||
navigateText: '切换',
|
||||
closeText: '关闭',
|
||||
searchByText: '搜索提供者'
|
||||
},
|
||||
noResultsScreen: {
|
||||
noResultsText: '无法找到相关结果',
|
||||
suggestedQueryText: '你可以尝试查询',
|
||||
reportMissingResultsText: '你认为该查询应该有结果？',
|
||||
reportMissingResultsLinkText: '点击反馈'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
[Essas opções](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts) podem ser sobrepostas. Consulte a documentação oficial Algolia para obter mais informações sobre elas.
|
||||
|
||||
### Configuração _Crawler_ {#crawler-config}
|
||||
|
||||
Aqui está um exemplo de configuração baseado na qual este site usa:
|
||||
|
||||
```ts
|
||||
new Crawler({
|
||||
appId: '...',
|
||||
apiKey: '...',
|
||||
rateLimit: 8,
|
||||
startUrls: ['https://vitepress.dev/'],
|
||||
renderJavaScript: false,
|
||||
sitemaps: [],
|
||||
exclusionPatterns: [],
|
||||
ignoreCanonicalTo: false,
|
||||
discoveryPatterns: ['https://vitepress.dev/**'],
|
||||
schedule: 'at 05:10 on Saturday',
|
||||
actions: [
|
||||
{
|
||||
indexName: 'vitepress',
|
||||
pathsToMatch: ['https://vitepress.dev/**'],
|
||||
recordExtractor: ({ $, helpers }) => {
|
||||
return helpers.docsearch({
|
||||
recordProps: {
|
||||
lvl1: '.content h1',
|
||||
content: '.content p, .content li',
|
||||
lvl0: {
|
||||
selectors: '',
|
||||
defaultValue: 'Documentation'
|
||||
},
|
||||
lvl2: '.content h2',
|
||||
lvl3: '.content h3',
|
||||
lvl4: '.content h4',
|
||||
lvl5: '.content h5'
|
||||
},
|
||||
indexHeadings: true
|
||||
})
|
||||
}
|
||||
}
|
||||
],
|
||||
initialIndexSettings: {
|
||||
vitepress: {
|
||||
attributesForFaceting: ['type', 'lang'],
|
||||
attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
|
||||
attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
|
||||
attributesToSnippet: ['content:10'],
|
||||
camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
|
||||
searchableAttributes: [
|
||||
'unordered(hierarchy_radio_camel.lvl0)',
|
||||
'unordered(hierarchy_radio.lvl0)',
|
||||
'unordered(hierarchy_radio_camel.lvl1)',
|
||||
'unordered(hierarchy_radio.lvl1)',
|
||||
'unordered(hierarchy_radio_camel.lvl2)',
|
||||
'unordered(hierarchy_radio.lvl2)',
|
||||
'unordered(hierarchy_radio_camel.lvl3)',
|
||||
'unordered(hierarchy_radio.lvl3)',
|
||||
'unordered(hierarchy_radio_camel.lvl4)',
|
||||
'unordered(hierarchy_radio.lvl4)',
|
||||
'unordered(hierarchy_radio_camel.lvl5)',
|
||||
'unordered(hierarchy_radio.lvl5)',
|
||||
'unordered(hierarchy_radio_camel.lvl6)',
|
||||
'unordered(hierarchy_radio.lvl6)',
|
||||
'unordered(hierarchy_camel.lvl0)',
|
||||
'unordered(hierarchy.lvl0)',
|
||||
'unordered(hierarchy_camel.lvl1)',
|
||||
'unordered(hierarchy.lvl1)',
|
||||
'unordered(hierarchy_camel.lvl2)',
|
||||
'unordered(hierarchy.lvl2)',
|
||||
'unordered(hierarchy_camel.lvl3)',
|
||||
'unordered(hierarchy.lvl3)',
|
||||
'unordered(hierarchy_camel.lvl4)',
|
||||
'unordered(hierarchy.lvl4)',
|
||||
'unordered(hierarchy_camel.lvl5)',
|
||||
'unordered(hierarchy.lvl5)',
|
||||
'unordered(hierarchy_camel.lvl6)',
|
||||
'unordered(hierarchy.lvl6)',
|
||||
'content'
|
||||
],
|
||||
distinct: true,
|
||||
attributeForDistinct: 'url',
|
||||
customRanking: [
|
||||
'desc(weight.pageRank)',
|
||||
'desc(weight.level)',
|
||||
'asc(weight.position)'
|
||||
],
|
||||
ranking: [
|
||||
'words',
|
||||
'filters',
|
||||
'typo',
|
||||
'attribute',
|
||||
'proximity',
|
||||
'exact',
|
||||
'custom'
|
||||
],
|
||||
highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
|
||||
highlightPostTag: '</span>',
|
||||
minWordSizefor1Typo: 3,
|
||||
minWordSizefor2Typos: 7,
|
||||
allowTyposOnNumericTokens: false,
|
||||
minProximity: 1,
|
||||
ignorePlurals: true,
|
||||
advancedSyntax: true,
|
||||
attributeCriteriaComputedByMinProximity: true,
|
||||
removeWordsIfNoResults: 'allOptional'
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
<style>
|
||||
img[src="/search.png"] {
|
||||
width: 100%;
|
||||
aspect-ratio: 1 / 1;
|
||||
}
|
||||
</style>
|
||||
@ -0,0 +1,215 @@
|
||||
# Barra Lateral {#sidebar}
|
||||
|
||||
A barra lateral é o bloco principal de navegação da sua documentação. Você pode configurar o menu da barra lateral em [`themeConfig.sidebar`](./default-theme-config#sidebar).
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Guia',
|
||||
items: [
|
||||
{ text: 'Introdução', link: '/introduction' },
|
||||
{ text: 'Iniciando', link: '/getting-started' },
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## O Básico {#the-basics}
|
||||
|
||||
A forma mais simples do menu da barra lateral é passar um único _array_ de links. O item do primeiro nível define a "seção" da barra lateral. Ele deve conter `text`, que é o título da seção, e `items` que são os próprios links de navegação.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Título da Seção A',
|
||||
items: [
|
||||
{ text: 'Item A', link: '/item-a' },
|
||||
{ text: 'Item B', link: '/item-b' },
|
||||
...
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Título da Seção B',
|
||||
items: [
|
||||
{ text: 'Item C', link: '/item-c' },
|
||||
{ text: 'Item D', link: '/item-d' },
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cada `link` deve especificar o caminho para o próprio arquivo começando com `/`. Se você adicionar uma barra no final do link, será mostrado o `index.md` do diretório correspondente.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Guia',
|
||||
items: [
|
||||
// Isso mostra a página `/guide/index.md`.
|
||||
{ text: 'Introdução', link: '/guide/' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Você pode aninhar ainda mais os itens da barra lateral até 6 níveis de profundidade contando a partir do nível raiz. Note que níveis mais profundos que 6 serão ignorados e não serão exibidos na barra lateral.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Nível 1',
|
||||
items: [
|
||||
{
|
||||
text: 'Nível 2',
|
||||
items: [
|
||||
{
|
||||
text: 'Nível 3',
|
||||
items: [
|
||||
...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Múltiplas Barras Laterais {#multiple-sidebars}
|
||||
|
||||
Você pode mostrar uma barra lateral diferente dependendo do caminho da página. Por exemplo, como mostrado neste site, você pode querer criar seções separadas de conteúdo em sua documentação, como a página "Guia" e a página "Configuração".
|
||||
|
||||
Para fazer isso, primeiro organize suas páginas em diretórios para cada seção desejada:
|
||||
|
||||
```
|
||||
.
|
||||
├─ guide/
|
||||
│ ├─ index.md
|
||||
│ ├─ one.md
|
||||
│ └─ two.md
|
||||
└─ config/
|
||||
├─ index.md
|
||||
├─ three.md
|
||||
└─ four.md
|
||||
```
|
||||
|
||||
Em seguida, atualize sua configuração para definir sua barra lateral para cada seção. Desta vez, você deve passar um objeto em vez de um array.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: {
|
||||
// Esta barra lateral é exibida quando um usuário
|
||||
// está no diretório `guide`.
|
||||
'/guide/': [
|
||||
{
|
||||
text: 'Guia',
|
||||
items: [
|
||||
{ text: 'Índice', link: '/guide/' },
|
||||
{ text: 'Um', link: '/guide/one' },
|
||||
{ text: 'Dois', link: '/guide/two' }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
// Esta barra lateral é exibida quando um usuário
|
||||
// está no diretório `config`.
|
||||
'/config/': [
|
||||
{
|
||||
text: 'Configuração',
|
||||
items: [
|
||||
{ text: 'Índice', link: '/config/' },
|
||||
{ text: 'Três', link: '/config/three' },
|
||||
{ text: 'Quatro', link: '/config/four' }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Grupos Retráteis na Barra Lateral {#collapsible-sidebar-groups}
|
||||
|
||||
Adicionando a opção `collapsed` ao grupo da barra lateral, ela mostra um botão para ocultar/mostrar cada seção.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Título da Seção A',
|
||||
collapsed: false,
|
||||
items: [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Todas as seções são "abertas" por padrão. Se você deseja que elas estejam "fechadas" na carga inicial da página, defina a opção `collapsed` como `true`.
|
||||
|
||||
```js
|
||||
export default {
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Título da Seção A',
|
||||
collapsed: true,
|
||||
items: [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## `useSidebar` <Badge type="info" text="composable" />
|
||||
|
||||
Retorna dados relacionados à barra lateral. O objeto retornado tem o seguinte tipo:
|
||||
|
||||
```ts
|
||||
export interface DocSidebar {
|
||||
isOpen: Ref<boolean>
|
||||
sidebar: ComputedRef<DefaultTheme.SidebarItem[]>
|
||||
sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
|
||||
hasSidebar: ComputedRef<boolean>
|
||||
hasAside: ComputedRef<boolean>
|
||||
leftAside: ComputedRef<boolean>
|
||||
isSidebarEnabled: ComputedRef<boolean>
|
||||
open: () => void
|
||||
close: () => void
|
||||
toggle: () => void
|
||||
}
|
||||
```
|
||||
|
||||
**Exemplo:**
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { useSidebar } from 'vitepress/theme'
|
||||
|
||||
const { hasSidebar } = useSidebar()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div v-if="hasSidebar">Visível apenas quando a barra lateral existe</div>
|
||||
</template>
|
||||
```
|
||||
@ -0,0 +1,258 @@
|
||||
<script setup>
|
||||
import { VPTeamMembers } from 'vitepress/theme'
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://github.com/yyx990803.png',
|
||||
name: 'Evan You',
|
||||
title: 'Criador',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/yyx990803' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
|
||||
]
|
||||
},
|
||||
{
|
||||
avatar: 'https://github.com/kiaking.png',
|
||||
name: 'Kia King Ishii',
|
||||
title: 'Desenvolvedor',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/kiaking' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/KiaKing85' }
|
||||
]
|
||||
}
|
||||
]
|
||||
</script>
|
||||
|
||||
# Página da Equipe {#team-page}
|
||||
|
||||
Se você quiser apresentar sua equipe, você pode usar componentes de equipe para construir a Página da Equipe. Existem duas maneiras de usar esses componentes. Uma é incorporá-lo na página de documento, e outra é criar uma Página de Equipe completa.
|
||||
|
||||
## Mostrar membros da equipe em uma página {#show-team-members-in-a-page}
|
||||
|
||||
Você pode usar o componente `<VPTeamMembers>` exposto em `vitepress/theme` para exibir uma lista de membros da equipe em qualquer página.
|
||||
|
||||
```html
|
||||
<script setup>
|
||||
import { VPTeamMembers } from 'vitepress/theme'
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://www.github.com/yyx990803.png',
|
||||
name: 'Evan You',
|
||||
title: 'Criador',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/yyx990803' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
|
||||
]
|
||||
},
|
||||
...
|
||||
]
|
||||
</script>
|
||||
|
||||
# Nosso time
|
||||
|
||||
Diga olá à nossa equipe incrível.
|
||||
|
||||
<VPTeamMembers size="small" :members="members" />
|
||||
```
|
||||
|
||||
O código acima exibirá um membro da equipe em um elemento tipo cartão. Ele deve exibir algo semelhante ao abaixo.
|
||||
|
||||
<VPTeamMembers size="small" :members="members" />
|
||||
|
||||
O componente `<VPTeamMembers>` vem em 2 tamanhos diferentes, pequeno `small` e médio `medium`. Enquanto é uma questão de preferência, geralmente o tamanho `small` deve encaixar melhor quando usado na página de documento. Além disso, você pode adicionar mais propriedades a cada membro, como adicionar o botão "descrição" ou "patrocinador". Saiba mais sobre em [`<VPTeamMembers>`](#vpteammembers).
|
||||
|
||||
Incorporar membros da equipe na página de documento é bom para equipes de pequeno porte, onde ter uma página de equipe inteira dedicada pode ser demais, ou introduzir membros parciais como uma referência ao contexto da documentação.
|
||||
|
||||
Se você tiver um grande número de membros, ou simplesmente quiser ter mais espaço para mostrar os membros da equipe, considere [criar uma página de equipe completa.](#create-a-full-team-page)
|
||||
|
||||
## Criando uma página de equipe completa {#create-a-full-team-page}
|
||||
|
||||
Em vez de adicionar membros da equipe à página de documento, você também pode criar uma Página de Equipe completa, da mesma forma que pode criar uma [Página Inicial](./default-theme-home-page) personalizada.
|
||||
|
||||
Para criar uma página de equipe, primeiro crie um novo arquivo md. O nome do arquivo não importa, mas aqui vamos chamá-lo de `team.md`. Neste arquivo, defina a opção `layout: page` do frontmatter, e então você poderá compor a estrutura da sua página usando componentes `TeamPage`.
|
||||
|
||||
```html
|
||||
---
|
||||
layout: page
|
||||
---
|
||||
<script setup>
|
||||
import {
|
||||
VPTeamPage,
|
||||
VPTeamPageTitle,
|
||||
VPTeamMembers
|
||||
} from 'vitepress/theme'
|
||||
|
||||
const members = [
|
||||
{
|
||||
avatar: 'https://www.github.com/yyx990803.png',
|
||||
name: 'Evan You',
|
||||
title: 'Criador',
|
||||
links: [
|
||||
{ icon: 'github', link: 'https://github.com/yyx990803' },
|
||||
{ icon: 'twitter', link: 'https://twitter.com/youyuxi' }
|
||||
]
|
||||
},
|
||||
...
|
||||
]
|
||||
</script>
|
||||
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>
|
||||
Nosso time
|
||||
</template>
|
||||
<template #lead>
|
||||
O desenvolvimento do VitePress é orientado por uma equipe internacional,
|
||||
alguns dos membros escolheram ser apresentados abaixo.
|
||||
</template>
|
||||
</VPTeamPageTitle>
|
||||
<VPTeamMembers
|
||||
:members="members"
|
||||
/>
|
||||
</VPTeamPage>
|
||||
```
|
||||
|
||||
Ao criar uma página de equipe completa, lembre-se de agrupar todos os componentes com o componente `<VPTeamPage>`. Este componente garantirá que todos os componentes aninhados relacionados à equipe obtenham a estrutura de layout adequada, como espaçamentos.
|
||||
|
||||
O componente `<VPPageTitle>` adiciona a seção de título da página. O título é `<h1>`. Use os _slots_ `#title` e `#lead`para documentar sobre sua equipe.
|
||||
|
||||
`<VPMembers>` funciona da mesma forma que quando usado em uma página de documento. Ele exibirá a lista de membros.
|
||||
|
||||
### Adicione seções para dividir os membros da equipe {#add-sections-to-divide-team-members}
|
||||
|
||||
Você pode adicionar "seções" à página da equipe. Por exemplo, você pode ter diferentes tipos de membros da equipe, como membros da Equipe Principal e Parceiros da Comunidade. Você pode dividir esses membros em seções para explicar melhor os papéis de cada grupo.
|
||||
|
||||
Para fazer isso, adicione o componente `<VPTeamPageSection>` ao arquivo `team.md` que criamos anteriormente.
|
||||
|
||||
```html
|
||||
---
|
||||
layout: page
|
||||
---
|
||||
<script setup>
|
||||
import {
|
||||
VPTeamPage,
|
||||
VPTeamPageTitle,
|
||||
VPTeamMembers,
|
||||
VPTeamPageSection
|
||||
} from 'vitepress/theme'
|
||||
|
||||
const coreMembers = [...]
|
||||
const partners = [...]
|
||||
</script>
|
||||
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>Nosso time</template>
|
||||
<template #lead>...</template>
|
||||
</VPTeamPageTitle>
|
||||
<VPTeamMembers size="medium" :members="coreMembers" />
|
||||
<VPTeamPageSection>
|
||||
<template #title>Parceiros</template>
|
||||
<template #lead>...</template>
|
||||
<template #members>
|
||||
<VPTeamMembers size="small" :members="partners" />
|
||||
</template>
|
||||
</VPTeamPageSection>
|
||||
</VPTeamPage>
|
||||
```
|
||||
|
||||
O componente `<VPTeamPageSection>` pode ter os _slots_ `#title` e `#lead` similar ao componente `VPTeamPageTitle`, e também o _slot_ `#members` para exibir os membros da equipe.
|
||||
|
||||
Lembre-se de colocar o componente `<VPTeamMembers>` dentro do _slot_ `#members`.
|
||||
|
||||
## `<VPTeamMembers>`
|
||||
|
||||
O componente `<VPTeamMembers>` exibe uma determinada lista de membros.
|
||||
|
||||
```html
|
||||
<VPTeamMembers
|
||||
size="medium"
|
||||
:members="[
|
||||
{ avatar: '...', name: '...' },
|
||||
{ avatar: '...', name: '...' },
|
||||
...
|
||||
]"
|
||||
/>
|
||||
```
|
||||
|
||||
```ts
|
||||
interface Props {
|
||||
// Tamanho de cada membro. O padrão é `medium`.
|
||||
size?: 'small' | 'medium'
|
||||
|
||||
// Lista de membros a serem exibidos.
|
||||
members: TeamMember[]
|
||||
}
|
||||
|
||||
interface TeamMember {
|
||||
// Imagem avatar do membro
|
||||
avatar: string
|
||||
|
||||
// Nome do membro.
|
||||
name: string
|
||||
|
||||
// Título a ser mostrado abaixo do nome do membro.
|
||||
// Ex.: Desenvolvedor, Engenheiro de Software, etc.
|
||||
title?: string
|
||||
|
||||
// Organização a qual o membro pertence.
|
||||
org?: string
|
||||
|
||||
// URL da organização.
|
||||
orgLink?: string
|
||||
|
||||
// Descrição do membro.
|
||||
desc?: string
|
||||
|
||||
// Links sociais, por exemplo, GitHub, Twitter, etc.
|
||||
// Você pode passar o objeto de Links Sociais aqui.
|
||||
// Veja: https://vitepress.dev/reference/default-theme-config.html#sociallinks
|
||||
links?: SocialLink[]
|
||||
|
||||
// URL da página de patrocinador do membro.
|
||||
sponsor?: string
|
||||
|
||||
// Texto para o link do patrocinador. O padrão é 'Sponsor'.
|
||||
actionText?: string
|
||||
}
|
||||
```
|
||||
|
||||
## `<VPTeamPage>`
|
||||
|
||||
O componente raiz ao criar uma página de equipe completa. Ele aceita apenas um único _slot_. Ele estilizará todos os componentes relacionados à equipe passados.
|
||||
|
||||
## `<VPTeamPageTitle>`
|
||||
|
||||
Adiciona a seção "título" da página. Melhor usar logo no início sob `<VPTeamPage>`. Aceita os _slots_ `#title` e `#lead`.
|
||||
|
||||
```html
|
||||
<VPTeamPage>
|
||||
<VPTeamPageTitle>
|
||||
<template #title>
|
||||
Nosso time
|
||||
</template>
|
||||
<template #lead>
|
||||
O desenvolvimento do VitePress é orientado por uma equipe internacional,
|
||||
alguns dos membros escolheram ser apresentados abaixo.
|
||||
</template>
|
||||
</VPTeamPageTitle>
|
||||
</VPTeamPage>
|
||||
```
|
||||
|
||||
## `<VPTeamPageSection>`
|
||||
|
||||
Cria uma "seção" na página da equipe. Aceita os _slots_ `#title`, `#lead` e `#members`. Você pode adicionar quantas seções quiser dentro de `<VPTeamPage>`.
|
||||
|
||||
```html
|
||||
<VPTeamPage>
|
||||
...
|
||||
<VPTeamPageSection>
|
||||
<template #title>Parceiros</template>
|
||||
<template #lead>Lorem ipsum...</template>
|
||||
<template #members>
|
||||
<VPTeamMembers :members="data" />
|
||||
</template>
|
||||
</VPTeamPageSection>
|
||||
</VPTeamPage>
|
||||
```
|
||||
@ -0,0 +1,165 @@
|
||||
# API em Tempo de Execução {#runtime-api}
|
||||
|
||||
VitePress oferece várias APIs embutidas para permitir o acesso aos dados da aplicação. VitePress vem também com alguns componentes embutidos que podem ser usados globalmente.
|
||||
|
||||
Os métodos auxiliares são importáveis globais de `vitepress` e geralmente são usados em componentes Vue de temas personalizados. No entanto, eles também podem ser usados dentro de páginas `.md` porque os arquivos markdown são compilados em [Componentes de Arquivo Único Vue (SFC)](https://vuejs.org/guide/scaling-up/sfc.html).
|
||||
|
||||
Métodos que começam com `use*` indicam que é uma função da [API de Composição Vue 3](https://vuejs.org/guide/introduction.html#composition-api) ("Composable") que só pode ser usada dentro de `setup()` ou `<script setup>`.
|
||||
|
||||
## `useData` <Badge type="info" text="composable" />
|
||||
|
||||
Retorna dados específicos da página. O objeto retornado possui o seguinte tipo:
|
||||
|
||||
```ts
|
||||
interface VitePressData<T = any> {
|
||||
/**
|
||||
* Metadados do nível do site
|
||||
*/
|
||||
site: Ref<SiteData<T>>
|
||||
/**
|
||||
* themeConfig de .vitepress/config.js
|
||||
*/
|
||||
theme: Ref<T>
|
||||
/**
|
||||
* Metadados do nível da página
|
||||
*/
|
||||
page: Ref<PageData>
|
||||
/**
|
||||
* Frontmatter da página
|
||||
*/
|
||||
frontmatter: Ref<PageData['frontmatter']>
|
||||
/**
|
||||
* Parâmetros dinâmicos da rota
|
||||
*/
|
||||
params: Ref<PageData['params']>
|
||||
title: Ref<string>
|
||||
description: Ref<string>
|
||||
lang: Ref<string>
|
||||
isDark: Ref<boolean>
|
||||
dir: Ref<string>
|
||||
localeIndex: Ref<string>
|
||||
}
|
||||
|
||||
interface PageData {
|
||||
title: string
|
||||
titleTemplate?: string | boolean
|
||||
description: string
|
||||
relativePath: string
|
||||
filePath: string,
|
||||
headers: Header[]
|
||||
frontmatter: Record<string, any>
|
||||
params?: Record<string, any>
|
||||
isNotFound?: boolean
|
||||
lastUpdated?: number
|
||||
}
|
||||
```
|
||||
|
||||
**Exemplo:**
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { useData } from 'vitepress'
|
||||
|
||||
const { theme } = useData()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<h1>{{ theme.footer.copyright }}</h1>
|
||||
</template>
|
||||
```
|
||||
|
||||
## `useRoute` <Badge type="info" text="composable" />
|
||||
|
||||
Retorna o objeto de rota atual com o seguinte tipo:
|
||||
|
||||
```ts
|
||||
interface Route {
|
||||
path: string
|
||||
data: PageData
|
||||
component: Component | null
|
||||
}
|
||||
```
|
||||
|
||||
## `useRouter` <Badge type="info" text="composable" />
|
||||
|
||||
Retorna a instância do roteador VitePress para que você possa navegar programaticamente para outra página.
|
||||
|
||||
```ts
|
||||
interface Router {
|
||||
/**
|
||||
* Rota atual.
|
||||
*/
|
||||
route: Route
|
||||
/**
|
||||
* Navegar para uma nova URL.
|
||||
*/
|
||||
go: (to?: string) => Promise<void>
|
||||
/**
|
||||
* Chamado antes da mudança de rota. Retorne `false` para cancelar a navegação.
|
||||
*/
|
||||
onBeforeRouteChange?: (to: string) => Awaitable<void | boolean>
|
||||
/**
|
||||
* Chamado antes do carregamento do componente da página (depois que o estado do histórico é
|
||||
* atualizado). Retorne `false` para cancelar a navegação.
|
||||
*/
|
||||
onBeforePageLoad?: (to: string) => Awaitable<void | boolean>
|
||||
/**
|
||||
* Chamado após a mudança de rota.
|
||||
*/
|
||||
onAfterRouteChanged?: (to: string) => Awaitable<void>
|
||||
}
|
||||
```
|
||||
|
||||
## `withBase` <Badge type="info" text="helper" />
|
||||
|
||||
- **Tipo**: `(path: string) => string`
|
||||
|
||||
Anexa o [`base`](./site-config#base) configurado a um caminho de URL fornecido. Veja também [Base URL](../guide/asset-handling#base-url).
|
||||
|
||||
## `<Content />` <Badge type="info" text="component" />
|
||||
|
||||
O componente `<Content />` exibe o conteúdo markdown renderizado. Útil [ao criar seu próprio tema](../guide/custom-theme).
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<h1>Layout Personalizado!</h1>
|
||||
<Content />
|
||||
</template>
|
||||
```
|
||||
|
||||
## `<ClientOnly />` <Badge type="info" text="component" />
|
||||
|
||||
O componente `<ClientOnly />` revela seu _slot_ apenas no lado do cliente.
|
||||
|
||||
Como as aplicações VitePress são interpretadas no lado do servidor em Node.js ao gerar builds estáticos, qualquer uso do Vue deve seguir os requisitos de código universal. Em resumo, certifique-se de acessar apenas APIs do Navegador / DOM em ganchos `beforeMount` ou `mounted`.
|
||||
|
||||
Se você estiver usando ou demonstrando componentes que não são compatíveis com SSR (por exemplo, contêm diretivas personalizadas), você pode envolvê-los dentro do componente `ClientOnly`.
|
||||
|
||||
```vue-html
|
||||
<ClientOnly>
|
||||
<NonSSRFriendlyComponent />
|
||||
</ClientOnly>
|
||||
```
|
||||
|
||||
- Relacionado: [Compatibilidade SSR](../guide/ssr-compat)
|
||||
|
||||
## `$frontmatter` <Badge type="info" text="template global" />
|
||||
|
||||
Acesse diretamente os dados [frontmatter](../guide/frontmatter) da página atual em expressões Vue.
|
||||
|
||||
```md
|
||||
---
|
||||
title: Olá
|
||||
---
|
||||
|
||||
# {{ $frontmatter.title }}
|
||||
```
|
||||
|
||||
## `$params` <Badge type="info" text="template global" />
|
||||
|
||||
Acesse diretamente os [parâmetros de rota dinâmica](../guide/routing#dynamic-routes) da página atual em expressões Vue.
|
||||
|
||||
```md
|
||||
- nome do pacote: {{ $params.pkg }}
|
||||
- versão: {{ $params.version }}
|
||||
```
|
||||
@ -0,0 +1,705 @@
|
||||
---
|
||||
outline: deep
|
||||
---
|
||||
|
||||
# Configuração do Site {#site-config}
|
||||
|
||||
A configuração do site é onde você pode definir as configurações globais do site. As opções de configuração do aplicativo definem configurações que se aplicam a todos os sites VitePress, independentemente do tema que estão usando. Por exemplo, o diretório base ou o título do site.
|
||||
|
||||
## Visão geral {#overview}
|
||||
|
||||
### Resolução de Configuração {#config-resolution}
|
||||
|
||||
O arquivo de configuração é sempre resolvido a partir de `<root>/.vitepress/config.[ext]`, onde `<root>` é a [raiz do projeto](../guide/routing#root-and-source-directory) VitePress e `[ext]` é uma das extensões de arquivo suportadas. O TypeScript é suportado de fábrica. As extensões suportadas incluem `.js`, `.ts`, `.mjs` e `.mts`.
|
||||
|
||||
Recomenda-se usar a sintaxe de módulos ES nos arquivos de configuração. O arquivo de configuração deve exportar por padrão um objeto:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
// opções de configuração de nível da aplicação
|
||||
lang: 'pt-BR',
|
||||
title: 'VitePress',
|
||||
description: 'Gerador de site estático Vite & Vue.',
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
:::details Configuração Dinâmica (Assíncrona)
|
||||
|
||||
Se você precisar gerar dinamicamente a configuração, também pode exportar por padrão uma função. Por exemplo:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default async () => {
|
||||
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
|
||||
|
||||
return defineConfig({
|
||||
// opções de configuração de nível da aplicação
|
||||
lang: 'pt-BR',
|
||||
title: 'VitePress',
|
||||
description: 'Gerador de site estático Vite & Vue.',
|
||||
|
||||
// opções de configuração de nível do tema
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
...posts.map((post) => ({
|
||||
text: post.name,
|
||||
link: `/posts/${post.name}`
|
||||
}))
|
||||
]
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Você também pode usar o `await` no nível superior. Como:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
const posts = await (await fetch('https://my-cms.com/blog-posts')).json()
|
||||
|
||||
export default defineConfig({
|
||||
// opções de configuração de nível da aplicação
|
||||
lang: 'pt-BR',
|
||||
title: 'VitePress',
|
||||
description: 'Gerador de site estático Vite & Vue.',
|
||||
|
||||
// opções de configuração de nível do tema
|
||||
themeConfig: {
|
||||
sidebar: [
|
||||
...posts.map((post) => ({
|
||||
text: post.name,
|
||||
link: `/posts/${post.name}`
|
||||
}))
|
||||
]
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Configuração Intellisense {#config-intellisense}
|
||||
|
||||
Usar o auxiliar `defineConfig` fornecerá Intellisense alimentado por TypeScript para as opções de configuração. Supondo que seu IDE o suporte, isso deve funcionar tanto em JavaScript quanto em TypeScript.
|
||||
|
||||
```js
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
### Configuração de Tema Tipada {#typed-theme-config}
|
||||
|
||||
Por padrão, o auxiliar `defineConfig` espera o tipo de configuração de tema do tema padrão:
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
export default defineConfig({
|
||||
themeConfig: {
|
||||
// O tipo é `DefaultTheme.Config`
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Se você estiver usando um tema personalizado e desejar verificações de tipo para a configuração do tema, será necessário usar `defineConfigWithTheme` em vez disso, e passar o tipo de configuração para o seu tema personalizado por meio de um argumento genérico:
|
||||
|
||||
```ts
|
||||
import { defineConfigWithTheme } from 'vitepress'
|
||||
import type { ThemeConfig } from 'your-theme'
|
||||
|
||||
export default defineConfigWithTheme<ThemeConfig>({
|
||||
themeConfig: {
|
||||
// O tipo é `ThemeConfig`
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Configuração Vite, Vue & Markdown
|
||||
|
||||
- **Vite**
|
||||
|
||||
Você pode configurar a instância subjacente do Vite usando a opção [vite](#vite) em sua configuração VitePress. Não é necessário criar um arquivo de configuração Vite separado.
|
||||
|
||||
- **Vue**
|
||||
|
||||
VitePress já inclui o plugin Vue oficial para Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). Você pode configurar suas opções usando a opção [vue](#vue) em sua configuração VitePress.
|
||||
|
||||
- **Markdown**
|
||||
|
||||
Você pode configurar a instância subjacente de [Markdown-It](https://github.com/markdown-it/markdown-it) usando a opção [markdown](#markdown) em sua configuração VitePress.
|
||||
|
||||
## Metadados do Site {#site-metadata}
|
||||
|
||||
### title
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `VitePress`
|
||||
- Pode ser substituído por página via [frontmatter](./frontmatter-config#title)
|
||||
|
||||
Título do site. Ao usar o tema padrão, isso será exibido na barra de navegação.
|
||||
|
||||
Ele também será usado como o sufixo padrão para todos os títulos individuais das páginas, a menos que [`titleTemplate`](#titletemplate) seja definido. O título final de uma página individual será o conteúdo textual do seu primeiro cabeçalho `<h1>`, combinado com o título global como sufixo. Por exemplo, com a seguinte configuração e conteúdo da página:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
title: 'Meu Site Incrível'
|
||||
}
|
||||
```
|
||||
|
||||
```md
|
||||
# Olá
|
||||
```
|
||||
|
||||
O título da página será `Olá | Meu Site Incrível`.
|
||||
|
||||
### titleTemplate
|
||||
|
||||
- Tipo: `string | boolean`
|
||||
- Pode ser substituído por página via [frontmatter](./frontmatter-config#titletemplate)
|
||||
|
||||
Permite personalizar o sufixo do título de cada página ou o título inteiro. Por exemplo:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
title: 'Meu Site Incrível',
|
||||
titleTemplate: 'Sufixo Personalizado'
|
||||
}
|
||||
```
|
||||
|
||||
```md
|
||||
# Olá
|
||||
```
|
||||
|
||||
O título da página será `Olá | Sufixo Personalizado`.
|
||||
|
||||
Para personalizar completamente como o título deve ser renderizado, você pode usar o símbolo `:title` em `titleTemplate`:
|
||||
|
||||
```ts
|
||||
export default {
|
||||
titleTemplate: ':title - Sufixo Personalizado'
|
||||
}
|
||||
```
|
||||
|
||||
Aqui, `:title` será substituído pelo texto inferido do primeiro cabeçalho `<h1>` da página. O título do exemplo anterior da página será `Olá - Sufixo Personalizado`.
|
||||
|
||||
A opção pode ser definida como `false` para desativar sufixos de título.
|
||||
|
||||
### description
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `Um site VitePress`
|
||||
- Pode ser substituído por página via [frontmatter](./frontmatter-config#descrição)
|
||||
|
||||
Descrição para o site. Isso será apresentado como uma tag `<meta>` na página HTML.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
descrição: 'Um site VitePress'
|
||||
}
|
||||
```
|
||||
|
||||
### head
|
||||
|
||||
- Tipo: `HeadConfig[]`
|
||||
- Padrão: `[]`
|
||||
- Pode ser acrescentado por página via [frontmatter](./frontmatter-config#head)
|
||||
|
||||
Elementos adicionais para adicionar na tag `<head>` da página HTML. As tags adicionadas pelo usuário são mostradas antes da tag `head` de fechamento, após as tags VitePress.
|
||||
|
||||
```ts
|
||||
type HeadConfig =
|
||||
| [string, Record<string, string>]
|
||||
| [string, Record<string, string>, string]
|
||||
```
|
||||
|
||||
#### Exemplo: Adicionando um favicon {#example-adding-a-favicon}
|
||||
|
||||
```ts
|
||||
export default {
|
||||
cabeça: [['link', { rel: 'icon', href: '/favicon.ico' }]]
|
||||
} // coloque o favicon.ico no diretório public, se a base estiver definida, use /base/favicon.ico
|
||||
|
||||
/* Mostraria:
|
||||
<link rel="icon" href="/favicon.ico">
|
||||
*/
|
||||
```
|
||||
|
||||
#### Exemplo: Adicionando Fontes do Google {#example-adding-google-fonts}
|
||||
|
||||
```ts
|
||||
export default {
|
||||
head: [
|
||||
[
|
||||
'link',
|
||||
{ rel: 'preconnect', href: 'https://fonts.googleapis.com' }
|
||||
],
|
||||
[
|
||||
'link',
|
||||
{ rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }
|
||||
],
|
||||
[
|
||||
'link',
|
||||
{ href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }
|
||||
]
|
||||
]
|
||||
}
|
||||
|
||||
/* Mostraria:
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
|
||||
*/
|
||||
```
|
||||
|
||||
#### Exemplo: Registrando um _service worker_ {#example-registering-a-service-worker}
|
||||
|
||||
```ts
|
||||
export default {
|
||||
head: [
|
||||
[
|
||||
'script',
|
||||
{ id: 'register-sw' },
|
||||
`;(() => {
|
||||
if ('serviceWorker' in navigator) {
|
||||
navigator.serviceWorker.register('/sw.js')
|
||||
}
|
||||
})()`
|
||||
]
|
||||
]
|
||||
}
|
||||
|
||||
/* Mostraria:
|
||||
<script id="register-sw">
|
||||
;(() => {
|
||||
if ('serviceWorker' in navigator) {
|
||||
navigator.serviceWorker.register('/sw.js')
|
||||
}
|
||||
})()
|
||||
</script>
|
||||
*/
|
||||
```
|
||||
|
||||
#### Exemplo: Usando o Google Analytics {#example-using-google-analytics}
|
||||
|
||||
```ts
|
||||
export default {
|
||||
head: [
|
||||
[
|
||||
'script',
|
||||
{ async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }
|
||||
],
|
||||
[
|
||||
'script',
|
||||
{},
|
||||
`window.dataLayer = window.dataLayer || [];
|
||||
function gtag(){dataLayer.push(arguments);}
|
||||
gtag('js', new Date());
|
||||
gtag('config', 'TAG_ID');`
|
||||
]
|
||||
]
|
||||
}
|
||||
|
||||
/* Mostraria:
|
||||
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
|
||||
<script>
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
function gtag(){dataLayer.push(arguments);}
|
||||
gtag('js', new Date());
|
||||
gtag('config', 'TAG_ID');
|
||||
</script>
|
||||
*/
|
||||
```
|
||||
|
||||
### lang
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `en-US`
|
||||
|
||||
O atributo de idioma para o site. Isso será mostrado como uma tag `<html lang="en-US">` na página HTML.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
lang: 'en-US'
|
||||
}
|
||||
```
|
||||
|
||||
### base
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `/`
|
||||
|
||||
A URL base em que o site será implantado. Você precisará definir isso se planeja implantar seu site em um subdiretório, por exemplo, no GitHub pages. Se você planeja implantar seu site em `https://foo.github.io/bar/` então você deve definir a base como `'/bar/'`. Deve sempre começar e terminar com uma barra.
|
||||
|
||||
A base é automaticamente adicionada a todos as URLs que começam com / em outras opções, então você só precisa especificá-la uma vez.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
base: '/base/'
|
||||
}
|
||||
```
|
||||
|
||||
## Roteamento {#routing}
|
||||
|
||||
### cleanUrls
|
||||
|
||||
- Tipo: `boolean`
|
||||
- Padrão: `false`
|
||||
|
||||
Quando definido como `true`, VitePress removerá o `.html` no final dos URLs. Veja também [Gerando URL Limpa](../guide/routing#generating-clean-url).
|
||||
|
||||
::: alerta Suporte do Servidor Necessário
|
||||
Ativar isso pode exigir configurações adicionais em sua plataforma de hospedagem. Para funcionar, seu servidor deve ser capaz de servir `/foo.html` ao visitar `/foo` **sem redirecionamento**.
|
||||
:::
|
||||
|
||||
### rewrites
|
||||
|
||||
- Tipo: `Record<string, string>`
|
||||
|
||||
Define mapeamentos personalizados de diretório <-> URL. Veja [Roteamento: Reescrever Rotas](../guide/routing#route-rewrites) para mais detalhes.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
rewrites: {
|
||||
'source/:page': 'destination/:page'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Construção {#build}
|
||||
|
||||
### srcDir
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `.`
|
||||
|
||||
O diretório onde suas páginas de markdown são armazenadas, relativo à raiz do projeto. Veja também [Diretório Raiz e Fonte](../guide/routing#root-and-source-directory).
|
||||
|
||||
```ts
|
||||
export default {
|
||||
srcDir: './src'
|
||||
}
|
||||
```
|
||||
|
||||
### srcExclude
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `undefined`
|
||||
|
||||
Um [padrão glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) para corresponder a arquivos markdown que devem ser excluídos como conteúdo fonte.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
srcExclude: ['**/README.md', '**/TODO.md']
|
||||
}
|
||||
```
|
||||
|
||||
### outDir
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `./.vitepress/dist`
|
||||
|
||||
A localização da saída da compilação para o site, relativa à [raiz do projeto](../guide/routing#root-and-source-directory).
|
||||
|
||||
```ts
|
||||
export default {
|
||||
outDir: '../public'
|
||||
}
|
||||
```
|
||||
|
||||
### assetsDir
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `assets`
|
||||
|
||||
Especifica o diretório para aninhar ativos gerados. O caminho deve estar dentro de [`outDir`](#outdir) e é resolvido em relação a ele.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
assetsDir: 'static'
|
||||
}
|
||||
```
|
||||
|
||||
### cacheDir
|
||||
|
||||
- Tipo: `string`
|
||||
- Padrão: `./.vitepress/cache`
|
||||
|
||||
O diretório para arquivos de cache, relativo à [raiz do projeto](../guide/routing#root-and-source-directory). Veja também: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir).
|
||||
|
||||
```ts
|
||||
export default {
|
||||
cacheDir: './.vitepress/.vite'
|
||||
}
|
||||
```
|
||||
|
||||
### ignoreDeadLinks
|
||||
|
||||
- Tipo: `boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]`
|
||||
- Padrão: `false`
|
||||
|
||||
Quando definido como `true`, VitePress não falhará na compilação devido a links quebrados.
|
||||
|
||||
Quando definido como `'localhostLinks'`, a compilação falhará em links quebrados, mas não verificará links `localhost`.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
ignoreDeadLinks: true
|
||||
}
|
||||
```
|
||||
|
||||
Também pode ser um _array_ de uma exata URL em string, padrões regex, ou funções de filtro personalizadas.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
ignoreDeadLinks: [
|
||||
// ignora URL exata "/playground"
|
||||
'/playground',
|
||||
// ignora todos os links localhost
|
||||
/^https?:\/\/localhost/,
|
||||
// ignora todos os links incluindo "/repl/""
|
||||
/\/repl\//,
|
||||
// função personalizada, ignora todos os links incluindo "ignore"
|
||||
(url) => {
|
||||
return url.toLowerCase().includes('ignore')
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### mpa <Badge type="warning" text="experimental" />
|
||||
|
||||
- Tipo: `boolean`
|
||||
- Padrão: `false`
|
||||
|
||||
Quando definido como `true`, a aplicação em produção será compilada no [Modo MPA](../guide/mpa-mode). O modo MPA envia 0kb de JavaScript por padrão, às custas de desabilitar a navegação no lado do cliente e exigir permissão explícita para interatividade.
|
||||
|
||||
## Tematização {#theming}
|
||||
|
||||
### appearance
|
||||
|
||||
- Tipo: `boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions`
|
||||
- Padrão: `true`
|
||||
|
||||
Se habilitar o modo escuro (adicionando a classe `.dark` ao elemento `<html>`).
|
||||
|
||||
- Se a opção estiver definida como `true` o tema padrão é determinado pelo esquema de cores preferido do usuário.
|
||||
- Se a opção estiver definida como `dark` o tema é escuro por padrão, a menos que o usuário mude manualmente.
|
||||
- Se a opção estiver definida como `false` os usuários não poderão mudar o tema.
|
||||
|
||||
Esta opção injeta um script em linha que restaura as configurações dos usuários do armazenamento local (_local storage_) usando a chave `vitepress-theme-appearance`. Isso garante que a classe `.dark` seja aplicada antes de a página ser mostrada para evitar oscilações.
|
||||
|
||||
`appearance.initialValue` só pode ser `'dark' | undefined`. Refs ou getters não são suportados.
|
||||
|
||||
### lastUpdated
|
||||
|
||||
- Tipo: `boolean`
|
||||
- Padrão: `false`
|
||||
|
||||
Para obter o selo de tempo da última atualização para cada página usando o Git. O selo de data será incluído nos dados de cada página, acessíveis via [`useData`](./runtime-api#usedata).
|
||||
|
||||
Ao usar o tema padrão, habilitar esta opção exibirá o horário da última atualização de cada página. Você pode personalizar o texto via opção [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext).
|
||||
|
||||
## Personalização {#customization}
|
||||
|
||||
### markdown
|
||||
|
||||
- Tipo: `MarkdownOption`
|
||||
|
||||
Configure as opções do processador Markdown. VitePress usa [Markdown-it](https://github.com/markdown-it/markdown-it) como processador e [Shiki](https://github.com/shikijs/shiki) para destacar sintaxe de linguagem. Dentro desta opção, você pode passar várias opções Markdown relacionadas para atender às suas necessidades.
|
||||
|
||||
```js
|
||||
export default {
|
||||
markdown: {...}
|
||||
}
|
||||
```
|
||||
|
||||
Verifique a [declaração de tipo e jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) para todas as opções disponíveis.
|
||||
|
||||
### vite
|
||||
|
||||
- Tipo: `import('vite').UserConfig`
|
||||
|
||||
Passe a [Configuração Vite](https://vitejs.dev/config/) crua para o servidor interno / empacotador Vite.
|
||||
|
||||
```js
|
||||
export default {
|
||||
vite: {
|
||||
// Opções de configuração Vite
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### vue
|
||||
|
||||
- Tipo: `import('@vitejs/plugin-vue').Options`
|
||||
|
||||
Passe as opções [`@vitejs/plugin-vue`](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) cruas para a instância interna do plugin.
|
||||
|
||||
```js
|
||||
export default {
|
||||
vue: {
|
||||
// Opções @vitejs/plugin-vue
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Ganchos de Compilação {#build-hooks}
|
||||
|
||||
Os ganchos de compilação VitePress permitem adicionar novas funcionalidades ao seu site:
|
||||
|
||||
- Sitemap
|
||||
- Indexação de Pesquisa
|
||||
- PWA
|
||||
- _Teleports_
|
||||
|
||||
## buildEnd
|
||||
- Tipo: `(siteConfig: SiteConfig) => Awaitable<void>`
|
||||
`buildEnd` é um gancho de compilação CLI (Interface de Linha de Comando), ele será executado após a conclusão da compilação (SSG), mas antes que o processo VitePress CLI termine.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
async buildEnd(siteConfig) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## postRender
|
||||
- Tipo: `(context: SSGContext) => Awaitable<SSGContext | void>`
|
||||
- `postRender` é um gancho de compilação, chamado quando a interpretação SSG é concluída. Ele permitirá que você manipule o conteúdo de _teleports_ durante a geração de site estático.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
async postRender(context) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
interface SSGContext {
|
||||
content: string
|
||||
teleports?: Record<string, string>
|
||||
[key: string]: any
|
||||
}
|
||||
```
|
||||
|
||||
## transformHead
|
||||
- Tipo: `(context: TransformContext) => Awaitable<HeadConfig[]>`
|
||||
|
||||
`transformHead` é um gancho de compilação para transformar o cabeçalho antes de gerar cada página. Isso permite adicionar entradas no cabeçalho que não podem ser adicionadas estaticamente à configuração VitePress. Você só precisa retornar entradas extras, que serão mescladas automaticamente com as existentes.
|
||||
|
||||
:::warning
|
||||
Não faça mutações em qualquer item dentro de `context`.
|
||||
:::
|
||||
|
||||
```ts
|
||||
export default {
|
||||
async transformHead(context) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
interface TransformContext {
|
||||
page: string // e.g. index.md (relativo a srcDir)
|
||||
assets: string[] // todos os ativos não-js/css com URL pública completamente resolvida
|
||||
siteConfig: SiteConfig
|
||||
siteData: SiteData
|
||||
pageData: PageData
|
||||
title: string
|
||||
description: string
|
||||
head: HeadConfig[]
|
||||
content: string
|
||||
}
|
||||
```
|
||||
|
||||
Note que este gancho só é chamado ao gerar o site estaticamente. Não é chamado durante o desenvolvimento. Se você precisar adicionar entradas de cabeçalho dinâmicas durante o desenvolvimento, pode usar o gancho [`transformPageData`](#transformpagedata) em seu lugar.
|
||||
|
||||
```ts
|
||||
export default {
|
||||
transformPageData(pageData) {
|
||||
pageData.frontmatter.head ??= []
|
||||
pageData.frontmatter.head.push([
|
||||
'meta',
|
||||
{
|
||||
name: 'og:title',
|
||||
content:
|
||||
pageData.frontmatter.layout === 'home'
|
||||
? `VitePress`
|
||||
: `${pageData.title} | VitePress`
|
||||
}
|
||||
])
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Exemplo: Adicionar URL canônica `<link>` {#example-adding-a-canonical-url-link}
|
||||
|
||||
```ts
|
||||
export default {
|
||||
transformPageData(pageData) {
|
||||
const canonicalUrl = `https://example.com/${pageData.relativePath}`
|
||||
.replace(/index\.md$/, '')
|
||||
.replace(/\.md$/, '.html')
|
||||
|
||||
pageData.frontmatter.head ??= []
|
||||
pageData.frontmatter.head.push([
|
||||
'link',
|
||||
{ rel: 'canonical', href: canonicalUrl }
|
||||
])
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### transformHtml
|
||||
- Tipo: `(code: string, id: string, context: TransformContext) => Awaitable<string | void>`
|
||||
`transformHtml` é um gancho de compilação para transformar o conteúdo de cada página antes de salvá-lo no disco.
|
||||
|
||||
:::warning
|
||||
Não faça mutações em qualquer item dentro de `context`. Além disso, modificar o conteúdo HTML pode causar problemas de hidratação em tempo de execução.
|
||||
:::
|
||||
|
||||
```ts
|
||||
export default {
|
||||
async transformHtml(code, id, context) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### transformPageData
|
||||
- Tipo: `(pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>`
|
||||
|
||||
`transformPageData` é um gancho para transformar os dados de cada página. Você pode fazer mutações diretamente em `pageData` ou retornar valores alterados que serão mesclados nos dados da página.
|
||||
|
||||
:::warning
|
||||
Não faça mutações em qualquer item dentro de `context` e tenha cuidado pois isso pode impactar no desempenho do servidor de desenvolvimento, especialmente se você tiver algumas solicitações de rede ou computações pesadas (como gerar imagens) no gancho. Você pode verificar `process.env.NODE_ENV === 'production'` para lógica condicional.
|
||||
:::
|
||||
|
||||
```ts
|
||||
export default {
|
||||
async transformPageData(pageData, { siteConfig }) {
|
||||
pageData.contributors = await getPageContributors(pageData.relativePath)
|
||||
}
|
||||
|
||||
// ou retorne dados a serem mesclados
|
||||
async transformPageData(pageData, { siteConfig }) {
|
||||
return {
|
||||
contributors: await getPageContributors(pageData.relativePath)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
interface TransformPageContext {
|
||||
siteConfig: SiteConfig
|
||||
}
|
||||
```
|
||||
@ -1,3 +1,6 @@
|
||||
/assets/*
|
||||
cache-control: max-age=31536000
|
||||
cache-control: immutable
|
||||
|
||||
/_translations/*
|
||||
x-robots-tag: noindex
|
||||
|
||||
|
After Width: | Height: | Size: 94 KiB |
|
After Width: | Height: | Size: 33 KiB |
|
After Width: | Height: | Size: 2.0 KiB |
|
After Width: | Height: | Size: 2.4 KiB |
|
After Width: | Height: | Size: 249 KiB |
@ -0,0 +1,80 @@
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue'
|
||||
const showModal = ref(false)
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<button class="modal-button" @click="showModal = true">
|
||||
Показать модальное окно
|
||||
</button>
|
||||
|
||||
<Teleport to="body">
|
||||
<Transition name="modal">
|
||||
<div v-show="showModal" class="modal-mask">
|
||||
<div class="modal-container">
|
||||
<p>Привет из модального окна!</p>
|
||||
<div class="model-footer">
|
||||
<button class="modal-button" @click="showModal = false">
|
||||
Закрыть
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</Transition>
|
||||
</Teleport>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.modal-mask {
|
||||
position: fixed;
|
||||
z-index: 200;
|
||||
top: 0;
|
||||
left: 0;
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
background-color: rgba(0, 0, 0, 0.5);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
transition: opacity 0.3s ease;
|
||||
}
|
||||
|
||||
.modal-container {
|
||||
width: 300px;
|
||||
margin: auto;
|
||||
padding: 20px 30px;
|
||||
background-color: var(--vp-c-bg);
|
||||
border-radius: 2px;
|
||||
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.33);
|
||||
transition: all 0.3s ease;
|
||||
}
|
||||
|
||||
.model-footer {
|
||||
margin-top: 8px;
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
.modal-button {
|
||||
padding: 4px 8px;
|
||||
border-radius: 4px;
|
||||
border-color: var(--vp-button-alt-border);
|
||||
color: var(--vp-button-alt-text);
|
||||
background-color: var(--vp-button-alt-bg);
|
||||
}
|
||||
|
||||
.modal-button:hover {
|
||||
border-color: var(--vp-button-alt-hover-border);
|
||||
color: var(--vp-button-alt-hover-text);
|
||||
background-color: var(--vp-button-alt-hover-bg);
|
||||
}
|
||||
|
||||
.modal-enter-from,
|
||||
.modal-leave-to {
|
||||
opacity: 0;
|
||||
}
|
||||
|
||||
.modal-enter-from .modal-container,
|
||||
.modal-leave-to .modal-container {
|
||||
transform: scale(1.1);
|
||||
}
|
||||
</style>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue