Recetas de personalización habituales

Última actualización: 13 sept 2026 / Especificación Oficial de Arquitectura EpoCanvas

Esta página organiza las necesidades de personalización más habituales en un manual de consulta rápida donde basta con seguir los pasos. En cada receta se indica la ubicación exacta del cambio, hasta el archivo concreto; antes de empezar se recomienda conocer las reglas de renderizado y el sistema de componentes, lo que te ahorrará desvíos.

Receta 1: añadir un documento

Crea un archivo .md en src/content/docs/canvas/ (nómbralo en minúsculas y con guiones, por ejemplo user-guide.md);

Escribe el Frontmatter al inicio del archivo:

---
title: Guía del usuario
description: Una frase que resuma el contenido de la página; se muestra en los resultados de búsqueda y en las tarjetas para compartir.
---

Abre astro.config.mjs y registra el documento en el grupo correspondiente del array sidebar:
```
{ label: 'Guía del usuario', link: '/canvas/user-guide/' }
```
Guarda, comprueba en la vista previa local que aparece en el directorio de la izquierda, y después ejecuta pnpm run deploy para publicar.

Si creas el archivo sin registrarlo en la sidebar, la página es accesible pero no aparece en el directorio de la izquierda; es el error más habitual entre los principiantes.

Receta 2: añadir un botón de navegación superior

Abre src/config/navigation.ts y añade una entrada al array navigationConfig:

{
  id: 'blog',
  labelKey: 'nav.blog',
  defaultLabel: 'Blog',
  href: 'https://blog.epocanvas.com',
  isExternal: true,          // los enlaces externos se abren en una ventana nueva
},

Abre src/utils/i18n.ts y añade las entradas de traducción de nav.blog para los 10 idiomas;
Tras guardar, el nuevo botón aparece de inmediato en la barra superior; si es un enlace interno y debe participar en el resaltado de la navegación, configúrale una función match.

Receta 3: ajustar las reglas de resaltado de la página

Si un cambio en la ruta de la página provoca un resaltado incorrecto en la barra superior, modifica la función match de la entrada correspondiente en navigation.ts:

match: (pathname: string) =>
  pathname === '/canvas/' || pathname.includes('layout'),

La regla es que la coincidencia exacta tiene prioridad y includes actúa como fallback; los match de varios botones no deben solaparse, de lo contrario dos botones aparecerán resaltados a la vez.

Receta 4: cambiar el color de marca del theme

Abre src/styles/custom.css;

Modifica a la vez el trío de colores principales en los dos bloques, el claro (:root) y el oscuro (:root[data-theme='dark']):

--sl-color-accent: #10b981;      /* color principal: botones, estado seleccionado */
--sl-color-accent-low: rgba(16, 185, 129, 0.1);  /* fondo claro del elemento seleccionado */
--sl-color-accent-high: #047857; /* enlaces y texto resaltado */

Tras guardar, los botones, los resaltados y los enlaces de todo el sitio cambian de color automáticamente. Si solo cambia uno de los bloques, los colores quedarán descoordinados en el otro theme.

Receta 5: reemplazar el logo

Ubicación	Archivo	Uso
Izquierda de la barra superior	`public/images/logo.svg`	Icono de la barra superior en las páginas interiores; la ruta se configura en `logo.src` de `astro.config.mjs`
Imagen grande de la portada	`src/assets/logo.svg`	Imagen decorativa de la parte derecha de la página de inicio

Se recomienda reemplazar ambas a la vez. El logo usa formato vectorial SVG; establecer logo.replacesTitle en true en astro.config.mjs oculta el texto del título y deja solo el icono.

Receta 6: ajustar las dimensiones del layout

Los tres elementos del layout están centralizados al inicio de src/styles/custom.css:

:root {
  --sl-sidebar-width: 16.5rem;  /* ancho del directorio de la izquierda */
  --sl-content-width: 60rem;    /* ancho máximo del cuerpo del texto */
  --sl-nav-height: 3.5rem;      /* altura de la barra superior */
}

Receta 7: modificar los textos del cuadro de búsqueda

El placeholder del cuadro de búsqueda, las ayudas de los botones y demás textos de la interfaz provienen del diccionario multilingüe de src/utils/i18n.ts. Abre ese archivo y modifica las entradas como search.placeholder siguiendo la estructura de dos niveles “idioma → clave de entrada”:

export const UI_TRANSLATIONS = {
  'zh-CN': {
    'search.placeholder': '搜索文档与指令...',
    // ...resto de entradas de este idioma
  },
  en: {
    'search.placeholder': 'Search documentation...',
    // ...resto de entradas de este idioma
  },
  // los 8 idiomas restantes siguen el mismo esquema
};

Los idiomas que no se actualicen mostrarán automáticamente el valor predeterminado en chino como fallback, sin errores. Tras guardar, la actualización en caliente local lo muestra de inmediato; no hace falta compilar.

Receta 8: añadir etiquetas `<head>` de verificación al sitio

Para conectar servicios como Google Search Console o Baidu Webmaster Tools hay que inyectar etiquetas de verificación en el <head>. Abre astro.config.mjs y añade al array head de la configuración de Starlight:

head: [
  // configuración del favicon existente ...
  {
    tag: 'meta',
    attrs: {
      name: 'google-site-verification',
      content: 'cadena de verificación',
    },
  },
],

Tras guardar y volver a desplegar, realiza la comprobación con el botón de verificación que aporta cada plataforma. Para más configuración de motores de búsqueda después de publicar, ver SEO y optimización del rendimiento.

Flujo de verificación general tras cualquier cambio

Sea cual sea la personalización, verifica en este orden antes de confirmar:

pnpm run dev      # 1. revisar el resultado página por página en el navegador
pnpm exec astro check && pnpm run build   # 2. comprobación de tipos + compilación completa
pnpm run preview  # 3. previsualizar el resultado de la compilación y publicar solo si todo es correcto

Las formas de publicación se detallan en Despliegue en Cloudflare Pages.