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

description
Comienza a trabajar con VitePress. Aprende cómo instalar, crear la estructura y comenzar a desarrollar tu sitio de documentación.

Iniciando

Experimente Online

Puede experimentar VitePress directamente en su navegador en StackBlitz.

Instalación

Prerrequisitos

• Node.js versión 22 o superior.
• Terminal para acceder 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:

::: code-group

$ npm add -D vitepress@next

$ pnpm add -D vitepress@next

$ yarn add -D vitepress@next vue

$ bun add -D vitepress@next

$ deno add -D vitepress@next

:::

::: tip NOTA

VitePress es un paquete apenas para ESM. No use require() para importarlo, y asegúrese 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 CJS asíncronos, puede usar await import('vitepress').

:::

Asistente de Instalación

VitePress incluye un asistente de instalación por línea de comandos que le ayudará a crear un proyecto básico. Después de la instalación, inicie el asistente ejecutando:

::: code-group

$ npx vitepress init

$ pnpm vitepress init

$ yarn vitepress init

$ bun vitepress init

:::

Será saludado con algunas preguntas simples:

<<< @/snippets/init.ansi

::: tip Vue como Dependencia Correspondiente Si tiene la intención de realizar una personalización que usa componentes Vue o APIs, debe instalar explícitamente vue como una dependencia correspondiente. :::

Estructura de Archivos

Si está construyendo un sitio web independiente con VitePress, puede generar la estructura básica del sitio en su directorio actual (./). Sin embargo, si está instalando VitePress en un proyecto existente junto con otro código fuente, se recomendado construir el sitio en un directorio anidado (por ejemplo, ./docs) para que esté separado del resto del 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.json

El directorio docs es considerado la raíz 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 compilación, 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 compilación 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 varios aspectos de su sitio VitePress, con las opciones más básicas siendo el titulo y la descripción del sitio:

export default {
  // opciones a nivel del sitio
  title: 'VitePress',
  description: 'Solo una juego.',

  themeConfig: {
    // opciones a nivel del tema
  }
}

También puedes configurar el comportamiento del tema mediante la opción themeConfig. Consulta la Referencia de Configuración para obtener información detallada 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 la misma ruta. Por ejemplo, index.md se compilará en index.html y se podrá acceder a él desde la ruta raíz / del sitio VitePress resultante.

VitePress también proporciona la habilidad de generar URLs limpias, reescribir rutas y generar páginas dinámicamente. Estos temas se tratarán 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. Ejecútelo con el siguiente comando:

::: code-group

$ npm run docs:dev

$ pnpm run docs:dev

$ yarn docs:dev

$ bun run docs:dev

:::

En vez de scripts npm, también puede invocar VitePress directamente con:

::: code-group

$ npx vitepress dev docs

$ pnpm vitepress dev docs

$ yarn vitepress dev docs

$ bun vitepress dev docs

:::

Más usos de la linea de comandos están documentados en la Referencia CLI.

El servidor de desarrollo debería estar corriendo en http://localhost:5173. ¡Visita la URL en tu navegador para ver tu 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, asegúrese de leer la Guía de Despliegue.