Iniciando
Experimente Online
Puede experimentar VitePress directamente en su navegador en StackBlitz.
Instalación
Prerrequisitos
- Node.js versión 18 o superior.
- Terminal para acessar VitePress a través de su interfaz de linea de comando (CLI).
- Editor de texto con soporte a sintaxis Markdown.
- VSCode es recomendado, junto con la extensión oficial Vue.
VitePress puede ser usado solo, o ser instalado en un proyecto ya existente. En ambos casos, puede instalarlo con:
$ npm add -D vitepress$ pnpm add -D vitepress$ yarn add -D vitepress$ bun add -D vitepress::: detalles recibiendo avisos sobre dependencias ausentes? Si usa PNPM, percibirá un aviso de ausencia de @docsearch/js. Esto no evita que VitePress funcione. Si desea eliminar este aviso, adicione lo siguiente en su package.json:
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": [
"@algolia/client-search",
"search-insights"
]
}
}:::
NOTA
VitePress es un paquete apenas para ESM. No use require() para importarlo, y asegurese de que el package.json más cercano contiene "type": "module", o cambie la extensión de archivo de sus archivos relevantes como .vitepress/config.js a .mjs/.mts. Consulte la Guía de resolución de problemas Vite para más detalles. Además de eso, dentro de contextos de JavaScript asíncronos, puede usar await import('vitepress').
Asistente de Instalación
VitePress tiene embutido un asistente de instalación por linea de comando que ayudará a construir un proyecto básico. Después de la instalación, inicie el asistente ejecutando:
$ npx vitepress init$ pnpm vitepress init$ yarn vitepress init$ bun vitepress initSerá saludado con algunas preguntas simples:
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◆ Theme:
│ ● Default Theme (Out of the box, good-looking docs)
│ ○ Default Theme + Customization
│ ○ Custom Theme
└Vue como Dependencia Correspondiente
Si tiene la intención de realizar una personalización que usa componentes Vue o APIs, debe instalar explicitamente vue como una dependencia correspondiente.
Estrutura de Archivos
Se está construyendo un sitio VitePress individual, puede desarrollar su sitio en el directorio actual (./). Sin embargo, si está instalando VitePress en un proyecto existente junto con otro código fuente, es recomendado construir el sitio en un directorio anidado (e.g. ./docs) para que esté separado del resto de su proyecto.
Asumiendo la opción de desarrollar el proyecto VitePress en ./docs, la estructura de archivos generada debe parecerse a la siguiente:
.
├─ docs
│ ├─ .vitepress
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.jsonEl directorio docs es considerado la raiz del proyecto de su sitio VitePress. El directorio .vitepress es un lugar reservado para archivos de configuración VitePress, caché del servidor de desarrollo, resultado del build, y código de personalización de tema opcional.
TIP
Por defecto, VitePress almacena el caché del servidor de desarrollo en .vitepress/cache, y el resultado del build de producción en .vitepress/dist. Se usa Git, debe adicionarlos a su archivo .gitignore. Estas ubicaciones también pueden ser configuradas.
El archivo de configuración
El archivo de configuración (.vitepress/config.js) permite que personalice vários aspectos de su sitio VitePress, con las opciones más básicas siendo el titulo y la descripción del sitio:
// .vitepress/config.js
export default {
// opciones a nivel del sitio
title: 'VitePress',
description: 'Solo una broma.',
themeConfig: {
// opciones a nivel del tema
}
}Puede también configurar el comportamiento del tema a través de la opción themeConfig. Consulte la Referencia de Configuración para detaller completos sobre todas las opciones de configuración.
Archivos fuente
Archivos Markdown fuera del directorio .vitepress son considerados archivos fuente.
VitePress usa enrutamiento basado en archivos: cada archivo .md es compilado en un archivo .html correspondiente con el mismo path. Por ejemplo, index.md será compilado en index.html, y puede ser visitado en el path raiz / del sitio VitePress resultante.
VitePress también proporciona la habilidad de generar URLs limpias, retambém fornece a habilidade de gerar URLs limpas, reescribir paths, y generare páginas dinámicamente. Estos serán tratados en la Guía de Enrutamiento.
Instalado y Funcionando
La herramienta debe tener también inyectado los siguientes scripts npm en su package.json si permitió esto durante el proceso de instalación:
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}El script docs:dev iniciará un servidor de desarrollo local con actualizaciones instantáneas. Ejecutelo con el siguiente comando:
$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev$ bun run docs:devEn vez de scripts npm, también puede invocar VitePress directamente con:
$ npx vitepress dev docs$ pnpm vitepress dev docs$ yarn vitepress dev docs$ bun vitepress dev docsMás usos de la linea de comandos están documaentados en la Referencia CLI.
El servidor de desarrollo debe estar corriendo en http://localhost:5173. Visite la URL en su navegador para ver su nuevo sitio en acción!
Qué viene después?
Para entender mejor cómo archivos Markdown son mapeados en HTML, consulte la Guía de Enrutamiento.
Para descubrir más sobre lo que puede hacer en una página, cómo escribir contenido markdown o usar un componente Vue, consulte la sección "Escribiendo" de la guía. Un optimo lugar para comenzar sería aprendiendo más sobre Extensiones Markdown.
Para explorar las funcionalidades proporcionadas por el tema por defecto de la documentación, consulte la Referencia de Configuración del Tema por Defecto.
Se quiere profundizar la personalización de la apariencia de su sitio, explore tanto Extienda el Tema por Defecto como Construya un Tema Personalizado.
Una vez que su documentación tome forma, asegurese de leer la Guia de Despliegue.