Definition Box: Formato, Reglas y Ejemplos

Un definition box proporciona al término principal de la página una explicación exacta y delimitada antes de que el artículo lo desarrolle. Es un elemento de apertura: un componente de contenido reutilizable que aparece cerca del inicio porque el lector no debería tener que inferir el término central a partir de ejemplos, beneficios o antecedentes.

Ese ejemplo en vivo es el elemento completo, no un adelanto de una definición más abajo en la página. Su título es opcional; su cuerpo no lo es. El contrato de producción a continuación determina cuándo pertenece el elemento, qué significa cada campo y cómo se mapea el mismo contenido entre los sistemas de publicación.

Por qué es importante este elemento

Los lectores rara vez comienzan una página informativa leyendo cada palabra en orden. Escanean el título, las líneas iniciales, los encabezados y los bloques visualmente distintivos para decidir si la página responde a su pregunta. Una definición enterrada en un párrafo introductorio obliga al lector a separar la respuesta del contexto, las afirmaciones y la ambientación. El recuadro elimina ese trabajo: su límite dice “esta es la definición”.

Ese límite también le da a la definición una posición estable y direccionable. Los editores saben dónde revisarla, las plantillas saben dónde renderizarla, y las revisiones futuras no obligan al lector ni a una verificación de calidad a buscar en varios párrafos de apertura. La ubicación coherente es importante en toda una biblioteca porque la misma función informativa no debería moverse de forma impredecible de una página a otra.

La extraíbilidad automatizada es la capacidad del software de aislar una unidad de contenido sin perder su significado. Una definición tipificada con un título y un cuerpo puede ser indexada, comparada, citada o transformada de forma independiente. Una oración que simplemente define un término dentro de texto libre se disuelve en la prosa circundante: el software debe adivinar dónde comienza la definición, dónde termina y si la afirmación precedente es parte de ella. Sigue las reglas de escritura de elementos para que la identidad semántica sobreviva incluso cuando el diseño visual cambie.

El texto debe funcionar igualmente sin el recuadro. El estilo crea contraste para las personas; un sujeto, verbo y significado distintivo autocontenidos crean extraíbilidad para las máquinas. “Es un método para mejorarlos” falla cuando se saca de su párrafo. “La poda de contenido es el proceso de eliminar, consolidar o actualizar páginas que ya no cumplen un propósito útil de búsqueda o negocio” sobrevive.

Cuándo usarlo

Usa un definition box cuando la página está organizada en torno a un término y ese término puede definirse con precisión en una declaración breve. Es obligatorio para los formatos de término de glosario y qué-es-X. También es obligatorio para contenido de diagnóstico o condición: el lector debe saber qué es la condición nombrada antes de considerar causas, pruebas o remedios.

Las páginas centradas en síntomas y las guías prácticas usan el elemento raramente. Agrégado solo cuando una definición breve resuelva una ambigüedad genuina necesaria para la tarea. Por ejemplo, una guía titulada “Cómo solucionar la canibalización de palabras clave” puede definir la canibalización de palabras clave antes de los pasos porque el diagnóstico controla qué solución se aplica. Una guía titulada “Cómo cambiar una etiqueta de título” no necesita un recuadro que defina una etiqueta de título si la audiencia y la instrucción inicial ya hacen que el objeto sea inequívoco.

No uses un definition box para:

• Una introducción amplia, historia, declaración de beneficios o explicación de por qué el tema es importante. Esos pasajes desarrollan el artículo; no definen el término.
• Un resumen de la página. Un resumen recoge varias conclusiones, mientras que una definición expresa el significado de un término.
• Una promesa de producto como “AmICited es la forma más fácil de mejorar la visibilidad”. Eso es posicionamiento, no una definición comprobable.
• Una advertencia, salvedad, requisito previo o consejo. Su función comunicativa difiere incluso cuando un tema podría hacer que parezca el mismo panel coloreado.
• Un término secundario introducido a mitad del artículo. Define ese término en la oración donde aparece por primera vez, o asígnale su propia página cuando merezca un tratamiento sostenido.
• Una cita cuya autoridad sustituye a la claridad. Atribuye una definición formal en la prosa circundante cuando la atribución sea necesaria; mantén el recuadro legible como una declaración directa.

El error común por aproximación es una “introducción a la definición”: “La rotación de clientes es uno de los conceptos más importantes para los negocios de suscripción, y entenderlo puede transformar el crecimiento”. Esto dice que el concepto es importante pero nunca dice qué es. El recuadro no puede hacer que una ambientación vacía sea precisa.

Dónde colocarlo

La ubicación codifica la prioridad. Coloca el definition box inmediatamente después del párrafo introductorio o la introducción breve, como el primer bloque de contenido. La introducción establece por qué el lector está en la página; el recuadro fija entonces el significado antes de que causas, ejemplos, beneficios, pasos o comparaciones dependan de él.

No coloques navegación, tabla de contenidos, conclusiones clave, galería de imágenes ni una llamada a la acción promocional entre la introducción y la definición. Estos bloques obligan al lector a atravesar material no relacionado antes de recibir el significado del término. Las migas de pan y el héroe de la página son parte de la plantilla, no contenido creado, por lo que pueden preceder a la introducción.

Usa un definition box por página. La regla existe porque el componente identifica el objeto definicional principal de la página. Dos recuadros crean dos términos principales en competencia y hacen que la extracción sea ambigua. Si ambos términos son genuinamente principales, divide el tema en dos páginas y conéctalos en prosa. Si el segundo término es subordinado, defínelo en línea en lugar de darle formato de segunda respuesta canónica.

Un bloque de respuesta directa puede coexistir con una definición solo cuando responde una pregunta principal diferente. En una página de diagnóstico, la definición puede indicar qué es la condición mientras que la respuesta directa indica la primera acción recomendada. Cuando la pregunta principal de la página es “¿Qué es X?”, la respuesta directa y la definición son la misma respuesta. Fúndelas en un solo definition box; versiones adyacentes simplemente repiten el texto y compiten por la extracción.

Anatomía

El elemento tiene dos regiones de autoría y una relación estructural. La captura de pantalla debe mostrar el elemento renderizado sin incluir texto explicativo en la imagen; la leyenda a continuación permanece seleccionable, accesible y mantenible cuando el diseño cambie.

Leyenda renderizada

1. Título opcional: Generalmente “¿Qué es X?”. Identifica el término exacto y no debe agregar una segunda afirmación.
2. Cuerpo obligatorio: Una definición autónoma que nombra el término, lo sitúa en una categoría útil y establece qué lo distingue.
3. Posición de apertura: El recuadro sigue a la introducción y precede a la primera sección explicativa. Esta relación es parte del contrato aunque no sea un campo.

El borde, fondo, relleno, tratamiento de iconos y tipografía pertenecen al renderizador. Los autores aportan significado, no tokens visuales. El elemento debe seguir siendo comprensible si se elimina todo estilo decorativo.

Ejemplos de diseño

La galería cubre las variantes de contenido admitidas, no inventa diferentes tipos semánticos. Cada captura debería reutilizar la misma definición cuando sea posible para que los revisores puedan evaluar el manejo del título, el ajuste del cuerpo y el comportamiento en el viewport en lugar de comparar texto no relacionado.

Con título: La variante preferida cuando el término es desconocido, ambiguo, abreviado o diferente del título exacto de la página.

Sin título: Permitido cuando el encabezado de la página y la introducción inmediatamente anterior hacen que el tema sea inconfundible. El cuerpo debe seguir nombrando el término; la omisión del título nunca permite que pronombres como “este” reemplacen al sujeto.

Longitud máxima: El renderizador ajusta el cuerpo completo. No debe truncar, colapsar, desplazar ni reducir la fuente para adaptarse al texto en el máximo editorial.

Viewport estrecho: El título y el cuerpo mantienen su orden, una longitud de línea legible y un límite visible. Ningún significado debe depender de un icono que se mueva junto al texto.

Parámetros

Los parámetros separan el contenido de la presentación. Sus límites mantienen las definiciones comparables entre páginas y evitan que el componente se convierta en una nota informativa de uso general.

Parámetros del definition box

El renderizador puede derivar el término para la indexación, pero los autores nunca deben escribir un cuerpo que dependa de que ese campo derivado se muestre. Una definición copiada debe nombrar su sujeto explícitamente.

Sintaxis y ejemplos de código

Las tres formas llevan el mismo título y cuerpo. La directiva portátil de Markdown es la forma canónica de autoría; Hugo y WordPress son adaptadores. Los ejemplos usan deliberadamente el mismo texto para que una prueba de migración pueda comparar valores, no solo la apariencia.

Directiva portátil de Markdown

:::definition
## ¿Qué es la poda de contenido?

La poda de contenido es el proceso de eliminar, consolidar o actualizar páginas que ya no cumplen un propósito útil de búsqueda o negocio.
:::

El primer encabezado se asigna a title; todo lo que le sigue se asigna a body. Omite el encabezado para la variante sin título, pero mantén el término en el cuerpo.

Shortcode de Hugo

{{< callout type="note" title="¿Qué es la poda de contenido?" >}}La poda de contenido es el proceso de eliminar, consolidar o actualizar páginas que ya no cumplen un propósito útil de búsqueda o negocio.{{< /callout >}}

El sitio reutiliza el renderizador de callout existente para el tratamiento visible de Hugo. El contrato de definición aún proviene de la fuente portátil tipificada: note es aquí un adaptador de renderizado, no un permiso para poner notas ordinarias en definition boxes.

Bloque o shortcode de WordPress

[definition title="¿Qué es la poda de contenido?"]La poda de contenido es el proceso de eliminar, consolidar o actualizar páginas que ya no cumplen un propósito útil de búsqueda o negocio.[/definition]

Una implementación de WordPress puede exponer los mismos campos como un bloque personalizado. Los valores almacenados siguen siendo title y body; los controles del editor, colores y espaciado son ajustes de presentación y no deben alterar el significado de la definición.

Ejemplos

Esto es bueno porque nombra el término, identifica la condición y establece la consecuencia distintiva. No afirma que cada par de páginas que comparten una palabra compita; la frase “misma intención de búsqueda” proporciona el límite necesario. El cuerpo es útil sin el título y suficientemente breve para citarlo completo.

Esto es malo porque nunca define la canibalización de palabras clave. Ofrece importancia, audiencia, urgencia y un efecto vago, pero ninguna categoría ni condición distintiva. Reemplazar “uno de los más importantes” con “una situación en la que varias páginas compiten por la misma intención de búsqueda” convierte la promoción en significado.

Un segundo patrón erróneo es sobrecargar el recuadro: una definición seguida de causas, cinco ejemplos, una advertencia y una herramienta recomendada. Incluso si la primera oración es precisa, el material adicional destruye el límite estable. Mantén la definición; traslada las causas y ejemplos a la siguiente sección, la advertencia a su elemento correcto y la recomendación al punto donde el lector pueda actuar sobre ella.

Schema markup y accesibilidad

Un definition box no crea automáticamente una entidad independiente de Schema.org. En un artículo normal, su texto sigue siendo parte del Article o TechArticle que lo contiene. En una página de glosario, una implementación de publicación puede mapear el término y la definición a un vocabulario adecuado solo cuando el sitio ha adoptado esa política de esquema. No inventes un tipo DefinitionBox: no existe en Schema.org.

Del mismo modo, no dupliques el cuerpo en JSON-LD simplemente porque el recuadro parezca importante. Schema markup debe describir la página de manera veraz, y duplicar prosa visible en una propiedad no relacionada crea ruido en lugar de un significado más sólido. Si se completa una propiedad de esquema, su valor debe coincidir con la definición visible en sustancia y actualizarse con ella.

El elemento no necesita ningún rol ARIA interactivo. Renderízalo en el orden normal del documento como una región etiquetada o un contenedor semántico, con el título antes del cuerpo. No uses role="alert", porque una definición estática no es información urgente o recién llegada. No uses color o un icono como la única señal de que el bloque es una definición. Si el título se implementa como un encabezado, su nivel debe seguir la jerarquía de la página; el ## de la fuente es una convención de mapeo de campos, no una instrucción para crear un salto de encabezado inválido.

El comportamiento de teclado es el comportamiento de lectura ordinario: el recuadro en sí mismo no es enfocable. Cualquier enlace en su interior sigue la semántica normal de enlaces y necesita un ancla descriptiva. La salida del lector de pantalla debe preservar el mismo orden título-cuerpo visible en pantalla.

Reglas de escritura

Escribe la definición antes de escribir sus beneficios. Comienza con el término mismo, luego usa un verbo de enlace como “es”, “significa” u “ocurre cuando”. Indica la categoría útil más cercana y la característica que separa el término de conceptos vecinos. Esta secuencia existe porque la categoría sin distinción es amplia, mientras que la distinción sin categoría deja al lector sin saber qué tipo de cosa es el término.

Mantén el cuerpo en un máximo de aproximadamente 300 caracteres, incluidos los espacios. Prefiere una oración. Una segunda oración breve es aceptable solo cuando un límite necesario no puede expresarse con claridad en la primera. El límite es editorial, no una invitación a comprimir puntuación, eliminar artículos o acumular cláusulas. Si la precisión requiere más espacio, pon el núcleo exacto en el recuadro y califícalo inmediatamente después.

Usa un tono neutro y declarativo. Evita “importante”, “poderoso”, “revolucionario”, “debes saber” y juicios similares. Evita definiciones circulares como “la optimización de contenido es el acto de optimizar contenido”. Desarrolla las abreviaturas en el primer uso a menos que la abreviatura sea el término de la página. Usa el mismo nombre canónico que aparece en el título de la página.

Nunca coloques estos elementos dentro del cuerpo:

• Más de un término principal o una lista de términos relacionados.
• Beneficios, historia, causas, síntomas, ejemplos, pasos, propuestas de producto o llamadas a la acción.
• Tablas, imágenes, videos, formularios, botones, notas al pie o callouts anidados.
• Superlativos sin respaldo, estadísticas inventadas o afirmaciones que requieran un párrafo de evidencia.
• Un segundo encabezado, lista con viñetas o cita en bloque.
• Pronombres cuyo significado dependa de la introducción precedente.

Un enlace de atribución es la excepción, no el objetivo. Úsalo solo cuando una definición legal, científica o basada en estándares dependa de una fuente nombrada. Coloca las citas extensas y el desacuerdo entre fuentes en prosa ordinaria, donde el lector pueda ver la calificación en lugar de confundir una redacción controvertida con una definición universal.

Tipos de publicación que lo usan

El frontmatter postTypes registra las uniones registradas. La tabla traduce esas uniones en reglas editoriales. Los formatos de diagnóstico/condición y centrados en síntomas se describen aquí como patrones de uso, pero no están enlazados como tipos de publicación independientes del playbook porque no están en el registro canónico actual.

Requisitos por tipo de publicación

Para páginas de diagnóstico o condición, usa el recuadro siempre y colócalo antes de los síntomas, causas, gravedad o remedios. Para páginas centradas en síntomas, úsalo solo cuando el nombre del síntoma tenga una definición genuinamente breve y estable. Si el recuadro simplemente reformularía el título —“Un sitio web lento es un sitio web que es lento”— omítelo y comienza con el umbral de diagnóstico o el problema observable en prosa.

Lista de verificación de control de calidad

Un revisor verifica el significado antes que la apariencia. Un recuadro pulido que contiene una introducción vaga sigue siendo una definición fallida.

• Un término principal: La página y el recuadro definen exactamente un concepto principal.
• Posición correcta: El recuadro es el primer bloque de contenido creado después de la introducción, sin tabla de contenido, conclusiones, galería o promoción insertada antes de él.
• Una ocurrencia: Ningún segundo definition box compite con la respuesta canónica.
• Definición real: El cuerpo indica qué es el término o cuándo existe la condición; no solo dice por qué el término es importante.
• Texto autónomo: El cuerpo nombra su sujeto y tiene sentido cuando se copia sin la prosa o el estilo cercanos.
• Precisión: La categoría, la característica distintiva y cualquier límite esencial son precisos. La redacción no generaliza en exceso.
• Longitud: El cuerpo no supera los aproximadamente 300 caracteres y se mantiene legible, no comprimido.
• Contenido limpio: No aparecen beneficios, historia, ejemplos, pasos, afirmaciones de producto, medios, tablas o elementos anidados en su interior.
• Decisión de respuesta directa: Si la página pregunta “¿Qué es X?”, el definition box es el único elemento de respuesta directa. Si ambos elementos aparecen, responden preguntas claramente diferentes.
• Semántica accesible: El título precede al cuerpo, el orden de encabezados es válido, el color no es el único identificador y no hay rol de alerta ni objetivo de enfoque innecesario.
• Paridad portátil: Los mapeos de Markdown, Hugo y WordPress conservan el mismo título y definición.
• Restricción de datos estructurados: Cualquier valor de esquema coincide con el texto visible y no se usa ningún tipo inventado de Schema.org.
• Estado de capturas de pantalla: Los comentarios siguen siendo instrucciones de captura no renderizables hasta que los archivos nombrados existan; no se hace referencia a ninguna ruta de imagen inexistente como imagen.

FAQ

La plantilla de academy renderiza las cinco preguntas revisadas almacenadas en el frontmatter [[faq]] de esta página. En conjunto cubren la necesidad, la coexistencia con respuestas directas, enlaces y citas, el límite de longitud y la regla de uno por página.