Saltar al contenido principal

Instalación

¡Bienvenido! Esta guía te explica paso a paso cómo configurar docStatic por primera vez.

Si nunca has trabajado con GitHub o con «docs-as-code», no te preocupes: te explicaremos qué necesitas, por qué y dónde encontrar más información.

Requisitos previos​

Puedes ejecutar docStatic localmente (en tu ordenador) o alojarlo en la nube.

Para una configuración en la nube más sencilla, crea cuentas gratuitas en estos servicios:

  • GitHub: almacena tu contenido y realiza un seguimiento de los cambios
  • TinaCMS: permite la edición desde el navegador
  • LanguageTool: ofrece una revisión opcional de gramática y estilo

Si, por el contrario, tienes pensado ejecutar docStatic localmente (en tu ordenador), consulta los requisitos para el desarrollo local.

Requisitos para el desarrollo local​

Esta sección solo es aplicable si tienes pensado trabajar localmente.

Necesitarás un entorno de desarrollo integrado (IDE) o un editor de texto. Dos opciones de código abierto son:

También tendrás que instalar Node.js para sus herramientas de compilación y Yarn para la gestión de paquetes.

Instalar Node.js​

Debes instalar Node.js versión 22.0 o superior.

Comprueba si Node.js ya está instalado. Abre un terminal (Símbolo del sistema o la aplicación Terminal) y ejecuta:

node -v

Si ves un número de versión que empieza por v22 o superior, ya estás listo.

Si Node.js no está instalado o tienes una versión anterior:

  1. Ve a la página oficial de descargas de Node.js.
  2. Elige la versión LTS (soporte a largo plazo) para tu sistema operativo. El instalador incluye npm, el gestor de paquetes de Node, que necesitarás en pasos posteriores. Durante la instalación:* Mantén seleccionadas las opciones predeterminadas (estas incluyen las dependencias necesarias) * Cuando finalice la instalación, cierra y vuelve a abrir la terminal.
  3. (Opcional) Si trabajas en diferentes proyectos que requieren distintas versiones de Node, instala nvm (Node Version Manager). Con nvm, puedes cambiar entre versiones de Node sin alterar tu configuración.

Instalar Yarn​

docStatic utiliza Yarn para la gestión de paquetes.

Comprueba si Yarn ya está instalado. Abre tu terminal o la línea de comandos y escribe:

yarn -v

Si ves un número de versión, Yarn ya está instalado.

Si aparece un mensaje del tipo «comando no encontrado» o un error similar, abre un terminal (Símbolo del sistema o la aplicación Terminal) y ejecuta:

npm install -g yarn
Nota

En macOS o Linux, es posible que tengas que anteponer «sudo» al comando para conceder permisos:

sudo npm install -g yarn
Nota

En Windows no se utiliza «sudo». Solo tienes que abrir el terminal como administrador y ejecutar el comando.

Obtener docStatic​

Hay dos formas de obtener tu propia copia de docStatic:

  1. Crea un nuevo sitio con `create-docstatic` (recomendado). Con un solo comando obtendrás un sitio nuevo e independiente con su propio nombre e historial de git.
  2. Haz un fork y clona el repositorio. Elige esta opción si quieres contribuir al propio docStatic o si prefieres gestionar las actualizaciones mediante fusiones con Git.

Crear un nuevo sitio​

Abre un terminal (Símbolo del sistema o la aplicación Terminal) y ejecuta uno de los siguientes comandos, según tu gestor de paquetes preferido. Sustituye my-docs por el nombre de tu proyecto.

npx create-docstatic@latest my-docs

El comando descarga la última plantilla de docStatic, crea la carpeta my-docs, la convierte en un repositorio de Git e instala las dependencias del proyecto. Cuando termine, inicia el servidor de desarrollo local:

cd my-docs
yarn dev
Consejo

Ejecuta npx create-docstatic@latest --help para ver las opciones disponibles, como --no-install, que permite omitir la instalación de dependencias.

Si has creado tu sitio de esta forma, puedes pasar directamente a la sección Estructura del proyecto.

Mantén tu sitio actualizado​

Cuando se publique una nueva versión de docStatic, ejecuta este comando desde la carpeta raíz de tu sitio:

npx create-docstatic@latest --update

El comando actualiza los archivos propios de docStatic (componentes de React, scripts de compilación, configuración de Docusaurus y Tina, versiones de las dependencias) y deja intacto tu contenido —docs/, blog/, config/, reuse/ y static/—. Se conservan el nombre de tu sitio y cualquier script personalizado de package.json que hayas añadido.

La actualización requiere un árbol de trabajo de Git limpio, así que primero confirma tu trabajo. A continuación, revisa el resultado con git diff, vuelve a aplicar cualquier personalización que hayas realizado en los archivos actualizados y confirma los cambios.

Consejo

Añade --dry-run para ver qué cambios se producirían sin escribir nada.

Hacer un fork del repositorio docStatic​

Hacer un fork y clonar es la opción adecuada si tienes pensado contribuir a docStatic o si prefieres fusionar futuras versiones de docStatic en tu sitio web mediante Git.

  1. Inicia sesión en tu cuenta de GitHub.
  2. Visita https://github.com/aowendev/docstatic.
  3. Haz clic en «Fork» (normalmente se encuentra en la esquina superior derecha).
  4. Deja el nombre predeterminado del repositorio tal cual.
  5. Introduce una descripción de tu proyecto.
  6. Asegúrate de que la opción «Copiar solo la rama principal» esté marcada.
  7. Haz clic en «Crear bifurcación».

GitHub crea una nueva rama del repositorio en tu cuenta de GitHub.

Clona tu bifurcación del repositorio docStatic​

Para crear un clon:

  1. Inicia sesión en tu cuenta de GitHub.
  2. Accede al repositorio de la bifurcación.
  3. Haz clic en el repositorio para abrirlo.
  4. Haz clic en <> Código y, a continuación, copia la URL.
  5. Abre tu terminal o línea de comandos y utiliza cd para ir a la ubicación donde quieras guardar el clon. Por ejemplo, cd Documentos/Proyectos/.
  6. Escribe git clone seguido de la URL de tu clon.
git clone https://github.com/acme-projects/docstatic.git

Instalar las dependencias del proyecto​

Este paso solo es necesario si has creado una bifurcación y clonado el repositorio; create-docstatic instala las dependencias por ti.

Utiliza cd para navegar hasta la carpeta raíz de tu repositorio docStatic clonado e instala los paquetes:

cd docstatic
yarn install

Yarn descargará todo lo que aparece en package.json. Esto puede tardar unos minutos.

Estructura del proyecto​

Tras crear tu sitio web o clonar el repositorio, verás varios archivos en la carpeta del proyecto. A continuación, hemos incluido algunos de los archivos y carpetas de la estructura del proyecto que debes tener en cuenta. No se trata de una lista completa de todo lo que contiene el proyecto.

docstatic
├── apis
│   └── petstore.yaml
├── bin
│   └── docstatic.js
├── blog
│   └── hybrid.mdx
├── config
│   ├── chatbot
│   │   └── index.json
│   ├── docusaurus
│   │   └── index.json
│   ├── sidebar
│   │   └── index.json
│   └── theme
│       └── index.json
├── create-docstatic
│   └── index.js
├── docs
│   └── introduction.mdx
├── i18n
│   └── fr
├── mcp-server
│   └── src
│       └── server.ts
├── reuse
│   ├── code
│   │   └── example.xml
│   ├── conditions
│   │   └── index.json
│   ├── glossaryTerms
│   │   └── index.json
│   ├── homepage
│   │   └── index.json
│   ├── media
│   │   └── index.json
│   ├── snippets
│   │   └── example.mdx
│   ├── taxonomy
│   │   └── index.json
│   ├── urls
│   │   └── index.json
│   ├── variableSets
│   │   └── index.json
│   ├── code-files.json
│   └── snippets-files.json
├── scripts
│   └── generate-media-index.js
├── src
│   ├── components
│   │   └── Dashboard
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── example-page.mdx
│       ├── index.js
│       └── index.module.css
├── static
│   └── img
├── template
│   └── docs
├── test
│   └── link-checker.test.mjs
├── tina
│   └── config.jsx
├── docusaurus.config.ts
├── package.json
├── README.md
├── sidebars.ts
└── yarn.lock

Resumen de la estructura del proyecto​

  • /apis/: archivos YAML de OpenAPI.
  • /bin/: el punto de entrada de la CLI docstatic que ejecuta create-docstatic para crear un nuevo sitio. Solo está presente si has clonado el repositorio docStatic.
  • /blog/: archivos MDX del blog.
  • /config/: archivos JSON que utiliza TinaCMS para configurar docStatic, incluidos los ajustes del chatbot y del tema.
  • /create-docstatic/: el paquete npm publicado como create-docstatic. Solo está presente si has clonado el repositorio docStatic.
  • /docs/: archivos MDX de la documentación.
  • /i18n/: archivos de traducción.
  • /mcp-server/: el servidor MCP que permite a los asistentes de IA acceder a tu documentación.
  • /reuse/: contenido reutilizable, incluidas las URL gestionadas y los ajustes de la página de inicio y de medios.
  • /scripts/: scripts de compilación que se ejecutan automáticamente mediante prebuild y predev.
  • /src/: archivos que no pertenecen a la documentación, como páginas o componentes React personalizados.
    • /src/components: componentes React personalizados, como los paneles y el chatbot.
    • /src/pages: cualquier archivo JSX/TSX/MDX dentro de este directorio se convierte en una página web.
  • /static/: carpeta estática. Todo el contenido que se encuentre aquí se copia en la raíz de la carpeta de la compilación final.
  • /template/: la plantilla de scaffolding que se mantiene sincronizada con el sitio principal y que create-docstatic distribuye a los nuevos sitios. Solo está presente si has clonado el repositorio docStatic. Consulta CLI.
  • /test/: la batería de pruebas del proyecto. Solo está presente si has clonado el repositorio docStatic.
  • /tina/: configuración de TinaCMS y esquema GraphQL.
  • /docusaurus.config.ts: archivo de configuración que contiene la configuración del sitio.
  • /package.json: un sitio web de docStatic es una aplicación de React. Puedes instalar y utilizar cualquier paquete de npm que desees.
  • /sidebars.ts: especifica el orden de los documentos en la barra lateral. Úsalo para la estructura de tu «índice».

Borrar la carpeta «docs»​

La carpeta docs/ incluye una copia de la documentación de docStatic: las páginas que estás leyendo ahora mismo. Está ahí a modo de ejemplo práctico, no como contenido para tu sitio web, así que elimínala antes de publicar y guarda tus propios temas en docs/ en su lugar. Si la dejas, tu sitio publicará el manual de docStatic bajo tu nombre.

Monorepos​

docStatic permite el uso de un único repositorio que contenga tanto el código del proyecto como la documentación del mismo. En la terminología de Docusaurus, este concepto se denomina «monorepo».

Para obtener más información, consulta Monorepos en la documentación de Docusaurus.

Vista previa de los cambios​

Para obtener una vista previa de los cambios a medida que editas los archivos, puedes ejecutar un servidor de desarrollo local que alojará tu sitio web y reflejará los últimos cambios.

Abre un terminal o una línea de comandos e introduce:

yarn dev

Por defecto, se abrirá una ventana del navegador en http://localhost:3000.

Compilación​

docStatic utiliza un generador de sitios estáticos para compilar el sitio web en una carpeta de contenido estático y subirlo a un servidor web donde se pueda visualizar. Para compilar el sitio web, utiliza:

yarn build-local

El contenido se genera en la carpeta /build, que puedes copiar a cualquier servicio de alojamiento de archivos estáticos, como GitHub Pages, Netlify o Vercel. Para obtener más información, consulta la sección Implementación en la documentación de Docusaurus.