Shortcodes de navegación de documentación
Tres shortcodes construyen la experiencia de lectura del sitio de documentación: el menú del producto, el índice de la página y la llamada a la acción del producto.
Están pensados para la plantilla del artículo de documentación, junto al contenido del artículo. Colócalos en una plantilla o en un campo del constructor que procese shortcodes de WordPress.
Qué tienen en común
- No muestran nada cuando no pueden resolver qué mostrar, por lo que es seguro dejarlos en una plantilla que también muestre documentos sin categorías.
- No incluyen CSS propio. La navegación reutiliza el marcado de acordeón del tema y el índice de la página reutiliza las clases de navegación del tema, de modo que ambos heredan los estilos del sitio y pueden refinarse desde la hoja de estilos del sitio.
- Determinan en qué producto se encuentran a partir del documento que se está leyendo: la categoría de documentación más profunda asignada a él, y el ancestro superior de esa categoría, que es el producto.
Por tanto, un documento asignado solo a una subcategoría profunda sigue resolviéndose correctamente a su producto.
[pom_docs_nav]
El menú de documentación del producto actual: todas las categorías por debajo del producto, de forma recursiva, con los documentos publicados de cada una.
Su comportamiento:
- Las categorías son paneles plegables, no enlaces.
- Los documentos son enlaces, y el que se está leyendo se marca como la página actual.
- Las categorías que conducen al documento actual se muestran expandidas; el resto comienzan plegadas.
- Los demás productos nunca aparecen.
- Las categorías sin ningún documento publicado por debajo en ningún nivel se omiten.
- Un documento en varias categorías se lista una sola vez, bajo la más profunda.
- El orden sigue el orden de categorías utilizado por la biblioteca de Docs, y después el orden propio de cada documento, y después su título.
- Los documentos asignados directamente a la raíz del producto aparecen antes que sus subcategorías.
Los paneles utilizan el marcado de acordeón del tema, incluidos sus iconos plegado y expandido, por lo que se comportan exactamente igual que cualquier otro acordeón del sitio.
| Atributo | Predeterminado | Descripción |
|---|---|---|
el_class |
vacío | Clases adicionales para el elemento de navegación |
[pom_docs_toc]
Un índice «En esta página» del artículo que se está leyendo, que resalta la sección actual a medida que el lector se desplaza.
La lista se construye en el navegador a partir del artículo renderizado, porque los cuerpos de documentación provienen tanto de Markdown sincronizado como del constructor de páginas. A los encabezados sin ancla se les asigna una derivada de su texto; las anclas existentes se conservan, y los niveles de los encabezados se anidan.
El índice permanece oculto hasta que tiene entradas, de modo que un artículo sin encabezados no muestra nada. Su presentación predeterminada está orientada al escritorio y se oculta en los puntos de interrupción responsive más pequeños; el artículo principal sigue disponible en todos los dispositivos.
| Atributo | Predeterminado | Descripción |
|---|---|---|
el_class |
vacío | Clases adicionales para el elemento de navegación |
content |
#content .doc-content |
Selector del elemento que contiene el artículo |
headings |
h2, h3 |
Qué encabezados indexar |
offset |
100 |
Desplazamiento del scroll en píxeles, para dejar libre una cabecera fija |
title |
On this page |
Encabezado mostrado encima de la lista |
Cambia offset si tu cabecera se superpone a la sección resaltada, y headings si tus artículos utilizan una estructura distinta.
[pom_docs_cta]
La llamada a la acción del producto para la rama de documentación que se está leyendo: un enlace a la página del producto, un enlace a su página de compra y un enlace a su registro de cambios.
Los destinos se declaran por producto y son traducibles junto con sus etiquetas, de modo que cada idioma apunta a sus propias páginas. Un producto sin destinos declarados no muestra nada, que es lo que verás en un producto nuevo hasta que se añadan sus enlaces.
| Atributo | Predeterminado | Descripción |
|---|---|---|
el_class |
vacío | Clases adicionales para el contenedor |
Cómo incluirlos en una plantilla
Un diseño de documentación típico utiliza los tres: la navegación en una barra lateral, el índice junto al artículo y la llamada a la acción al final del contenido o debajo de la navegación.
Como cada uno no muestra nada cuando no tiene nada que mostrar, una sola plantilla sirve para cada producto y cada artículo.
Verificación
- Abre un artículo publicado en una parte profunda de la estructura de un producto en el sitio de documentación.
- Comprueba que la navegación muestra solo ese producto, expandida hasta el documento actual.
- Comprueba que el documento actual está marcado como actual.
- Comprueba que el índice de la página lista los encabezados del artículo y sigue tu desplazamiento.
- Comprueba que la llamada a la acción apunta al producto correcto.
- Abre un artículo sin encabezados y comprueba que el índice está ausente en lugar de vacío.
Solución de problemas
- Un shortcode no muestra nada: confirma que estás en el sitio de documentación, que el documento tiene una categoría de producto asignada y que existe la correspondencia de producto relevante.
- Un documento aparece en una rama inesperada: revisa todas las categorías asignadas; la navegación elige la asignación más profunda.
- La rama actual no se expande: confirma que el documento actual está publicado e incluido por debajo de la raíz del producto resuelta.
- El índice de la página está vacío: confirma que el selector
contentcoincide con el artículo renderizado y que el artículo contiene encabezados seleccionados porheadings. - Un encabezado queda oculto bajo la cabecera fija: aumenta
offset. - La llamada a la acción está ausente: puede que el producto aún no haya declarado destinos de página de inicio, compra y registro de cambios.
Limitaciones
La navegación y la llamada a la acción dependen de la estructura de categorías del sitio de documentación y de las correspondencias de producto admitidas. No son menús de propósito general para sitios o tipos de contenido arbitrarios.