Documentación Cordlang (español)

Sitio de documentación oficial escrito en Cordlang y generado a React. Todo el contenido visible está en español; la fuente de verdad es src/**/*.cord (no editar dist/).

Posicionamiento (manda sobre otras lecturas): Cordlang es un IR de UI para vibecode e IA — fuentes densas, menos tokens que JSX, check determinista, sin LLM en compile. Si alguna página o doc hermano prioriza “otro framework” o amplitud de backends, gana este contrato. Contrato agentes: ruta /ia y ../cordlang/docs/AI_CONTEXT.md.

Dirección visual: Signal Precision (tinta + acento #3DFFB5, tipografías Syne / IBM Plex). Atmósfera y motion en public/site.css + helpers en public/site.js.

Notas de backends (2026)

Contrato default (loop IA): React / Svelte / HTML preview.
Además, el CLI emite Vue 3, Solid, email, PDF, y meta Next / SvelteKit como destinos experimentales — útiles, pero no el norte de producto ni el contrato IA. Detalle en ../cordlang/docs/.

Playground WASM: stub (PLAYGROUND.md) — aplazado respecto al loop IA.

Requisitos

• Compilador Cordlang construido desde el repo hermano ../cordlang
• Node.js + npm para cordlang run react / --check

Estructura

src/
  app.cord                 # theme + layout + routes
  layouts/docs.cord        # shell con sidebar
  components/
    SiteHeader.cord        # nav + buscar + tema
    SiteFooter.cord
    DocNav.cord            # sidebar (NavLink / aria-current)
    DocToc.cord            # TOC on-page
    CodeSample.cord        # chrome + copiar
    LiveCounter.cord       # demo state
    LiveListDemo.cord      # demo if/select
  pages/
    HomePage.cord          # showcase / hero
    …
public/
  site.css                 # atmósfera, motion, dark theme
  site.js                  # tema, búsqueda, copy
  search-index.json
cordlang.json

Rutas

Ruta	Página
/	Inicio (showcase)
/instalacion	Instalación
/guia	Guía práctica (+ demos)
/cheatsheet	Cheatsheet
/ejemplos	Catálogo + demos vivas
/templates	Templates Cord (init --template)
/react	Mapa Cordlang ↔ React
/ia	Contrato para modelos / agentes
/roadmap	Roadmap resumido

Comandos

Desde este directorio (doc/):

# construir el CLI una vez
make -C ../cordlang

../cordlang/cordlang check
../cordlang/cordlang run                 # preview HTML nativo
../cordlang/cordlang run react           # genera dist/react
../cordlang/cordlang run react --check   # + npm install si hace falta + vite build
../cordlang/cordlang run react --watch

Tras run react:

cd dist/react
npm install   # si aún no
npm run dev

Trampas del lenguaje (al editar docs)

• Interpolación: #{expr} se evalúa en runtime. Para mostrar la sintaxis literal en ejemplos usa \#{expr} (el compilador emite el texto #{…}).
• Comillas en strings: "say \"hi\"" ya funciona (lexer unescape). Prefiere ejemplos sin comillas anidadas cuando se pueda.
• Nombres con punto: "build.bat" es texto literal (no expresión JS).
• slot: en layouts → outlet de router; en componentes (CodeSample) → children.
• Clases CSS del sitio: class=hero-shell (una clase) o class="a b" (varias). No uses bool attrs inventados (reveal solo).
• No edites dist/ como fuente de verdad.

Scaffold / meta HTML

En cordlang.json puedes fijar:

• lang — atributo html lang (este sitio usa "es")
• title — <title> (si falta, se usa name)

El scaffold React envuelve la app en ErrorBoundary, carga fuentes Google y enlaza /site.css + /site.js desde public/.

UX del sitio

• Nav activa: link emite NavLink (React) con aria-current="page".
• Dark mode: botón Tema en el header (site.js + [data-theme=dark]).
• Búsqueda: panel en header; filtrado client-side.
• CodeSample: botón Copiar vía data-copy + site.js.
• Mapa Svelte: diferido; ver Roadmap. Este sitio documenta el backend React.
• Responsive: el scaffold apila aside bajo ~768px; header sticky con z-index.