Documentación

Agradecemos su interés en mejorar nuestra documentación. Ya sea un miembro del equipo o un colaborador externo, hay varias formas en las que puede ayudar:

Actualizar documentos existentes: Corregir errores o agregar nueva información a las páginas actuales.
Crear nuevo contenido: Escribir nuevas páginas o secciones sobre temas que aún no hemos cubierto.
Traducir documentos: Ayudarnos a llegar a más personas traduciendo a otros idiomas.

Elija el método de contribución que mejor se adapte a usted a continuación.

Actualización de documentación existente

Miembros del equipo

En la parte inferior de cada página del sitio web, encontrará un enlace de Editar página. Haga clic en este enlace para abrir la página en GitHub. Estos son los pasos para hacerlo:

Haga clic en el enlace Editar página en la parte inferior de la página.
Realice sus cambios en la documentación.
Confirme (commit) los cambios.

Colaboradores externos

Si no es miembro del equipo, aún puede contribuir al proyecto. Así es cómo:

Haga un fork del repositorio de documentación.
Ventana de terminal
```
https://github.com/nahpu/nahpu-docs.git
```
Si está utilizando GitHub CLI.
Ventana de terminal
```
gh repo clone nahpu/nahpu-docs
```
Realice los cambios en la documentación.
Envíe un pull request.

Crear nuevo contenido

Para crear una o dos páginas, puede agregar un nuevo archivo en el repositorio de GitHub. Los archivos de documentación están dentro de src/content/docs/[idioma]. Requerimos agregar primero el contenido en inglés y luego escribir la traducción para el resto de los idiomas. Preferimos la documentación en formato markdoc .mdoc. Sin embargo, puede comenzar con un markdown simple y dejar que el mantenedor de la documentación haga el resto.

Para un escenario más complejo con páginas y enrutamiento complejos, consulte la sección de Profundización para más detalles.

Agregar traducción a un nuevo idioma

Siempre estamos buscando hablantes de idiomas que no admitimos actualmente. Para facilitar la adición de nuevos idiomas, utilizamos IA para asistir con las traducciones. Si está interesado en contribuir, comuníquese con uno de nuestros miembros del equipo. Nuestro flujo de trabajo para agregar un nuevo idioma implica:

Crear un nuevo directorio de idioma en la carpeta src/content/docs. El nombre de la carpeta sigue el código del idioma (por ejemplo, en, es, fr).
Usar un modelo de lenguaje grande para traducir la documentación en inglés.
Agregar las traducciones de la barra lateral en el archivo astro.config.mjs.
Revisar y corregir la traducción de la IA para asegurar su precisión por parte de un miembro del equipo.

Profundización

Esta sección explica el método avanzado para desarrollar la documentación de NAHPU.

Tecnologías

A continuación se muestra una lista de las tecnologías utilizadas en la documentación de NAHPU:

Astro - Generador de sitios estáticos
Starlight - Tema de documentación para Astro
Markdoc - Formato de documentación
Tailwind CSS - Framework CSS basado en utilidades

Desarrollo local

Prerrequisitos

Necesitará instalar Bun y un editor de código (por ejemplo, VS Code) en su máquina. A continuación se presenta la guía paso a paso:

Instale bun.
Ventana de terminal
```
curl -fsSL https://bun.com/install | bash
```
Siga la documentación de bun para más detalles.
Verifique la instalación de bun.
Ventana de terminal
```
bun --version
```
Si la instalación fue exitosa, debería ver el número de versión.
Clone el repositorio de documentación.
Ventana de terminal
```
git clone https://github.com/nahpu/nahpu-docs.git
```
Cambie al directorio del repositorio.
Ventana de terminal
```
cd nahpu-docs
```
Si utiliza VS Code, puede abrir directamente el repositorio en el editor.
Ventana de terminal
```
code nahpu-docs
```
Instale todas las dependencias:
Ventana de terminal
```
bun install
```
Realice los cambios.
La documentación se encuentra en la carpeta src\content\docs\[idioma]. Otras páginas están en src\pages.

Estructura de directorios

Aquí está la estructura de directorios y una breve descripción de cada archivo/directorio.

astro.config.mjs Configuración del sitio Astro
markdoc.config.mjs Configuración de la documentación Markdoc
package.json Dependencias y scripts del proyecto
README.md Resumen e instrucciones del proyecto
tsconfig.json Configuración de TypeScript
Directoriopublic/ Activos estáticos servidos directamente
- …
Directoriosrc/ Directorio principal de código fuente
- content.config.ts Configuración de gestión de contenidos
- Directorioassets/ Archivos multimedia como imágenes
  - …
- Directoriocomponents/ Componentes de interfaz de usuario reutilizables
  - …
- Directoriocontent/ Archivos de documentación organizados por idioma
  - …
- Directoriolayouts/ Componentes de diseño para plantillas de página reutilizables
  - …
- Directoriopages/ Páginas principales del sitio
  - …
- Directoriostyles/ Hojas de estilo CSS globales
  - …

Para más detalles sobre la estructura de directorios, siga las guías de Astro y la documentación de Starlight.

Convención de código

Si el mismo fragmento de código aparece en varios lugares, use un componente compartido para evitar la duplicación y asegurar la consistencia. Coloque el componente compartido en el directorio src/components con un nombre de archivo que siga la convención PascalCase, por ejemplo, SharedComponent.astro.
También puede usar el Layout para una plantilla de interfaz de usuario reutilizable. El nombre del archivo sigue una convención similar a la de los componentes.
Los Layouts deben seguir la misma convención de nomenclatura que los componentes y colocarse en el directorio src/layouts.
Evite usar CSS puro para el estilo siempre que sea posible. Use tailwindcss en su lugar. Utilizamos Tailwind v4.
Evite escribir muchas clases en el elemento. En su lugar, use la variable constante cntl para almacenar las clases. Vea el archivo pages/index.astro para un ejemplo.

Agregar nuevos componentes

Cree un nuevo componente en src/components/. Use PascalCase para el nombre del archivo, por ejemplo, MiComponente.astro.
src/components/MiComponente.astro
```
<div>
  El contenido de su componente aquí
</div>
```

Regístrelo como una etiqueta Markdoc en markdoc.config.mjs.

import { defineMarkdocConfig, component } from "@astrojs/markdoc/config";
import starlightMarkdoc from "@astrojs/starlight-markdoc";

export default defineMarkdocConfig({
  extends: [starlightMarkdoc()],
  tags: {
    mycomponent: {
      render: component("./src/components/MiComponente.astro"),
      selfClosing: true,
    },
  },
});

Úselo en cualquier archivo .mdoc.
```
{% mycomponent / %}
```

Use selfClosing: true para componentes que no envuelven contenido. Para componentes que envuelven contenido, omítalo y use etiquetas de apertura y cierre:

{% mycomponent / %}

Ejecución del sitio web localmente

Ejecute astro en modo de desarrollo
Ventana de terminal
```
bun run dev
```
Abra su navegador y navegue a http://localhost:4321/ para ver el sitio web de documentación.

En VS Code puede presionar CTRL + clic en el enlace que se muestra en la terminal.