53. Ejemplo de documento Markdown profesional {#53-ejemplo-de-documento-markdown-profesional}

# Nebula

[![CI](https://github.com/ejemplo/nebula/actions/workflows/ci.yml/badge.svg)](https://github.com/ejemplo/nebula/actions/workflows/ci.yml)
[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-yellow.svg)](LICENSE)
[![Versión](https://img.shields.io/badge/versi%C3%B3n-1.4.0-blue.svg)](CHANGELOG.md)
[![Documentación](https://img.shields.io/badge/docs-nebula.dev-informational)](https://example.com/nebula/docs)

> **Nebula** es una herramienta de línea de comandos para generar documentación técnica a partir de archivos Markdown. Convierte un repositorio de documentos en un sitio navegable, validado y listo para publicar.

## Tabla de contenidos

- [Características](#características)
- [Arquitectura](#arquitectura)
- [Requisitos](#requisitos)
- [Instalación](#instalación)
- [Inicio rápido](#inicio-rápido)
- [Configuración](#configuración)
- [Comandos](#comandos)
- [API](#api)
- [Pruebas](#pruebas)
- [Integración continua](#integración-continua)
- [Roadmap](#roadmap)
- [Contribución](#contribución)
- [Licencia](#licencia)
- [Referencias](#referencias)

## Características

- Generación estática a partir de Markdown y Front Matter.
- Validación de enlaces internos y externos.
- Búsqueda local sin servicios externos.
- Temas claros y oscuros.
- Soporte de tablas GFM, notas al pie y bloques de código resaltados.
- Diagramas Mermaid opcionales.
- Salida HTML accesible y responsive.

## Arquitectura

```mermaid
flowchart LR
    A[Documentos Markdown] --> B[Parser]
    B --> C[AST]
    C --> D[Transformaciones]
    D --> E[HTML]
    E --> F[Sitio estático]
    C --> G[Validación]
    G --> H[Informe de errores]
```

El flujo separa el análisis, las transformaciones y la publicación. La validación se ejecuta antes de generar el sitio para evitar publicar enlaces rotos.

## Requisitos

| Componente | Versión mínima | Notas |
|---|---|---|
| Node.js | 20 LTS | Recomendado |
| npm | 10 | O pnpm 9 |
| Git | 2.40 | Para el modo repositorio |

## Instalación

```bash
npm install --global nebula-cli
nebula --version
```

Si prefieres una instalación local:

```bash
npm install --save-dev nebula-cli
npx nebula --version
```

## Inicio rápido

1. Crea un directorio `docs/`.
2. Añade un archivo `docs/index.md`.
3. Ejecuta el generador:

```bash
nebula build --source docs --output dist
```

4. Abre `dist/index.html` en el navegador o publica `dist/` en tu hosting.

![Captura de la interfaz de Nebula con el índice lateral y el contenido principal](docs/images/interfaz.png)

## Configuración

Crea `nebula.config.json` en la raíz del proyecto:

```json
{
  "source": "docs",
  "output": "dist",
  "site": {
    "title": "Mi documentación",
    "lang": "es",
    "baseUrl": "/"
  },
  "features": {
    "search": true,
    "mermaid": true,
    "darkMode": true
  }
}
```

| Opción | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
| `source` | string | `docs` | Carpeta de entrada |
| `output` | string | `dist` | Carpeta de salida |
| `site.title` | string | `Documentación` | Título del sitio |
| `site.lang` | string | `es` | Idioma principal |
| `features.search` | boolean | `true` | Activa la búsqueda local |
| `features.mermaid` | boolean | `false` | Renderiza diagramas Mermaid |
| `features.darkMode` | boolean | `true` | Añade selector de tema |

## Comandos

| Comando | Descripción |
|---|---|
| `nebula build` | Genera el sitio |
| `nebula serve` | Sirve el sitio en local con recarga |
| `nebula check` | Valida enlaces y Front Matter |
| `nebula clean` | Elimina la salida generada |

## API

### `build(options)`

Genera el sitio y devuelve un resumen.

```javascript
import { build } from "nebula-cli";

const result = await build({
  source: "docs",
  output: "dist",
  failOnBrokenLinks: true
});

console.log(result.pages);
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `source` | string | No | Carpeta de entrada |
| `output` | string | No | Carpeta de salida |
| `failOnBrokenLinks` | boolean | No | Falla si hay enlaces rotos |

## Pruebas

```bash
npm test
npm run test:e2e
```

La suite incluye pruebas unitarias del parser, pruebas de integración del generador y comprobaciones de accesibilidad con axe.

## Integración continua

```yaml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
      - run: npm run lint
      - run: npm run build
```

## Roadmap

- [x] Parser CommonMark
- [x] Generación de HTML
- [x] Búsqueda local
- [ ] Versionado de documentación
- [ ] Traducciones
- [ ] Exportación a PDF

## Contribución

1. Haz un fork del repositorio.
2. Crea una rama descriptiva: `git switch -c feat/mi-cambio`.
3. Añade pruebas y documentación.
4. Ejecuta `npm test` y `npm run lint`.
5. Abre un pull request.

Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para más detalles.

## Licencia

Distribuido bajo la licencia MIT. Consulta [LICENSE](LICENSE).

## Referencias

- [Documentación de Nebula](https://example.com/nebula/docs)
- [CommonMark](https://commonmark.org/)
- [GitHub Flavored Markdown](https://github.github.com/gfm/)
- [Mermaid](https://mermaid.js.org/)
- [Keep a Changelog](https://keepachangelog.com/)
- [Semantic Versioning](https://semver.org/)