Contribuir a la Documentación

¡Gracias por tu interés en contribuir a la documentación de Xainflow! Esta guía te ayudará a comenzar.

Requisitos Previos

Antes de comenzar, asegúrate de tener:

• Node.js versión 20.0 o superior
• Git instalado
• Una cuenta de GitHub

Primeros Pasos

1. Clonar el Repositorio

git clone https://github.com/xainflow/xainflow-docs.git
cd xainflow-docs

2. Instalar Dependencias

cd docs
npm install

3. Iniciar el Servidor de Desarrollo

npm start

Esto iniciará un servidor de desarrollo local en http://localhost:3000. El sitio se recargará automáticamente cuando realices cambios.

Agregar Documentación

Crear un Nuevo Documento

1. Navega al directorio docs/docs/
2. Crea un nuevo archivo Markdown (ej., mi-nuevo-doc.md)
3. Agrega el frontmatter en la parte superior del archivo:

---
sidebar_position: 3
---

# Mi Nuevo Documento

Tu contenido aquí...

Estructura del Documento

Cada documento debe tener:

• Frontmatter - Metadatos YAML en la parte superior
• Título - Encabezado H1 (usado automáticamente como título de página)
• Contenido - Tu documentación en Markdown

Opciones de Frontmatter

Propiedad	Descripción	Ejemplo
sidebar_position	Orden en la barra lateral	1, 2, 3
sidebar_label	Etiqueta personalizada de la barra lateral	"Primeros Pasos"
title	Título de la página (anula H1)	"Mi Título Personalizado"
description	Meta descripción	"Una guía para..."
slug	Ruta URL personalizada	/ruta-personalizada

Organizar Documentos

Crear Categorías

Para crear una nueva categoría (carpeta con múltiples docs):

1. Crea una nueva carpeta en docs/docs/ (ej., docs/docs/guias/)
2. Agrega un archivo _category_.json:

{
    "label": "Guías",
    "position": 3,
    "link": {
        "type": "generated-index",
        "description": "Aprende a usar Xainflow con estas guías."
    }
}

3. Agrega tus documentos dentro de la carpeta

Ejemplo de Estructura

docs/docs/
├── intro.md
├── contributing.md
├── guias/
│   ├── _category_.json
│   ├── primeros-pasos.md
│   └── uso-avanzado.md
└── arquitectura/
    ├── _category_.json
    ├── resumen.md
    └── despliegue.md

Directrices de Escritura

Características de Markdown

Docusaurus soporta características extendidas de Markdown:

Bloques de Código con Resaltado de Sintaxis

```javascript title="ejemplo.js"
function hola() {
    console.log("¡Hola, Xainflow!");
}
```

Admoniciones

:::note[Esto es una nota. :::]

:::tip[Esto es un consejo útil. :::]

:::warning[Esto es una advertencia. :::]

:::danger[Esto es una alerta de peligro. :::]

:::info[Esto es informativo. :::]

Pestañas

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm" default>
    npm install paquete
  </TabItem>
  <TabItem value="yarn" label="Yarn">
    yarn add paquete
  </TabItem>
</Tabs>

Mejores Prácticas

1. Sé Claro y Conciso - Usa lenguaje simple y oraciones cortas
2. Usa Ejemplos - Incluye ejemplos de código siempre que sea posible
3. Agrega Imágenes - Los recursos visuales ayudan a explicar conceptos complejos
4. Enlaza Docs Relacionados - Haz referencias cruzadas a documentación relacionada
5. Mantente Actualizado - Actualiza los docs cuando cambien las funcionalidades

Agregar Publicaciones de Blog

Crear una Publicación de Blog

1. Navega al directorio docs/blog/
2. Crea un nuevo archivo con la convención de nombres: AAAA-MM-DD-titulo.md

---
slug: mi-primera-publicacion
title: Mi Primera Publicación de Blog
authors: [tu-nombre]
tags: [anuncio, funcionalidad]
---

Tu contenido de blog aquí...

<!-- truncate -->

Más contenido después del corte...

Opciones de Publicación de Blog

Propiedad	Descripción
slug	Ruta URL para la publicación
title	Título de la publicación
authors	Array de IDs de autor (definidos en authors.yml)
tags	Array de etiquetas
date	Anular fecha de publicación
image	Imagen de tarjeta social

Agregar Imágenes

1. Coloca las imágenes en docs/static/img/
2. Referenciarlas en tu Markdown:

![Texto alternativo](/img/mi-imagen.png)

Para imágenes específicas de documentación, también puedes usar rutas relativas:

![Texto alternativo](./img/mi-imagen.png)

Enviar Cambios

1. Crear una Rama

git checkout -b docs/mi-nueva-funcionalidad

2. Realizar tus Cambios

Edita o crea archivos de documentación según sea necesario.

3. Previsualizar tus Cambios

npm start

4. Confirmar tus Cambios

git add .
git commit -m "docs: agregar guía para nueva funcionalidad"

5. Enviar y Crear un Pull Request

git push origin docs/mi-nueva-funcionalidad

Luego crea un Pull Request en GitHub.

Compilar para Producción

Para probar la compilación de producción localmente:

npm run build
npm run serve

Esto compilará el sitio y lo servirá en http://localhost:3000.

¿Necesitas Ayuda?

• Consulta la documentación de Docusaurus
• Abre un issue en GitHub