Solución de problemas

La mayoría de los problemas afectan a la frontera entre configuración CLI, rutas de app/routes y contenido Markdown/MDX. Parte del síntoma y compara con el ejemplo Basic de la misma versión.

Problemas de instalación

Cannot find module 'ardo'

Comprueba que todas las dependencias necesarias estén instaladas:

pnpm add ardo@6

Error de versión de Node.js

Ardo necesita Node.js 22.22.0 o posterior. Comprueba tu versión:

node --version

Para actualizar, puedes usar nvm o fnm.

Problemas de compilación

Failed to resolve import

La CLI añade la integración automáticamente. Pon los ajustes del sitio en el archivo opcional ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Documentation",
})

Reserva vite.config.ts para plugins adicionales o ajustes propios de Vite. Ardo proporciona su integración.

Límite del paquete de documentación

Ardo trata la raíz Vite como un paquete independiente. Mantén allí una package.json e instala sus dependencias en su propio node_modules. Una instalación en un directorio padre o la raíz del monorepositorio no sustituye una instalación local ausente.

Ardo gestiona React, React DOM, Vite e iconos predeterminados desde su árbol de dependencias. Los demás imports directos deben declararse en el paquete de documentación, aunque otra dependencia ya los use. Las dependencias pueden usar sus paquetes transitivos declarados. Se admiten los enlaces pnpm normales al almacén virtual; su ubicación no cambia la pertenencia del paquete.

Mantén los componentes en el proyecto, por ejemplo en app/components/. Los imports relativos, alias y enlaces simbólicos a fuentes vecinas del workspace fallan en desarrollo y compilación, igual que los enlaces de paquetes hacia esas fuentes. Instala una biblioteca publicada. El enlace del propio Ardo se admite para desarrollar el framework mediante sus archivos dist compilados.

Ardo empaqueta las dependencias SSR con React. Los componentes y el renderer comparten esa ejecución; no hace falta una lista ssr.noExternal por componente. Una dependencia ausente produce un error [ardo], sin recurrir a instalaciones superiores. Vite optimiza las dependencias SSR en desarrollo para que CommonJS funcione en el mismo grafo.

Este límite afecta al grafo de la aplicación. Las entradas API y fuentes explícitas siguen siendo legibles para generar páginas; no habilitan imports de componentes externos.

Errores TypeScript en las rutas

La tabla de rutas es virtual; no hay tipos del router que regenerar. Comprueba la ruta y sus imports:

1. Comprueba que tsconfig.json extienda ardo/tsconfig e incluya app.
2. Importa las API y tipos React de ardo/react.
3. Ejecuta pnpm exec tsc --noEmit y reinicia el servidor TypeScript del editor si conserva diagnósticos antiguos.
4. Corrige los errores de API y colecciones en sus fuentes y configuración, no en el Markdown generado.

Error de memoria al compilar

Para sitios grandes, aumenta la memoria de Node.js:

NODE_OPTIONS=--max-old-space-size=4096 pnpm build

Problemas de desarrollo

La recarga en caliente no funciona

1. Comprueba que editas archivos de app/routes/.
2. Comprueba que el servidor Vite esté activo.
3. Reinícialo.

Los estilos no se aplican

Ardo carga sus estilos automáticamente. Comprueba el import CSS de app/root.tsx y la cascada para entender su interacción con la capa ardo.

La búsqueda no funciona

Los datos de búsqueda se generan desde las rutas en desarrollo y producción. No hace falta compilar antes de usar la búsqueda en desarrollo.

1. Comprueba que el documento esté en app/routes/ o una fuente activada.
2. Busca una palabra de un título o párrafo Markdown/MDX.
3. Revisa la consola y el terminal por fallos al cargar el índice.
4. Reinicia si un cambio de configuración añade una fuente.

Problemas de contenido

El Markdown no se muestra

Comprueba que el archivo:

1. Tenga extensión .md o .mdx.
2. Esté en app/routes/.
3. Tenga frontmatter válido, si lo usa.

Bloques sin resaltado

El resaltado usa Ferriki. Indica el lenguaje:

```javascript
const foo = "bar"
```

Los recursos estándar de Ferriki enumeran lenguajes y temas. Un lenguaje desconocido genera un aviso y se muestra como texto plano.

Fallo del motor nativo o los recursos

Ardo necesita Node.js 22.22 o posterior y binarios Linux/Windows x64/arm64 o macOS Apple Silicon. Activa las dependencias opcionales al instalar.

Ferriki descarga los recursos al primer uso. Para CI sin conexión, prepara y conserva una caché y define FERRIKI_CACHE_DIR y FERRIKI_ASSETS_REMOTE=0. Un tema o binario ausente hace fallar la compilación; consulta la solución de problemas de Ferriki.

CodeBlock sin resaltado en.tsx

ardo:codeblock-highlight necesita una prop language estática. Con variables o expresiones dinámicas se omite el resaltado y se muestra texto plano.

Proporciona el código como texto hijo, template literal o prop code:

import { ArdoCodeBlock } from "ardo/ui"

;<ArdoCodeBlock language="typescript">const x = 42</ArdoCodeBlock>

Para código totalmente dinámico, usa highlightCode de ardo/vite durante la compilación:

import { highlightCode } from "ardo/vite"
const html = await highlightCode(dynamicCode, "typescript")

Las imágenes no cargan

Usa rutas relativas al archivo Markdown:

![Alt text](./images/screenshot.png)

O rutas absolutas desde el directorio público:

![Alt text](/images/screenshot.png)

Problemas de despliegue

Error 404 al recargar

Ardo escribe un HTML por página y usa navegación normal entre documentos. Publica todo build/client/ y sirve los índices de directorio, como /guide/intro/index.html para /guide/intro/. Conserva la ruta base y usa 404.html para páginas ausentes. Consulta Despliegue.

Si la raíz devuelve 404 en desarrollo, añade app/routes/home.tsx o app/routes/index.mdx. Comprueba que la portada enlace a un documento existente antes de recompilar.

Problemas de ruta base

Para un subdirectorio, define base en ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  base: "/my-docs/",
})

Obtener ayuda

Si tu problema no aparece aquí:

1. Busca problemas similares en GitHub Issues.
2. Pregunta en GitHub Discussions.
3. Abre una incidencia con una reproducción mínima.