Primeros pasos

Dale esta frase a tu agente de programación, en un repositorio nuevo o existente. El enlace lleva a las instrucciones versionadas para agentes. El agente adapta el ejemplo Basic probado e informa del resultado de la comprobación de tipos, las pruebas y la compilación. Revisas el resultado como cualquier otra pull request.

Sin agente, sigue la instalación manual de abajo.

Requisitos

Necesitas:

• Node.js 22.22.0 o posterior
• Linux o Windows en x64/arm64, o macOS en Apple Silicon, con las dependencias nativas opcionales activadas
• pnpm (recomendado), npm o yarn

Estructura del proyecto

Así es un proyecto Ardo. Los archivos de app/routes/ se convierten en páginas, app/root.tsx contiene la interfaz del sitio y el resto es configuración:

my-docs/
├── app/
│   ├── routes/                  # Pages: .md, .mdx, and .tsx files
│   │   ├── guide/
│   │   │   └── getting-started.mdx
│   │   └── home.tsx             # Home page
│   └── root.tsx                 # Optional: theme, logo, header, sidebar, footer
├── ardo.config.ts               # Optional site configuration
├── vite.config.ts               # Optional extra Vite plugins or settings
├── pnpm-workspace.yaml          # pnpm build-script allowlist, when using pnpm
├── tsconfig.json
└── package.json

Instalación manual

Estos pasos crean un proyecto de documentación nuevo. En un repositorio existente, colócalo en su propio paquete o directorio: Ardo genera un sitio estático independiente sin compartir router ni archivos de entrada con tu aplicación.

1. Crear un proyecto

mkdir my-docs
cd my-docs
pnpm init

2. Instalar las dependencias

pnpm add ardo@6
pnpm add -D typescript@6

TypeScript 6 o posterior comprueba los tipos de un sitio Ardo. La documentación de la API opcional necesita una nightly de TypeScript 7.1 fijada; cámbiala cuando añadas api.

3. Añadir los scripts

Ardo gestiona React, React DOM y Vite como dependencias propias. Su CLI arranca el servidor de desarrollo, compila el sitio estático y permite previsualizar la salida del cliente:

{
  "scripts": {
    "dev": "ardo dev",
    "build": "ardo build",
    "preview": "ardo preview"
  }
}

Con pnpm, añade una lista de scripts de compilación permitidos para que esbuild pueda preparar la dependencia nativa de Vite:

# pnpm-workspace.yaml
packages:
  - "."

allowBuilds:
  esbuild: true

4. Añadir configuración opcional de Ardo

Ardo funciona sin archivo de configuración. Añade ardo.config.ts para metadatos, despliegue o contenido. El tema, la navegación, la barra lateral y el pie de página se configuran mediante props JSX en root.tsx:

ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Documentation",
  description: "My awesome documentation site",
})

El sitio se sirve desde la raíz del dominio. Para una subruta, como un sitio de proyecto de GitHub Pages, define base. La guía de despliegue cubre los proveedores.

Añade vite.config.ts solo si necesitas plugins adicionales o ajustes específicos de Vite. La CLI de Ardo añade automáticamente la integración de compilación, así que tu configuración no necesita llamar a ardo().

5. Crear los archivos de la aplicación

El contenido por sí solo ya es un sitio: sin app/root.tsx, Ardo renderiza <ArdoRoot />, es decir, una cabecera con búsqueda y selector de tema, una sección lateral por carpeta de app/routes/ y un pie de página. Ardo también genera la estructura HTML y la tabla de rutas y proporciona las entradas del cliente y servidor, la configuración y los estilos. Añade app/root.tsx cuando quieras tu propio tema, logotipo o interfaz; su exportación predeterminada es el componente raíz.

app/root.tsx:

import { ArdoRoot } from "ardo/ui"

export default function Root() {
  return <ArdoRoot />
}

Pasa ArdoHeader, ArdoSidebar o ArdoFooter como hijos para modificar la interfaz, por ejemplo para añadir un enlace de navegación:

import { ArdoHeader, ArdoNav, ArdoNavLink, ArdoRoot } from "ardo/ui"

export default function Root() {
  return (
    <ArdoRoot>
      <ArdoHeader>
        <ArdoNav>
          <ArdoNavLink to="/guide/getting-started">Guide</ArdoNavLink>
        </ArdoNav>
      </ArdoHeader>
    </ArdoRoot>
  )
}

Diseño y navegación describe las secciones de la barra lateral, el pie de página y las exportaciones opcionales Layout y ErrorBoundary de root.tsx.

tsconfig.json:

{
  "extends": "ardo/tsconfig",
  "include": ["app/**/*", "*.ts"]
}

El preset configura jsx, jsxImportSource: "ardo" y las declaraciones de Ardo, de modo que los imports de React, MDX y virtual: se comprueban sin más ajustes.

Importa componentes de ardo/ui, API de ejecución como ArdoLink y useArdoPath de ardo/runtime y hooks de React de ardo/react. Ardo incluye React, así que tu paquete de documentación no necesita una dependencia React propia.

6. Crear las primeras páginas

Crea una página de inicio para que la URL raíz y el logo de la cabecera tengan un destino:

app/routes/home.tsx:

import { ArdoHero } from "ardo/ui"

export default function HomePage() {
  return (
    <ArdoHero
      name="My Documentation"
      tagline="Guides and examples for your project."
      actions={[{ text: "Get started", link: "/guide/getting-started", theme: "brand" }]}
    />
  )
}

Añade la guía enlazada desde la portada, la cabecera y la barra lateral:

app/routes/guide/getting-started.mdx:

---
title: Getting Started
---

# Getting Started

Welcome to your documentation site!

Ejecuta pnpm dev y abre http://localhost:5173. Deberías ver la portada; elige Get started para abrir la guía.

Desarrollo

Arranca el servidor de desarrollo:

pnpm dev

El sitio estará disponible en http://localhost:5173. Vite gestiona los cambios de las rutas MDX y TSX.

Compilación de producción

Cuando quieras publicar:

pnpm build

La salida está en build/client/: un index.html prerenderizado por página, una 404.html y los recursos con hash de contenido, listos para cualquier alojamiento estático. La compilación debe informar de dos páginas prerenderizadas y ningún enlace interno roto. Comprueba cada enlace y ancla del HTML generado. Previsualízalo localmente antes de desplegar:

pnpm preview

Siguientes pasos

Tu sitio ya funciona. Ahora personalízalo:

• Añade páginas, secciones laterales, un logo y enlaces de cabecera con Diseño y navegación
• Escribe contenido más rico con Markdown y MDX y los componentes incluidos
• Cambia colores y estilos con la personalización visual, incluido Tailwind CSS opcional
• Despliega tu sitio en GitHub Pages, Netlify, Vercel o cualquier alojamiento estático
• Genera páginas de referencia con la documentación de la API