Optimización SEO

Optimiza tu documentación para buscadores y previews sociales configurando títulos, descripciones y metadatos en el frontmatter.

Lo que Jamdesk hace automáticamente

Cómo optimizar tu contenido

Escribe un frontmatter efectivo

---
title: User Authentication    # Under 60 characters
description: Set up OAuth, JWT, and session-based authentication  # 120-160 characters
---

Títulos de página

• Manténlos por debajo de 60 caracteres, contando el nombre del sitio que añade el formato del título, para evitar truncamientos en los resultados de búsqueda
• Incluye tu palabra clave principal cerca del inicio
• Haz que cada título sea único en toda tu documentación

De forma predeterminada, el título de la pestaña del navegador y de los resultados de búsqueda es Título de la página — Nombre del sitio. Para cambiarlo, define seo.titleTemplate en docs.json. Coloca %s donde debe ir el título de la página:

{
  "seo": {
    "titleTemplate": "%s | Acme"
  }
}

Una página con el título Getting started muestra entonces Getting started | Acme. Usa "%s" solo para omitir el nombre del sitio. Si la plantilla no incluye %s, la compilación falla y jamdesk validate muestra el error. Las vistas previas de enlaces (og:title y twitter:title) siguen mostrando solo el título de la página.

Hay dos tipos de páginas que no usan la plantilla. Una página sin title muestra tu name seguido de "Documentation", por ejemplo Acme Documentation, o solo tu name si ya termina en "Docs" o "Documentation". Una página cuyo título es igual a tu name muestra ese título solo.

jamdesk validate y jamdesk dev aceptan seo.titleTemplate desde la versión 1.1.220 de la CLI. Actualiza con npm i -g jamdesk@latest.

Descripciones

• Apunta a 120-160 caracteres
• Resume lo que el lector aprenderá
• Incluye palabras clave relevantes de forma natural

Control de la indexación

Configuración global del sitio

En tu docs.json, configura el comportamiento predeterminado de los robots:

{
  "seo": {
    "metatags": {
      "robots": "index, follow"
    }
  }
}

Control por página

Anula la indexación para páginas específicas en el frontmatter:

---
title: Internal Notes
noindex: true
---

Usa noindex para:

• Páginas en borrador o en progreso
• Documentación interna
• Contenido obsoleto que conservas como referencia

Indexación en buscadores frente a ingesta por IA

Los metadatos robots y noindex controlan los buscadores: si una página aparece en Google y en tu sitemap.xml. No afectan a los archivos llms.txt y llms-full.txt que leen las herramientas de IA. Para dejar de publicarlos, establece seo.ai.llmsTxt en false (consulta Desactivar llms.txt). Los dos controles son independientes: una página puede estar indexada por buscadores pero excluida de la ingesta por IA, o al revés.

URLs canónicas

Si tu documentación es accesible desde varias URLs, establece una canónica:

---
title: Getting Started
canonical: https://docs.example.com/getting-started
---

También puedes establecer una base canónica global del sitio en docs.json. Jamdesk añade la ruta de cada página a esta base, de modo que cada página obtiene una canónica correcta:

{
  "seo": {
    "metatags": {
      "canonical": "https://docs.acme.com"
    }
  }
}

Previews sociales y Open Graph

Jamdesk genera automáticamente una tarjeta social de marca de 1200×630 para cada página. Anula cualquier etiqueta social en el frontmatter. Puedes usar claves planas de nivel superior o un bloque anidado seo:. Ambos funcionan, y cuando la misma clave se define de las dos formas, el valor plano de nivel superior prevalece.

---
title: API Reference
description: REST API endpoints and authentication
"og:title": API Reference — Acme
"og:description": Everything you need to call the Acme API
"og:image": /images/api-social-card.png
"twitter:card": summary_large_image
"twitter:creator": "@acme"
keywords: ["api", "rest", "authentication"]
canonical: https://docs.acme.com/api-reference
---

Etiquetas admitidas

Tipo de tarjeta de Twitter / X

La etiqueta twitter:card controla qué diseño usa X (y otras plataformas) cuando se comparte tu enlace:

Para una tarjeta de marca de 1200×630, usa summary_large_image para que la imagen se muestre a todo lo ancho.

Imagen predeterminada del sitio

Establece una imagen social de reserva para todas las páginas en docs.json. Cualquier página que establezca su propio og:image la anula:

{
  "seo": {
    "metatags": {
      "og:image": "https://docs.acme.com/images/default-card.png"
    }
  }
}

Personaliza la tarjeta social

Tu tarjeta generada conserva su aspecto actual a menos que añadas seo.socialCard a docs.json. Establece solo las claves que quieras cambiar:

{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true,
      "accentBar": false,
      "siteName": false,
      "customImage": "replace"
    }
  }
}

La tarjeta solo puede dibujar logos SVG, PNG y JPG. Jamdesk convierte a WebP los archivos de logo PNG y JPG de tu repositorio cuando compila tu sitio, por lo que la tarjeta suele mostrar tu favicon en su lugar y conserva el nombre del sitio, incluso con siteName: false. Usa un logo SVG para mostrar tu logo completo en la tarjeta, y logo.dark en una tarjeta oscura.

La tarjeta no puede dibujar el texto dentro de un logo SVG, así que el texto sale en blanco. Para solucionarlo, convierte el texto en contornos (trazados) en tu herramienta de diseño y exporta el SVG de nuevo. En Figma, selecciona el texto y usa Flatten. En Illustrator, usa Type > Create Outlines. Tu compilación muestra una sugerencia cuando encuentra texto en el logo SVG que usa la tarjeta. Los logos indicados con una URL completa (https://...) no se revisan.

Si tu color de marca no destaca lo suficiente contra la tarjeta, el texto de la insignia usa en su lugar el color de texto normal. La barra conserva tu color de marca, salvo que ese color se parezca casi por completo al fondo de la tarjeta. En ese caso, la barra es gris.

De forma predeterminada, Jamdesk dibuja el título de la página sobre tu og:image. Si tu imagen ya tiene su propio texto o diseño, establece "customImage": "replace" para mostrarla tal cual.

Cuando tu og:image es el fondo de la tarjeta, elige el theme que coincida con ella: dark para una imagen oscura, light para una clara.

En el modo replace, Jamdesk no dibuja ningún título sobre la imagen. Si seo.metatags establece og:image, todas las páginas usan esa imagen, y una página que establece su propia og:image usa esa en su lugar. Solo las páginas sin ninguna de las dos obtienen una tarjeta generada. Usa un PNG o JPG de 1200×630. Algunas plataformas no muestran imágenes WebP ni SVG.

Las redes sociales almacenan en caché las previews de enlaces, por lo que un enlace que ya se compartió puede conservar la tarjeta anterior durante un tiempo después de que cambies estos ajustes. Comprueba la nueva tarjeta con la herramienta OpenGraph Preview.

Sitemap y Robots.txt

Cada sitio de Jamdesk genera sitemap.xml y robots.txt automáticamente en cada build.

Dónde encontrarlos

Las URLs dependen de si tu documentación está en un dominio raíz o bajo una subruta /docs:

https://docs.acme.com/sitemap.xml
https://docs.acme.com/robots.txt

Qué se incluye en el sitemap

• Todas las páginas publicadas (excluyendo las que tienen noindex o hidden en el frontmatter)
• Fechas de última modificación del frontmatter cuando estén disponibles
• Frecuencia de cambio semanal

Excluir páginas del sitemap

Añade noindex al frontmatter para excluir una página tanto del sitemap como de los buscadores:

---
title: Internal Notes
noindex: true
---

Las páginas con hidden: true también se excluyen automáticamente.

Datos estructurados JSON-LD

Cada página incluye automáticamente datos estructurados de schema.org como una etiqueta <script type="application/ld+json"> con dos esquemas:

• WebSite: el nombre, la URL y la descripción de tu sitio (desde docs.json).
• BreadcrumbList: la ruta de navegación desde Home hasta la página actual, derivada de tu configuración de navigation.

No se necesita configuración. Los buscadores usan esto para resultados enriquecidos, como rutas de navegación en los listados de búsqueda.

IndexNow

Después de cada build, Jamdesk envía automáticamente las URLs de páginas modificadas a IndexNow para una indexación más rápida en los buscadores. Esto notifica a Bing, Yandex y otros buscadores participantes sobre los cambios en tu contenido sin esperar a su próximo ciclo de rastreo.

• Se activa después de cada build exitoso
• Solo envía páginas que realmente cambiaron
• No bloqueante, así que nunca retrasa tu build
• No requiere configuración

Buenas prácticas

Repasa esta lista de verificación antes de publicar:

Artículos relacionados