Markdown y MDX

Ardo empieza con Markdown sin limitarte a él. Usa texto y bloques de código; pasa a MDX cuando necesites un ejemplo React interactivo, un componente o un aviso del sistema de diseño, sin cambiar de herramientas.

Nombres de archivos de página

Los archivos de app/routes/ se convierten en URL. Usa nombres descriptivos como guide/getting-started.mdx o guide/c-sharp.mdx. Ardo rechaza # y ? en nombres de archivos y directorios porque delimitan fragmentos y consultas. Puedes usarlos en títulos y contenido.

Sintaxis básica

Títulos

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

Énfasis

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Listas

- Unordered item 1
- Unordered item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2

Enlaces e imágenes

[Link text](https://example.com)
![Alt text](/path/to/image.png)

GitHub Flavored Markdown

Ardo admite GitHub Flavored Markdown (GFM) de serie.

Tablas

Listas de tareas

• Escribir documentación
• Añadir resaltado de sintaxis
• Desplegar en producción

Enlaces automáticos

Las URL se convierten automáticamente en enlaces:https://vite.dev

Resaltado de sintaxis

Ferromark resalta los bloques durante la compilación con su integración nativa Ferriki. Las gramáticas y temas estándar se descargan y guardan en caché al primer uso. Ejemplos:

interface User {
  id: string
  name: string
  email: string
}

function greetUser(user: User): string {
  return `Hello, ${user.name}!`
}

Destacar líneas

Destaca líneas con la sintaxis {lines}:

function example() {
  const highlighted = true
  const normal = false
  const alsoHighlighted = true
  const highlighted = true
  const notHighlighted = false
}

Números de línea

Activa los números con showLineNumbers:

const first = 1
const second = 2
const third = 3

Título

Añade un título al bloque, compatible con las líneas destacadas:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.json",
    title: "API Reference",
  },
})

Prompts

Usa el lenguaje prompt para texto que se copia a un agente. Las líneas se ajustan en lugar de desplazarse horizontalmente; escribe cada párrafo en una sola línea fuente:

```prompt
Add a Deployment page that explains the GitHub Pages workflow of this repository.
```

Grupos de código

Muestra variantes de código en pestañas:

function greet(name) {
  return `Hello, ${name}!`
}

function greet(name: string): string {
  return `Hello, ${name}!`
}

def greet(name):
    return f"Hello, {name}!"

Avisos

Markdown sin imports: Ardo reconoce las alertas de GitHub y las asocia al aviso correspondiente.

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Negative potential consequences of an action.

Resultado:

Para un título propio, usa componentes como <Tip title="Pro Tip">, descritos en Componentes.

Componentes

Los componentes Ardo funcionan sin imports en MDX: avisos, badges, tarjetas, pestañas, acordeones, pasos, bloques e iconos. Componentes los muestra con su MDX y props.

Tus componentes

Importa componentes React y úsalos como HTML. Guárdalos fuera de app/routes/, por ejemplo en app/components/: cada .tsx de rutas se convierte en página.

import { MyComponent } from "../../components/MyComponent"

# My Page

<MyComponent prop="value" />

Fragmentos reutilizables

Ardo usa módulos MDX estándar: reutilizar contenido no necesita sintaxis ni plugins especiales. Pon los fragmentos en snippets/ e impórtalos donde hagan falta.

Por ejemplo, define una nota común en app/snippets/prerequisites.mdx. Los fragmentos dentro de otra página no necesitan frontmatter:

<Tip title="Before you start">
  This guide assumes you have {props.runtime} installed and can run packages with{" "}
  {props.packageManager}.
</Tip>

Impórtalo en una página MDX y úsalo dentro de ArdoBareContent para que no añada su propio wrapper de página:

import { ArdoBareContent } from "ardo/ui"
import Prerequisites from "../../snippets/prerequisites.mdx"

# Getting Started

<ArdoBareContent>
  <Prerequisites runtime="Node.js 22.22.0+" packageManager="pnpm" />
</ArdoBareContent>

Los fragmentos reciben props mediante expresiones MDX, combinan componentes Ardo y viven junto al código. Vite gestiona imports y recarga como en otras dependencias de rutas.

En rutas TSX

Un .mdx importado en .tsx usa normalmente el wrapper Content completo: artículo, cabecera, pie y navegación. Es útil para páginas completas, pero los fragmentos suelen necesitar solo contenido. Usa ArdoBareContent para integrarlo sin esa estructura:

import { ArdoBareContent } from "ardo/ui"
import MySnippet from "./snippet.mdx"

export default function MyPage() {
  return (
    <ArdoBareContent>
      <MySnippet />
    </ArdoBareContent>
  )
}

Compilación de MDX

Ferromark analiza .md y .mdx. MDX añade expresiones JavaScript, imports, exports y componentes JSX; React compila el JSX mediante Vite. Usa frontmatter YAML para metadatos.

Ferromark compila cada ruta como módulo MDX siguiendo el contrato de @mdx-js/mdx:

• import y export son JavaScript. La sintaxis TypeScript falla; mueve el código tipado a un módulo .ts importado.
• Los componentes importados se usan directamente. Los demás se buscan primero en Ardo y después en la prop components. El error indica el nombre de cualquier componente ausente.
• export default se convierte en diseño y sustituye el wrapper: tu diseño rodea la página en lugar de ArdoDocContent.
• El JSX dentro de expresiones como {items.map((item) => <Card />)} no accede a los componentes Ardo: impórtalos explícitamente.
• Los nombres _components, _createMdxContent, _missingMdxReference, _provideComponents, MDXLayout, MDXContent, _ArdoPageDataProvider, _ardoFrontmatter, _ardoRoute y _ardoToc están reservados. Declararlos provoca un error de compilación.

Frontmatter

Añade metadatos mediante frontmatter YAML:

---
title: Page Title
description: Page description for SEO
order: 2
---

Consulta todas las opciones en la referencia del frontmatter.