Arquitectura Lógica

El diseño técnico de @lynx/astro prioriza la simplicidad en la creación de contenido y la eficiencia en su distribución.

Estructura de Contenidos

Los documentos residen en src/content/docs/ y se organizan jerárquicamente para facilitar su indexación por parte del sistema de búsqueda integrado.

[!TIP] @lynx/astro utiliza el sistema de Content Collections de Astro para garantizar que cada documento cumpla con los esquemas de metadatos requeridos por Starlight.

Starlight

Starlight es un sistema de documentación para Astro que permite crear documentación técnica de alta calidad de forma sencilla. Proporciona una experiencia de lectura fluida y herramientas de búsqueda avanzadas mediante Starlight.

Cómo añadir o modificar documentación

Para añadir o modificar documentación, se debe seguir un proceso estandarizado que asegura la consistencia visual y técnica:

1. Definición de Frontmatter: Cada archivo debe iniciar con metadatos descriptivos (título, descripción, etc.). El formato de frontmatter es:

---
title: Título de la página
description: Descripción de la página
---

2. Uso de MDX: Para elementos interactivos o componentes React, utiliza la extensión .mdx. Si se requiere usar componentes de Astro es indispensablle usar MDX.

---
import MyComponent from '../../components/MyComponent.astro'
---

# Título

<MyComponent />

...

3. Diagramación: Utiliza bloques de código mermaid para representar flujos lógicos.

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

4. Verificación Local: Ejecuta el comando pnpm --filter=@lynx/astro dev para previsualizar los cambios en tiempo real.

Internacionalización

@lynx/astro soporta i18n para permitir la documentación en múltiples idiomas. El idioma canónico por defecto es Español y se almacena en src/content/docs. Los idiomas adicionales se almacenan en src/content/docs/{lang} donde {lang} es el código del idioma. Por ejemplo, para Alemán, se almacenaría en src/content/docs/de. Los locales activos se configuran en astro.config.ts.

Mantener los locales adicionales es opcional, ya que se pueden traducir mediante GitHub Actions (docs-translator.yml).

src/content/docs/
├── introduction.mdx
└── en/
    ├── introduction.mdx
    └── ...

Los nombres de los documentos y sus carpetas determinan su URL, y deben hacer match entre todas los idiomas para que Astro reconozca las versiones alterntativas de un documento.