From 532389270bbf76859a14a368bd05eeb919729352 Mon Sep 17 00:00:00 2001 From: etuardu Date: Wed, 28 Feb 2024 13:44:31 +0100 Subject: [PATCH 01/13] docs: linked files not treated as assets (#3615) close #3535 --- docs/guide/asset-handling.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guide/asset-handling.md b/docs/guide/asset-handling.md index 7d2ce57a..eeedc8c0 100644 --- a/docs/guide/asset-handling.md +++ b/docs/guide/asset-handling.md @@ -12,6 +12,10 @@ You can reference static assets in your markdown files, your `*.vue` components Common image, media, and font filetypes are detected and included as assets automatically. +::: tip Linked files are not treated as assets +PDFs or other documents referenced by links within markdown files are not automatically treated as assets. To make linked files accessible, you must manually place them within the [`public`](#the-public-directory) directory of your project. +::: + All referenced assets, including those using absolute paths, will be copied to the output directory with a hashed file name in the production build. Never-referenced assets will not be copied. Image assets smaller than 4kb will be base64 inlined - this can be configured via the [`vite`](../reference/site-config#vite) config option. All **static** path references, including absolute paths, should be based on your working directory structure. From 75bed4f836b32047e70e9c95e387c7014fd4050c Mon Sep 17 00:00:00 2001 From: Bairui Su Date: Thu, 29 Feb 2024 21:10:43 +0800 Subject: [PATCH 02/13] docs: fix config path in guide/custom-theme.md (#3618) --- docs/guide/custom-theme.md | 4 ++-- docs/zh/guide/custom-theme.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide/custom-theme.md b/docs/guide/custom-theme.md index 83625a23..1d168ce9 100644 --- a/docs/guide/custom-theme.md +++ b/docs/guide/custom-theme.md @@ -196,7 +196,7 @@ export default { If the theme requires special VitePress config, you will need to also extend it in your own config: ```ts -// .vitepress/theme/config.ts +// .vitepress/config.ts import baseConfig from 'awesome-vitepress-theme/config' export default { @@ -208,7 +208,7 @@ export default { Finally, if the theme provides types for its theme config: ```ts -// .vitepress/theme/config.ts +// .vitepress/config.ts import baseConfig from 'awesome-vitepress-theme/config' import { defineConfigWithTheme } from 'vitepress' import type { ThemeConfig } from 'awesome-vitepress-theme' diff --git a/docs/zh/guide/custom-theme.md b/docs/zh/guide/custom-theme.md index 4a78185f..e5eb760b 100644 --- a/docs/zh/guide/custom-theme.md +++ b/docs/zh/guide/custom-theme.md @@ -196,7 +196,7 @@ export default { 如果主题需要特殊的 VitePress 配置，也需要在配置中扩展： ```ts -// .vitepress/theme/config.ts +// .vitepress/config.ts import baseConfig from 'awesome-vitepress-theme/config' export default { @@ -208,7 +208,7 @@ export default { 最后，如果主题为其主题配置提供了类型： ```ts -// .vitepress/theme/config.ts +// .vitepress/config.ts import baseConfig from 'awesome-vitepress-theme/config' import { defineConfigWithTheme } from 'vitepress' import type { ThemeConfig } from 'awesome-vitepress-theme' From 489391cdbeab73d3f62ef5de4a0528e3c93e0ee8 Mon Sep 17 00:00:00 2001 From: Xavi Lee Date: Sun, 3 Mar 2024 14:09:52 +0800 Subject: [PATCH 03/13] docs(zh): update a link and sync translations (#3624) sync with https://github.com/vuejs/vitepress/commit/532389270bbf76859a14a368bd05eeb919729352 --- docs/zh/guide/asset-handling.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/zh/guide/asset-handling.md b/docs/zh/guide/asset-handling.md index fa6478ca..69259a6a 100644 --- a/docs/zh/guide/asset-handling.md +++ b/docs/zh/guide/asset-handling.md @@ -2,7 +2,7 @@ ## 引用静态资源 {#referencing-static-assets} -所有的 Markdown 文件都会被编译成 Vue 组件，并由 [Vite](https://vitejs.dev/guide/assets.html) 处理。可以**并且应该**使用相对路径来引用资源： +所有的 Markdown 文件都会被编译成 Vue 组件，并由 [Vite](https://cn.vitejs.dev/guide/assets.html) 处理。可以**并且应该**使用相对路径来引用资源： ```md ![An image](./image.png) @@ -12,6 +12,10 @@ 常见的图像，媒体和字体文件会被自动检测并视作资源。 +::: tip 通过链接引用的文件不会视作资源 +在 Markdown 内，通过链接引用的 PDF 或者其他文档不会被自动视作资源。要使这些文件可用，你必须手动将其放在项目的 [`public`](#the-public-directory) 目录内。 +::: + 所有引用的资源，包括那些使用绝对路径的，都会在生产构建过程中被复制到输出目录，并使用哈希文件名。从未使用过的资源将不会被复制。小于 4kb 的图像资源将会采用 base64 内联——这可以通过 [`vite`](../reference/site-config#vite) 配置选项进行配置。 所有**静态**路径引用，包括绝对路径，都应基于你的工作目录的结构。 From 90eab25b709da2a501d9ffe4ec78f6904076fcee Mon Sep 17 00:00:00 2001 From: Pavel Horal Date: Sun, 3 Mar 2024 11:24:14 +0100 Subject: [PATCH 04/13] docs: remove unnecessary nojekyll for GitHub Actions deployment (#3630) --- docs/guide/deploy.md | 4 +--- docs/zh/guide/deploy.md | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/guide/deploy.md b/docs/guide/deploy.md index c9716855..83835eed 100644 --- a/docs/guide/deploy.md +++ b/docs/guide/deploy.md @@ -168,9 +168,7 @@ Don't enable options like _Auto Minify_ for HTML code. It will remove comments f - name: Install dependencies run: npm ci # or pnpm install / yarn install / bun install - name: Build with VitePress - run: | - npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build - touch docs/.vitepress/dist/.nojekyll + run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/docs/zh/guide/deploy.md b/docs/zh/guide/deploy.md index cb2b0974..d8ac6cca 100644 --- a/docs/zh/guide/deploy.md +++ b/docs/zh/guide/deploy.md @@ -168,9 +168,7 @@ Cache-Control: max-age=31536000,immutable - name: Install dependencies run: npm ci # 或 pnpm install / yarn install / bun install - name: Build with VitePress - run: | - npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build - touch docs/.vitepress/dist/.nojekyll + run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: From f6bd99eb1311238e1114301a767634b139327916 Mon Sep 17 00:00:00 2001 From: Lo Date: Wed, 6 Mar 2024 13:25:24 +0800 Subject: [PATCH 05/13] feat: add `window.__VITEPRESS__` (#3634) --- src/client/app/index.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/client/app/index.ts b/src/client/app/index.ts index 57cfe15a..911760a1 100644 --- a/src/client/app/index.ts +++ b/src/client/app/index.ts @@ -64,6 +64,8 @@ const VitePressApp = defineComponent({ }) export async function createApp() { + ;(globalThis as any).__VITEPRESS__ = true + const router = newRouter() const app = newApp() From 6b971a08f5ee1593dcda6252835b5404db87c2f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=83=BD=E5=AE=81?= Date: Wed, 6 Mar 2024 22:49:44 +0800 Subject: [PATCH 06/13] fix(router): hashchange not emitted in certain cases (#3637) Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> --- src/client/app/router.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/client/app/router.ts b/src/client/app/router.ts index 00c98531..7370d9e3 100644 --- a/src/client/app/router.ts +++ b/src/client/app/router.ts @@ -180,7 +180,7 @@ export function createRouter( : link.href, link.baseURI ) - const currentUrl = window.location + const currentUrl = new URL(window.location.href) // copy to keep old data // only intercept inbound html links if ( !e.ctrlKey && @@ -211,7 +211,12 @@ export function createRouter( window.scrollTo(0, 0) } } else { - go(href) + go(href).then(() => { + // do after the route is changed so location.hash in theme code is the new hash + if (hash !== currentUrl.hash) { + window.dispatchEvent(new Event('hashchange')) + } + }) } } } From 2df9bab566b59f85a5c9b4d5e17c58cc37e27924 Mon Sep 17 00:00:00 2001 From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> Date: Wed, 6 Mar 2024 20:32:51 +0530 Subject: [PATCH 07/13] chore: adjust fix for #3637 --- src/client/app/router.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/client/app/router.ts b/src/client/app/router.ts index 7370d9e3..bc282367 100644 --- a/src/client/app/router.ts +++ b/src/client/app/router.ts @@ -64,11 +64,16 @@ export function createRouter( } async function go(href: string = inBrowser ? location.href : '/') { + const currentHash = inBrowser ? location.hash : '' href = normalizeHref(href) if ((await router.onBeforeRouteChange?.(href)) === false) return updateHistory(href) await loadPage(href) await router.onAfterRouteChanged?.(href) + // do after the route is changed so location.hash in theme code is the new hash + if (new URL(href, fakeHost).hash !== currentHash) { + window.dispatchEvent(new Event('hashchange')) + } } let latestPendingPath: string | null = null @@ -211,12 +216,7 @@ export function createRouter( window.scrollTo(0, 0) } } else { - go(href).then(() => { - // do after the route is changed so location.hash in theme code is the new hash - if (hash !== currentUrl.hash) { - window.dispatchEvent(new Event('hashchange')) - } - }) + go(href) } } } From 6c0125b65513531870f00ebef1ae11096027875a Mon Sep 17 00:00:00 2001 From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> Date: Wed, 6 Mar 2024 20:42:08 +0530 Subject: [PATCH 08/13] chore: tweak hashchange emitting a bit --- src/client/app/router.ts | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/client/app/router.ts b/src/client/app/router.ts index bc282367..3f90c213 100644 --- a/src/client/app/router.ts +++ b/src/client/app/router.ts @@ -64,16 +64,11 @@ export function createRouter( } async function go(href: string = inBrowser ? location.href : '/') { - const currentHash = inBrowser ? location.hash : '' href = normalizeHref(href) if ((await router.onBeforeRouteChange?.(href)) === false) return updateHistory(href) await loadPage(href) await router.onAfterRouteChanged?.(href) - // do after the route is changed so location.hash in theme code is the new hash - if (new URL(href, fakeHost).hash !== currentHash) { - window.dispatchEvent(new Event('hashchange')) - } } let latestPendingPath: string | null = null @@ -212,7 +207,7 @@ export function createRouter( // use smooth scroll when clicking on header anchor links scrollTo(link, hash, link.classList.contains('header-anchor')) } else { - updateHistory(href) + updateHistory(href, false) // already emitted hashchange above window.scrollTo(0, 0) } } else { @@ -305,11 +300,15 @@ function shouldHotReload(payload: PageDataPayload): boolean { return payloadPath === locationPath } -function updateHistory(href: string) { +function updateHistory(href: string, emitHashChange = true) { if (inBrowser && normalizeHref(href) !== normalizeHref(location.href)) { + const currentHash = location.hash // save scroll position before changing url history.replaceState({ scrollPosition: window.scrollY }, document.title) history.pushState(null, '', href) + if (emitHashChange && new URL(href, fakeHost).hash !== currentHash) { + window.dispatchEvent(new Event('hashchange')) + } } } From a88a257da07022a18c6d0905fea3bdbf67360ea6 Mon Sep 17 00:00:00 2001 From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> Date: Wed, 6 Mar 2024 20:51:41 +0530 Subject: [PATCH 09/13] release: v1.0.0-rc.45 --- CHANGELOG.md | 10 ++++++++++ package.json | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 271ca1eb..4207b2d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,13 @@ +# [1.0.0-rc.45](https://github.com/vuejs/vitepress/compare/v1.0.0-rc.44...v1.0.0-rc.45) (2024-03-06) + +### Bug Fixes + +- **router:** hashchange not emitted in certain cases ([#3637](https://github.com/vuejs/vitepress/issues/3637)) ([f6bd99e...6c0125b](https://github.com/vuejs/vitepress/compare/f6bd99eb1311238e1114301a767634b139327916...6c0125b65513531870f00ebef1ae11096027875a)) + +### Features + +- set `__VITEPRESS__` for easy detection by plugins and other tools ([#3634](https://github.com/vuejs/vitepress/issues/3634)) ([f6bd99e](https://github.com/vuejs/vitepress/commit/f6bd99eb1311238e1114301a767634b139327916)) + # [1.0.0-rc.44](https://github.com/vuejs/vitepress/compare/v1.0.0-rc.43...v1.0.0-rc.44) (2024-2-19) ### Reverts diff --git a/package.json b/package.json index 729d579e..bf7c3b70 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "vitepress", - "version": "1.0.0-rc.44", + "version": "1.0.0-rc.45", "description": "Vite & Vue powered static site generator", "type": "module", "packageManager": "pnpm@8.15.3", From 49ea062b3984440b98aeb1158b390d92d7fe4670 Mon Sep 17 00:00:00 2001 From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> Date: Wed, 6 Mar 2024 21:21:31 +0530 Subject: [PATCH 10/13] refactor: more cleanup --- src/client/app/router.ts | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/src/client/app/router.ts b/src/client/app/router.ts index 3f90c213..cb4058f6 100644 --- a/src/client/app/router.ts +++ b/src/client/app/router.ts @@ -66,7 +66,17 @@ export function createRouter( async function go(href: string = inBrowser ? location.href : '/') { href = normalizeHref(href) if ((await router.onBeforeRouteChange?.(href)) === false) return - updateHistory(href) + if (inBrowser) { + const currentUrl = new URL(location.href) + if (href !== normalizeHref(currentUrl.href)) { + // save scroll position before changing url + history.replaceState({ scrollPosition: window.scrollY }, document.title) + history.pushState(null, '', href) + if (new URL(href, fakeHost).hash !== currentUrl.hash) { + window.dispatchEvent(new Event('hashchange')) + } + } + } await loadPage(href) await router.onAfterRouteChanged?.(href) } @@ -180,7 +190,7 @@ export function createRouter( : link.href, link.baseURI ) - const currentUrl = new URL(window.location.href) // copy to keep old data + const currentUrl = new URL(location.href) // copy to keep old data // only intercept inbound html links if ( !e.ctrlKey && @@ -199,7 +209,7 @@ export function createRouter( // scroll between hash anchors in the same page // avoid duplicate history entries when the hash is same if (hash !== currentUrl.hash) { - history.pushState(null, '', hash) + history.pushState(null, '', href) // still emit the event so we can listen to it in themes window.dispatchEvent(new Event('hashchange')) } @@ -207,7 +217,6 @@ export function createRouter( // use smooth scroll when clicking on header anchor links scrollTo(link, hash, link.classList.contains('header-anchor')) } else { - updateHistory(href, false) // already emitted hashchange above window.scrollTo(0, 0) } } else { @@ -300,18 +309,6 @@ function shouldHotReload(payload: PageDataPayload): boolean { return payloadPath === locationPath } -function updateHistory(href: string, emitHashChange = true) { - if (inBrowser && normalizeHref(href) !== normalizeHref(location.href)) { - const currentHash = location.hash - // save scroll position before changing url - history.replaceState({ scrollPosition: window.scrollY }, document.title) - history.pushState(null, '', href) - if (emitHashChange && new URL(href, fakeHost).hash !== currentHash) { - window.dispatchEvent(new Event('hashchange')) - } - } -} - function normalizeHref(href: string): string { const url = new URL(href, fakeHost) url.pathname = url.pathname.replace(/(^|\/)index(\.html)?$/, '$1') From 2b40266dacc1145542ec67937a54304ead1b7a67 Mon Sep 17 00:00:00 2001 From: viniciusdeliz Date: Thu, 7 Mar 2024 04:30:37 -0300 Subject: [PATCH 11/13] docs(pt): Create Portuguese VitePress translation (#3531) Co-authored-by: Savio Nascimento Co-authored-by: Xavi Lee Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> --- docs/.vitepress/config/index.ts | 4 +- docs/.vitepress/config/pt.ts | 212 ++++ docs/.vitepress/config/shared.ts | 3 +- docs/lunaria.config.json | 6 +- docs/pt/guide/asset-handling.md | 59 ++ docs/pt/guide/cms.md | 56 ++ docs/pt/guide/custom-theme.md | 222 +++++ docs/pt/guide/data-loading.md | 248 +++++ docs/pt/guide/deploy.md | 291 ++++++ docs/pt/guide/extending-default-theme.md | 340 +++++++ docs/pt/guide/frontmatter.md | 48 + docs/pt/guide/getting-started.md | 208 ++++ docs/pt/guide/i18n.md | 113 +++ docs/pt/guide/markdown.md | 929 ++++++++++++++++++ docs/pt/guide/mpa-mode.md | 23 + docs/pt/guide/routing.md | 372 +++++++ docs/pt/guide/sitemap-generation.md | 53 + docs/pt/guide/ssr-compat.md | 136 +++ docs/pt/guide/using-vue.md | 255 +++++ docs/pt/guide/what-is-vitepress.md | 57 ++ docs/pt/index.md | 57 ++ docs/pt/reference/cli.md | 74 ++ docs/pt/reference/default-theme-badge.md | 69 ++ docs/pt/reference/default-theme-carbon-ads.md | 22 + docs/pt/reference/default-theme-config.md | 451 +++++++++ docs/pt/reference/default-theme-edit-link.md | 60 ++ docs/pt/reference/default-theme-footer.md | 53 + docs/pt/reference/default-theme-home-page.md | 168 ++++ .../reference/default-theme-last-updated.md | 27 + docs/pt/reference/default-theme-layout.md | 62 ++ docs/pt/reference/default-theme-nav.md | 162 +++ .../default-theme-prev-next-links.md | 43 + docs/pt/reference/default-theme-search.md | 379 +++++++ docs/pt/reference/default-theme-sidebar.md | 215 ++++ docs/pt/reference/default-theme-team-page.md | 258 +++++ docs/pt/reference/frontmatter-config.md | 221 +++++ docs/pt/reference/runtime-api.md | 165 ++++ docs/pt/reference/site-config.md | 705 +++++++++++++ 38 files changed, 6823 insertions(+), 3 deletions(-) create mode 100644 docs/.vitepress/config/pt.ts create mode 100644 docs/pt/guide/asset-handling.md create mode 100644 docs/pt/guide/cms.md create mode 100644 docs/pt/guide/custom-theme.md create mode 100644 docs/pt/guide/data-loading.md create mode 100644 docs/pt/guide/deploy.md create mode 100644 docs/pt/guide/extending-default-theme.md create mode 100644 docs/pt/guide/frontmatter.md create mode 100644 docs/pt/guide/getting-started.md create mode 100644 docs/pt/guide/i18n.md create mode 100644 docs/pt/guide/markdown.md create mode 100644 docs/pt/guide/mpa-mode.md create mode 100644 docs/pt/guide/routing.md create mode 100644 docs/pt/guide/sitemap-generation.md create mode 100644 docs/pt/guide/ssr-compat.md create mode 100644 docs/pt/guide/using-vue.md create mode 100644 docs/pt/guide/what-is-vitepress.md create mode 100644 docs/pt/index.md create mode 100644 docs/pt/reference/cli.md create mode 100644 docs/pt/reference/default-theme-badge.md create mode 100644 docs/pt/reference/default-theme-carbon-ads.md create mode 100644 docs/pt/reference/default-theme-config.md create mode 100644 docs/pt/reference/default-theme-edit-link.md create mode 100644 docs/pt/reference/default-theme-footer.md create mode 100644 docs/pt/reference/default-theme-home-page.md create mode 100644 docs/pt/reference/default-theme-last-updated.md create mode 100644 docs/pt/reference/default-theme-layout.md create mode 100644 docs/pt/reference/default-theme-nav.md create mode 100644 docs/pt/reference/default-theme-prev-next-links.md create mode 100644 docs/pt/reference/default-theme-search.md create mode 100644 docs/pt/reference/default-theme-sidebar.md create mode 100644 docs/pt/reference/default-theme-team-page.md create mode 100644 docs/pt/reference/frontmatter-config.md create mode 100644 docs/pt/reference/runtime-api.md create mode 100644 docs/pt/reference/site-config.md diff --git a/docs/.vitepress/config/index.ts b/docs/.vitepress/config/index.ts index de218788..d5348e6f 100644 --- a/docs/.vitepress/config/index.ts +++ b/docs/.vitepress/config/index.ts @@ -2,11 +2,13 @@ import { defineConfig } from 'vitepress' import { shared } from './shared' import { en } from './en' import { zh } from './zh' +import { pt } from './pt' export default defineConfig({ ...shared, locales: { root: { label: 'English', ...en }, - zh: { label: '简体中文', ...zh } + zh: { label: '简体中文', ...zh }, + pt: { label: 'Português', ...pt } } }) diff --git a/docs/.vitepress/config/pt.ts b/docs/.vitepress/config/pt.ts new file mode 100644 index 00000000..f8ce02a1 --- /dev/null +++ b/docs/.vitepress/config/pt.ts @@ -0,0 +1,212 @@ +import { createRequire } from 'module' +import { defineConfig, type DefaultTheme } from 'vitepress' + +const require = createRequire(import.meta.url) +const pkg = require('vitepress/package.json') + +export const pt = defineConfig({ + lang: 'pt-BR', + description: 'Gerador de Site Estático desenvolvido com Vite e Vue.', + + themeConfig: { + nav: nav(), + + sidebar: { + '/pt/guide/': { base: '/pt/guide/', items: sidebarGuide() }, + '/pt/reference/': { base: '/pt/reference/', items: sidebarReference() } + }, + + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', + text: 'Edite esta página no GitHub' + }, + + footer: { + message: 'Lançado sob licença MIT', + copyright: `Direitos reservados © 2019-${new Date().getFullYear()} Evan You` + }, + + docFooter: { + prev: 'Anterior', + next: 'Próximo' + }, + + outline: { + label: 'Nesta página' + }, + + lastUpdated: { + text: 'Atualizado em', + formatOptions: { + dateStyle: 'short', + timeStyle: 'medium' + } + }, + + langMenuLabel: 'Alterar Idioma', + returnToTopLabel: 'Voltar ao Topo', + sidebarMenuLabel: 'Menu Lateral', + darkModeSwitchLabel: 'Tema Escuro', + lightModeSwitchTitle: 'Mudar para Modo Claro', + darkModeSwitchTitle: 'Mudar para Modo Escuro' + } +}) + +function nav(): DefaultTheme.NavItem[] { + return [ + { + text: 'Guia', + link: '/pt/guide/what-is-vitepress', + activeMatch: '/pt/guide/' + }, + { + text: 'Referência', + link: '/pt/reference/site-config', + activeMatch: '/pt/reference/' + }, + { + text: pkg.version, + items: [ + { + text: 'Registro de Mudanças', + link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md' + }, + { + text: 'Contribuindo', + link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md' + } + ] + } + ] +} + +function sidebarGuide(): DefaultTheme.SidebarItem[] { + return [ + { + text: 'Introdução', + collapsed: false, + items: [ + { text: 'O que é VitePress？', link: 'what-is-vitepress' }, + { text: 'Iniciando', link: 'getting-started' }, + { text: 'Roteamento', link: 'routing' }, + { text: 'Implantação', link: 'deploy' } + ] + }, + { + text: 'Escrevendo', + collapsed: false, + items: [ + { text: 'Extensões Markdown', link: 'markdown' }, + { text: 'Manipulando Ativos', link: 'asset-handling' }, + { text: 'Frontmatter', link: 'frontmatter' }, + { text: 'Usando Vue em Markdown', link: 'using-vue' }, + { text: 'Internacionalização', link: 'i18n' } + ] + }, + { + text: 'Personalização', + collapsed: false, + items: [ + { text: 'Usando um tema personalizado', link: 'custom-theme' }, + { text: 'Estendendo o tema padrão', link: 'extending-default-theme' }, + { + text: 'Carregamento de dados no momento da compilação', + link: 'data-loading' + }, + { text: 'Compatibilidade SSR', link: 'ssr-compat' }, + { text: 'Conectando a um CMS', link: 'cms' } + ] + }, + { + text: 'Experimental', + collapsed: false, + items: [ + { text: 'Modo MPA', link: 'mpa-mode' }, + { text: 'Geração de Sitemap', link: 'sitemap-generation' } + ] + }, + { + text: 'Configuração e Referência da API', + base: '/pt/reference/', + link: 'site-config' + } + ] +} + +function sidebarReference(): DefaultTheme.SidebarItem[] { + return [ + { + text: 'Referência', + items: [ + { text: 'Configuração do Site', link: 'site-config' }, + { text: 'Configuração Frontmatter', link: 'frontmatter-config' }, + { text: 'API do tempo de execução', link: 'runtime-api' }, + { text: 'CLI', link: 'cli' }, + { + text: 'Tema padrão', + base: '/pt/reference/default-theme-', + items: [ + { text: 'Visão Geral', link: 'config' }, + { text: 'Navegação', link: 'nav' }, + { text: 'Barra Lateral', link: 'sidebar' }, + { text: 'Página Inicial', link: 'home-page' }, + { text: 'Rodapé', link: 'footer' }, + { text: 'Layout', link: 'layout' }, + { text: 'Distintivo', link: 'badge' }, + { text: 'Página da Equipe', link: 'team-page' }, + { text: 'Links Anterior / Próximo', link: 'prev-next-links' }, + { text: 'Editar Link', link: 'edit-link' }, + { text: 'Selo Temporal de Atualização', link: 'last-updated' }, + { text: 'Busca', link: 'search' }, + { text: 'Carbon Ads', link: 'carbon-ads' } + ] + } + ] + } + ] +} + +export const search: DefaultTheme.AlgoliaSearchOptions['locales'] = { + pt: { + placeholder: 'Pesquisar documentos', + translations: { + button: { + buttonText: 'Pesquisar', + buttonAriaLabel: 'Pesquisar' + }, + modal: { + searchBox: { + resetButtonTitle: 'Limpar pesquisa', + resetButtonAriaLabel: 'Limpar pesquisa', + cancelButtonText: 'Cancelar', + cancelButtonAriaLabel: 'Cancelar' + }, + startScreen: { + recentSearchesTitle: 'Histórico de Pesquisa', + noRecentSearchesText: 'Nenhuma pesquisa recente', + saveRecentSearchButtonTitle: 'Salvar no histórico de pesquisas', + removeRecentSearchButtonTitle: 'Remover do histórico de pesquisas', + favoriteSearchesTitle: 'Favoritos', + removeFavoriteSearchButtonTitle: 'Remover dos favoritos' + }, + errorScreen: { + titleText: 'Não foi possível obter resultados', + helpText: 'Verifique a sua conexão de rede' + }, + footer: { + selectText: 'Selecionar', + navigateText: 'Navegar', + closeText: 'Fechar', + searchByText: 'Pesquisa por' + }, + noResultsScreen: { + noResultsText: 'Não foi possível encontrar resultados', + suggestedQueryText: 'Você pode tentar uma nova consulta', + reportMissingResultsText: + 'Deveriam haver resultados para essa consulta?', + reportMissingResultsLinkText: 'Clique para enviar feedback' + } + } + } + } +} diff --git a/docs/.vitepress/config/shared.ts b/docs/.vitepress/config/shared.ts index b6c610de..d768fd84 100644 --- a/docs/.vitepress/config/shared.ts +++ b/docs/.vitepress/config/shared.ts @@ -1,5 +1,6 @@ import { defineConfig } from 'vitepress' import { search as zhSearch } from './zh' +import { search as ptSearch } from './pt' export const shared = defineConfig({ title: 'VitePress', @@ -54,7 +55,7 @@ export const shared = defineConfig({ appId: '8J64VVRP8K', apiKey: 'a18e2f4cc5665f6602c5631fd868adfd', indexName: 'vitepress', - locales: { ...zhSearch } + locales: { ...zhSearch, ...ptSearch } } }, diff --git a/docs/lunaria.config.json b/docs/lunaria.config.json index 93eb6010..5c395156 100644 --- a/docs/lunaria.config.json +++ b/docs/lunaria.config.json @@ -6,7 +6,7 @@ }, "files": [ { - "location": ".vitepress/config/{en,zh}.ts", + "location": ".vitepress/config/{en,zh,pt}.ts", "pattern": ".vitepress/config/@lang.ts", "type": "universal" }, @@ -24,6 +24,10 @@ { "label": "简体中文", "lang": "zh" + }, + { + "label": "Português", + "lang": "pt" } ], "outDir": ".vitepress/dist/_translations", diff --git a/docs/pt/guide/asset-handling.md b/docs/pt/guide/asset-handling.md new file mode 100644 index 00000000..9bd66f24 --- /dev/null +++ b/docs/pt/guide/asset-handling.md @@ -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 +![Uma imagem](./imagem.png) +``` + +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 +![Uma imagem](/imagem-dentro-de-public.png) +``` + +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 + +``` + +Nesse caso, é recomendável envolver o caminho com o [`auxiliar withBase`](../reference/runtime-api#withbase) fornecido por VitePress: + +```vue + + + +``` diff --git a/docs/pt/guide/cms.md b/docs/pt/guide/cms.md new file mode 100644 index 00000000..c4593b6d --- /dev/null +++ b/docs/pt/guide/cms.md @@ -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 }} + + + ``` + +## 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á! diff --git a/docs/pt/guide/custom-theme.md b/docs/pt/guide/custom-theme.md new file mode 100644 index 00000000..caffd65b --- /dev/null +++ b/docs/pt/guide/custom-theme.md @@ -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 + /** + * 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 // 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 [``](../reference/runtime-api#content): + +```vue + + +``` + +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} + + + +``` + +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} + + + +``` + +Você pode, é claro, dividir o layout em mais componentes: + +```vue{3-5,12-15} + + + +``` + +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({ + extends: baseConfig, + themeConfig: { + // O tipo é `ThemeConfig` + } +}) +``` diff --git a/docs/pt/guide/data-loading.md b/docs/pt/guide/data-loading.md new file mode 100644 index 00000000..6efb7ddf --- /dev/null +++ b/docs/pt/guide/data-loading.md @@ -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 + + +
{{ data }}
+``` + +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 + + // 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 + + + +``` + +### 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 { + /** + * 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 +} +``` + +## 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 { + // ... + } +}) +``` + +## 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 +``` diff --git a/docs/pt/guide/deploy.md b/docs/pt/guide/deploy.md new file mode 100644 index 00000000..da583034 --- /dev/null +++ b/docs/pt/guide/deploy.md @@ -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@v2 # 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://.github.io/[repository]/` ou `https:///` 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 `'//'` se você deseja implantar em `https://.gitlab.io//`. + +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": "" + } + } + ``` + +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/). diff --git a/docs/pt/guide/extending-default-theme.md b/docs/pt/guide/extending-default-theme.md new file mode 100644 index 00000000..db68e954 --- /dev/null +++ b/docs/pt/guide/extending-default-theme.md @@ -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 `` 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 + + + + +``` + +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 + + + + + + + +``` + +Resultado (**atenção!**: cores piscantes, movimentos súbitos, luzes brilhantes): + +
+Demo + +![Demo de Transição de Alternância de Aparência](/appearance-toggle-transition.webp) + +
+ +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. \ No newline at end of file diff --git a/docs/pt/guide/frontmatter.md b/docs/pt/guide/frontmatter.md new file mode 100644 index 00000000..0ab4ac51 --- /dev/null +++ b/docs/pt/guide/frontmatter.md @@ -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 ` + + +``` + +## 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 , ou . Você precisará configurar seu plugin PostCSS para usar `:where([dir="ltr"])` e `:where([dir="rtl"])` como prefixos para evitar problemas de especificidade CSS. \ No newline at end of file diff --git a/docs/pt/guide/markdown.md b/docs/pt/guide/markdown.md new file mode 100644 index 00000000..5fba7333 --- /dev/null +++ b/docs/pt/guide/markdown.md @@ -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](/) +[foo](/foo/) +[foo heading](./#heading) +[bar - three](../bar/three) +[bar - three](../bar/three.md) +[bar - four](../bar/four.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
+::: +``` + +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 +
    +
  • + {{ todo.text }} +
    • +
+``` +```` + +**Saída** + +```js +export default { + name: 'MyComponent' + // ... +} +``` + +```html +
    +
  • + {{ todo.text }} +
    • +
+``` + +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:]`. + +**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#} + + + +<<< @/snippets/snippet.cs{1,2,4-6 c#} + + + +<<< @/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 + + + +<<< @/snippets/snippet.js + + + +<<< @/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 + + +``` + +**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 + + +``` + +**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). \ No newline at end of file diff --git a/docs/pt/guide/mpa-mode.md b/docs/pt/guide/mpa-mode.md new file mode 100644 index 00000000..28aabae1 --- /dev/null +++ b/docs/pt/guide/mpa-mode.md @@ -0,0 +1,23 @@ +# Modo MPA {#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 ` + +# Olá +``` + +` +``` + +### 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 + +``` diff --git a/docs/pt/guide/sitemap-generation.md b/docs/pt/guide/sitemap-generation.md new file mode 100644 index 00000000..c6f8d9b8 --- /dev/null +++ b/docs/pt/guide/sitemap-generation.md @@ -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 `` 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 + } + } +}) +``` diff --git a/docs/pt/guide/ssr-compat.md b/docs/pt/guide/ssr-compat.md new file mode 100644 index 00000000..deec9a7b --- /dev/null +++ b/docs/pt/guide/ssr-compat.md @@ -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. + +## `` + +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 ``: + +```md + + + +``` + +## 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 + +``` + +### 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 + + + +``` + +Você também pode passar propriedades/filhos/_slots_ para o componente alvo: + +```vue + + + +``` + +O componente alvo só será importado no gatilho `mounted` do componente que o envolve. \ No newline at end of file diff --git a/docs/pt/guide/using-vue.md b/docs/pt/guide/using-vue.md new file mode 100644 index 00000000..6c2002ac --- /dev/null +++ b/docs/pt/guide/using-vue.md @@ -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 ` + +## Conteúdo Markdown + +A contagem é: {{ count }} + + + + +``` + +::: warning Evite ` +``` + +## 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 `` 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). + + + +::: details +<<< @/components/ModalDemo.vue +::: + +```md + + +
+ // ... +
+ + +``` + + + + diff --git a/docs/pt/guide/what-is-vitepress.md b/docs/pt/guide/what-is-vitepress.md new file mode 100644 index 00000000..835f5bd3 --- /dev/null +++ b/docs/pt/guide/what-is-vitepress.md @@ -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. + +
+ +Quer apenas experimentar? Pule para o [Início Rápido](./getting-started). + +
+ +## 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. \ No newline at end of file diff --git a/docs/pt/index.md b/docs/pt/index.md new file mode 100644 index 00000000..41c72d54 --- /dev/null +++ b/docs/pt/index.md @@ -0,0 +1,57 @@ +--- +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: Simples, poderoso e rápido. Conheça o moderno framework SSG que você sempre quis. + actions: + - theme: brand + text: Iniciar + link: /pt/guide/getting-started + - theme: alt + text: Ver no 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: + title: Aproveite a experiência Vite + details: Início de servidor instantâneo, atualizações ultrarrápidas, e plugins do ecossistema Vite. + - icon: + 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. +--- + + diff --git a/docs/pt/reference/cli.md b/docs/pt/reference/cli.md new file mode 100644 index 00000000..6d7f0006 --- /dev/null +++ b/docs/pt/reference/cli.md @@ -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 ` | Especifica porta (`number`) | +| `--base ` | 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 ` | Caminho base público (padrão: `/`) (`string`) | +| `--target ` | Transpila o alvo (padrão: `"modules"`) (`string`) | +| `--outDir ` | Diretório de saída relativo ao **cwd** (padrão: `/.vitepress/dist`) (`string`) | +| `--minify [minifier]` | Habilita/desabilita minificação, ou especifica um minificador para usar (padrão: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`) | +| `--assetsInlineLimit ` | 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 ` | Caminho base público (padrão: `/`) (`string`) | +| `--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 +``` diff --git a/docs/pt/reference/default-theme-badge.md b/docs/pt/reference/default-theme-badge.md new file mode 100644 index 00000000..a96955a0 --- /dev/null +++ b/docs/pt/reference/default-theme-badge.md @@ -0,0 +1,69 @@ +# Emblema {#badge} + +O emblema permite adicionar status aos seus cabeçalhos. Por exemplo, pode ser útil especificar o tipo da seção ou a versão suportada. + +## Uso {#usage} + +Você pode usar o componente `Badge` que está disponível globalmente. + +```html +### Title +### Title +### Title +### Title +``` + +O código acima é apresentado como: + +### Title +### Title +### Title +### Title + +## Filiação Personalizada {#custom-children} + +`` aceita `children` (filhos), que serão exibidos no emblema. + +```html +### Title custom element +``` + +### Title custom element + +## Personalize o Tipo de Cor {#customize-type-color} + +Você pode personalizar o estilo dos emblemas sobrepondo variáveis ​​CSS. Os seguintes são os valores padrão: + +```css +:root { + --vp-badge-info-border: transparent; + --vp-badge-info-text: var(--vp-c-text-2); + --vp-badge-info-bg: var(--vp-c-default-soft); + + --vp-badge-tip-border: transparent; + --vp-badge-tip-text: var(--vp-c-brand-1); + --vp-badge-tip-bg: var(--vp-c-brand-soft); + + --vp-badge-warning-border: transparent; + --vp-badge-warning-text: var(--vp-c-warning-1); + --vp-badge-warning-bg: var(--vp-c-warning-soft); + + --vp-badge-danger-border: transparent; + --vp-badge-danger-text: var(--vp-c-danger-1); + --vp-badge-danger-bg: var(--vp-c-danger-soft); +} +``` + +## `` + +O componente `` aceita as seguintes propriedades: + +```ts +interface Props { + // Quando `` é passado, esse valor é ignorado. + text?: string + + // O padrão é `tip`. + type?: 'info' | 'tip' | 'warning' | 'danger' +} +``` diff --git a/docs/pt/reference/default-theme-carbon-ads.md b/docs/pt/reference/default-theme-carbon-ads.md new file mode 100644 index 00000000..1c4d4e60 --- /dev/null +++ b/docs/pt/reference/default-theme-carbon-ads.md @@ -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/). diff --git a/docs/pt/reference/default-theme-config.md b/docs/pt/reference/default-theme-config.md new file mode 100644 index 00000000..361475fc --- /dev/null +++ b/docs/pt/reference/default-theme-config.md @@ -0,0 +1,451 @@ +# 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 +} + +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 `

` a `

` 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: 'Dribbble' + }, + 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> +} +``` + +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. diff --git a/docs/pt/reference/default-theme-edit-link.md b/docs/pt/reference/default-theme-edit-link.md new file mode 100644 index 00000000..6b1e8793 --- /dev/null +++ b/docs/pt/reference/default-theme-edit-link.md @@ -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 +--- +``` diff --git a/docs/pt/reference/default-theme-footer.md b/docs/pt/reference/default-theme-footer.md new file mode 100644 index 00000000..98b02b2c --- /dev/null +++ b/docs/pt/reference/default-theme-footer.md @@ -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 Licença MIT.', + copyright: 'Direitos Reservados © 2019-present Evan You' + } + } +} +``` + +::: warning +Apenas elementos _inline_ serão usados em `message` e `copyright` conforme eles são apresentados dentro do elemento `

`. 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 +--- +``` \ No newline at end of file diff --git a/docs/pt/reference/default-theme-home-page.md b/docs/pt/reference/default-theme-home-page.md new file mode 100644 index 00000000..460c55bf --- /dev/null +++ b/docs/pt/reference/default-theme-home-page.md @@ -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 + } +``` diff --git a/docs/pt/reference/default-theme-last-updated.md b/docs/pt/reference/default-theme-last-updated.md new file mode 100644 index 00000000..5bc782e1 --- /dev/null +++ b/docs/pt/reference/default-theme-last-updated.md @@ -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. diff --git a/docs/pt/reference/default-theme-layout.md b/docs/pt/reference/default-theme-layout.md new file mode 100644 index 00000000..0e4d0162 --- /dev/null +++ b/docs/pt/reference/default-theme-layout.md @@ -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) + } +} +``` diff --git a/docs/pt/reference/default-theme-nav.md b/docs/pt/reference/default-theme-nav.md new file mode 100644 index 00000000..5f0d2399 --- /dev/null +++ b/docs/pt/reference/default-theme-nav.md @@ -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). diff --git a/docs/pt/reference/default-theme-prev-next-links.md b/docs/pt/reference/default-theme-prev-next-links.md new file mode 100644 index 00000000..c9472a24 --- /dev/null +++ b/docs/pt/reference/default-theme-prev-next-links.md @@ -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. diff --git a/docs/pt/reference/default-theme-search.md b/docs/pt/reference/default-theme-search.md new file mode 100644 index 00000000..35b0d812 --- /dev/null +++ b/docs/pt/reference/default-theme-search.md @@ -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: + +![captura de tela do modal de pesquisa](/search.png) + +Alternativamente, você pode usar [Algolia DocSearch](#algolia-search) ou alguns plugins da comunidade como ou . + +### 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} + */ + 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: '', + highlightPostTag: '', + minWordSizefor1Typo: 3, + minWordSizefor2Typos: 7, + allowTyposOnNumericTokens: false, + minProximity: 1, + ignorePlurals: true, + advancedSyntax: true, + attributeCriteriaComputedByMinProximity: true, + removeWordsIfNoResults: 'allOptional' + } + } +}) +``` + + diff --git a/docs/pt/reference/default-theme-sidebar.md b/docs/pt/reference/default-theme-sidebar.md new file mode 100644 index 00000000..62c3b3b1 --- /dev/null +++ b/docs/pt/reference/default-theme-sidebar.md @@ -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` + +Retorna dados relacionados à barra lateral. O objeto retornado tem o seguinte tipo: + +```ts +export interface DocSidebar { + isOpen: Ref + sidebar: ComputedRef + sidebarGroups: ComputedRef + hasSidebar: ComputedRef + hasAside: ComputedRef + leftAside: ComputedRef + isSidebarEnabled: ComputedRef + open: () => void + close: () => void + toggle: () => void +} +``` + +**Exemplo:** + +```vue + + + +``` diff --git a/docs/pt/reference/default-theme-team-page.md b/docs/pt/reference/default-theme-team-page.md new file mode 100644 index 00000000..9021b959 --- /dev/null +++ b/docs/pt/reference/default-theme-team-page.md @@ -0,0 +1,258 @@ + + +# 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 `` exposto em `vitepress/theme` para exibir uma lista de membros da equipe em qualquer página. + +```html + + +# Nosso time + +Diga olá à nossa equipe incrível. + + +``` + +O código acima exibirá um membro da equipe em um elemento tipo cartão. Ele deve exibir algo semelhante ao abaixo. + + + +O componente `` 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). + +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 +--- + + + + + + + + + +``` + +Ao criar uma página de equipe completa, lembre-se de agrupar todos os componentes com o componente ``. Este componente garantirá que todos os componentes aninhados relacionados à equipe obtenham a estrutura de layout adequada, como espaçamentos. + +O componente `` adiciona a seção de título da página. O título é `

`. Use os _slots_ `#title` e `#lead`para documentar sobre sua equipe. + +`` 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 `` ao arquivo `team.md` que criamos anteriormente. + +```html +--- +layout: page +--- + + + + + + + + + + + + + + +``` + +O componente `` 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 `` dentro do _slot_ `#members`. + +## `` + +O componente `` exibe uma determinada lista de membros. + +```html + +``` + +```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 +} +``` + +## `` + +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. + +## `` + +Adiciona a seção "título" da página. Melhor usar logo no início sob ``. Aceita os _slots_ `#title` e `#lead`. + +```html + + + + + + +``` + +## `` + +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 ``. + +```html + + ... + + + + + + +``` diff --git a/docs/pt/reference/frontmatter-config.md b/docs/pt/reference/frontmatter-config.md new file mode 100644 index 00000000..41ccad66 --- /dev/null +++ b/docs/pt/reference/frontmatter-config.md @@ -0,0 +1,221 @@ +--- +outline: deep +--- + +# Configuração Frontmatter {#frontmatter-config} + +Frontmatter permite a configuração baseada em páginas. Em cada arquivo markdown, você pode usar a configuração frontmatter para sobrepor opções de configuração a nível de site ou de tema. Além disso, existem opções de configuração que só podem ser definidas em frontmatter. + +Exemplo de uso: + +```md +--- +title: Documentação com VitePress +editLink: true +--- +``` + +Você pode acessar os dados do frontmatter através da variável global `$frontmatter` em expressões Vue: + +```md +{{ $frontmatter.title }} +``` + +## title + +- Tipo: `string` + +Título para a página. É o mesmo que [config.title](./site-config#title), e sobrepõe a configuração a nível de site. + +```yaml +--- +title: VitePress +--- +``` + +## titleTemplate + +- Tipo: `string | boolean` + +O sufixo para o título. É o mesmo que [config.titleTemplate](./site-config#titletemplate), e sobrepõe a configuração a nível de site. + +```yaml +--- +title: VitePress +titleTemplate: Gerador de site estático com Vite & Vue +--- +``` + +## description + +- Tipo: `string` + +Descrição para a página. É o mesmo que [config.description](./site-config#description), e sobrepõe a configuração a nível de site. + +```yaml +--- +description: VitePress +--- +``` + +## head + +- Tipo: `HeadConfig[]` + +Especifica tags head adicionais a serem injetadas na página atual. Elas serão acrescentadas após as tags head injetadas pela configuração a nível de site. + +```yaml +--- +head: + - - meta + - name: description + content: hello + - - meta + - name: keywords + content: super duper SEO +--- +``` + +```ts +type HeadConfig = + | [string, Record] + | [string, Record, string] +``` + +## Somente no Tema Padrão {#default-theme-only} + +As seguintes opções frontmatter são aplicáveis apenas ao usar o tema padrão. + +### layout + +- Tipo: `doc | home | page` +- Padrão: `doc` + +Determina o layout da página. + +- `doc` - Aplica estilos de documentação padrão ao conteúdo markdown. +- `home` - Layout especial para a "Página Inicial". Você pode adicionar opções extras como `hero` e `features` para criar rapidamente uma bela página inicial. +- `page` - Comporta-se de maneira semelhante a `doc`, mas não aplica estilos ao conteúdo. Útil quando você deseja criar uma página totalmente personalizada. + +```yaml +--- +layout: doc +--- +``` + +### hero + +Define o conteúdo da seção _hero_ na página inicial quando `layout` está definido como `home`. Mais detalhes em [Tema Padrão: Página Inicial](./default-theme-home-page). + +### features + +Define os itens a serem exibidos na seção de funcionalidades quando `layout` está definido como `home`. Mais detalhes em [Tema Padrão: Página Inicial](./default-theme-home-page). + +### navbar + +- Tipo: `boolean` +- Padrão: `true` + +Se deve exibir a [barra de navegação](./default-theme-nav). + +```yaml +--- +navbar: false +--- +``` + +### sidebar + +- Tipo: `boolean` +- Padrão: `true` + +Se deve exibir a [barra lateral](./default-theme-sidebar). + +```yaml +--- +sidebar: false +--- +``` + +### aside + +- Tipo: `boolean | 'left'` +- Padrão: `true` + +Define a localização do componente aside no layout `doc`. + +Configurar este valor como `false` impede a apresentação do elemento aside.\ +Configurar este valor como `true` apresenta o aside à direita.\ +Configurar este valor como `'left'` apresenta o aside à esquerda. + +```yaml +--- +aside: false +--- +``` + +### outline + +- Tipo: `number | [number, number] | 'deep' | false` +- Padrão: `2` + +Os níveis do cabeçalho no _outline_ a serem exibidos para a página. É o mesmo que [config.themeConfig.outline.level](./default-theme-config#outline), e sobrepõe o valor definido na configuração no nível do site. + +### lastUpdated + +- Tipo: `boolean | Date` +- Padrão: `true` + +Se deve mostrar o texto de [última atualização](./default-theme-last-updated) no rodapé da página atual. Se uma data e hora específica forem especificadas, ela será exibida em vez do último horário de modificação do git. + +```yaml +--- +lastUpdated: false +--- +``` + +### editLink + +- Tipo: `boolean` +- Padrão: `true` + +Se deve exibir o [link de edição](./default-theme-edit-link) no rodapé da página atual. + +```yaml +--- +editLink: false +--- +``` + +### footer + +- Tipo: `boolean` +- Padrão: `true` + +Se deve exibir o [rodapé](./default-theme-footer). + +```yaml +--- +footer: false +--- +``` + +### pageClass + +- Tipo: `string` + +Adiciona um nome de classe extra a uma página específica. + +```yaml +--- +pageClass: custom-page-class +--- +``` + +Em seguida, você pode personalizar os estilos desta página específica no arquivo `.vitepress/theme/custom.css`: + +```css +.custom-page-class { +  /* estilos específicos da página */ +} +``` diff --git a/docs/pt/reference/runtime-api.md b/docs/pt/reference/runtime-api.md new file mode 100644 index 00000000..a04458a1 --- /dev/null +++ b/docs/pt/reference/runtime-api.md @@ -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 ` + + +``` + +## `useRoute` + +Retorna o objeto de rota atual com o seguinte tipo: + +```ts +interface Route { + path: string + data: PageData + component: Component | null +} +``` + +## `useRouter` + +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 + /** + * Chamado antes da mudança de rota. Retorne `false` para cancelar a navegação. + */ + onBeforeRouteChange?: (to: string) => Awaitable + /** + * 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 + /** + * Chamado após a mudança de rota. + */ + onAfterRouteChanged?: (to: string) => Awaitable +} +``` + +## `withBase` + +- **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). + +## `` + +O componente `` exibe o conteúdo markdown renderizado. Útil [ao criar seu próprio tema](../guide/custom-theme). + +```vue + +``` + +## `` + +O componente `` 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 + + + +``` + +- Relacionado: [Compatibilidade SSR](../guide/ssr-compat) + +## `$frontmatter` + +Acesse diretamente os dados [frontmatter](../guide/frontmatter) da página atual em expressões Vue. + +```md +--- +title: Olá +--- + +# {{ $frontmatter.title }} +``` + +## `$params` + +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 }} +``` diff --git a/docs/pt/reference/site-config.md b/docs/pt/reference/site-config.md new file mode 100644 index 00000000..013ee7d9 --- /dev/null +++ b/docs/pt/reference/site-config.md @@ -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 `/.vitepress/config.[ext]`, onde `` é 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: { + // 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 `

`, 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 `

` 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 `` 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 `` 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, Record, 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: + +*/ +``` + +#### 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: + + + +*/ +``` + +#### 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: + +*/ +``` + +#### 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: + + +*/ +``` + +### lang + +- Tipo: `string` +- Padrão: `en-US` + +O atributo de idioma para o site. Isso será mostrado como uma tag `` 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` + +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 + +- 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 ``). + +- 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` +`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` +- `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 + [key: string]: any + } + ``` + +## transformHead +- Tipo: `(context: TransformContext) => Awaitable` + +`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 `` {#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` +`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 | { [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 +} +``` From 59183e9cef112a004c8a8e2b365478af657858b0 Mon Sep 17 00:00:00 2001 From: Timothy Lau Date: Thu, 7 Mar 2024 15:34:59 +0800 Subject: [PATCH 12/13] fix(build): resolve patter relative to srcDir instead of root in createContentLoader (#3638) Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> --- src/node/contentLoader.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/node/contentLoader.ts b/src/node/contentLoader.ts index c213f794..dc8651ac 100644 --- a/src/node/contentLoader.ts +++ b/src/node/contentLoader.ts @@ -75,7 +75,7 @@ export interface ContentData { */ export function createContentLoader( /** - * files to glob / watch - relative to + * files to glob / watch - relative to srcDir */ pattern: string | string[], { @@ -98,7 +98,7 @@ export function createContentLoader( } if (typeof pattern === 'string') pattern = [pattern] - pattern = pattern.map((p) => normalizePath(path.join(config.root, p))) + pattern = pattern.map((p) => normalizePath(path.join(config.srcDir, p))) let md: MarkdownRenderer From 5f6297cb3df98926154235f31570e75820d4ea16 Mon Sep 17 00:00:00 2001 From: Rick Dubiel Date: Thu, 7 Mar 2024 01:40:24 -0600 Subject: [PATCH 13/13] feat(theme): allow selectively disabling external link icon on navbar items (#3607) Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> --- docs/pt/reference/default-theme-config.md | 1 + docs/reference/default-theme-config.md | 1 + docs/zh/reference/default-theme-config.md | 1 + src/client/theme-default/components/VPNavBarMenuLink.vue | 1 + types/default-theme.d.ts | 1 + 5 files changed, 5 insertions(+) diff --git a/docs/pt/reference/default-theme-config.md b/docs/pt/reference/default-theme-config.md index 361475fc..417cbc30 100644 --- a/docs/pt/reference/default-theme-config.md +++ b/docs/pt/reference/default-theme-config.md @@ -93,6 +93,7 @@ interface NavItemWithLink { activeMatch?: string target?: string rel?: string + noIcon?: boolean } interface NavItemChildren { diff --git a/docs/reference/default-theme-config.md b/docs/reference/default-theme-config.md index f41fb7ad..b1a4a29a 100644 --- a/docs/reference/default-theme-config.md +++ b/docs/reference/default-theme-config.md @@ -93,6 +93,7 @@ interface NavItemWithLink { activeMatch?: string target?: string rel?: string + noIcon?: boolean } interface NavItemChildren { diff --git a/docs/zh/reference/default-theme-config.md b/docs/zh/reference/default-theme-config.md index bf8a3e69..a7028f16 100644 --- a/docs/zh/reference/default-theme-config.md +++ b/docs/zh/reference/default-theme-config.md @@ -93,6 +93,7 @@ interface NavItemWithLink { activeMatch?: string target?: string rel?: string + noIcon?: boolean } interface NavItemChildren { diff --git a/src/client/theme-default/components/VPNavBarMenuLink.vue b/src/client/theme-default/components/VPNavBarMenuLink.vue index a77636d4..e5c166a0 100644 --- a/src/client/theme-default/components/VPNavBarMenuLink.vue +++ b/src/client/theme-default/components/VPNavBarMenuLink.vue @@ -22,6 +22,7 @@ const { page } = useData() ) }" :href="item.link" + :noIcon="item.noIcon" :target="item.target" :rel="item.rel" tabindex="0" diff --git a/types/default-theme.d.ts b/types/default-theme.d.ts index d6636643..9a9df23f 100644 --- a/types/default-theme.d.ts +++ b/types/default-theme.d.ts @@ -176,6 +176,7 @@ export namespace DefaultTheme { activeMatch?: string rel?: string target?: string + noIcon?: boolean } export interface NavItemChildren {