Introducción

Este artículo ofrece un tutorial completo y detallado para crear un layout de documentación de tutoriales para WordPress usando CSS. El objetivo es diseñar una plantilla clara, accesible y fácil de mantener que contenga: navegación lateral (tabla de contenidos), área de contenido principal con pasos y ejemplos de código, componentes para callouts (nota, aviso, consejo), y paginación de tutoriales. Incluye ejemplos de marcado, CSS y snippets PHP para integrar en un tema o child theme de WordPress.

Resultado final esperado

• Layout con una barra lateral fija/pegajosa para la tabla de contenidos y navegación entre capítulos.
• Área principal enfocada en la lectura con tipografía legible, bloques de código bien formateados y callouts destacados.
• Responsive: en pantallas pequeñas la tabla de contenidos se colapsa o se desplaza arriba.
• Integración con WordPress: plantilla de single para el tipo de contenido tutorial y estilos cargados desde functions.php.

Requisitos y convenciones

1. Conocer lo básico de WordPress (themes, templates, loop).
2. Usar un post type llamado tutorial o adaptar el código a entradas o páginas.
3. Separar CSS en un archivo propio (por ejemplo: /css/tutorial-doc.css) y cargarlo mediante wp_enqueue_style.
4. Usar clases BEM o una convención similar para facilitar mantenimiento y evitar colisiones.

Estructura de archivos recomendada

/wp-content/themes/mi-theme/
  ├─ single-tutorial.php         lt-- plantilla específica para tutorials
  ├─ template-parts/
  │   └─ content-tutorial.php
  ├─ css/
  │   └─ tutorial-doc.css
  └─ functions.php               lt-- registro/enqueue de estilos y scripts

Marcado HTML recomendado (ejemplo mínimo de la estructura del tutorial)

El siguiente es un ejemplo de cómo estructurar el HTML del contenido del tutorial. Este bloque va dentro de la plantilla de WordPress (por ejemplo en content-tutorial.php), sustituyendo contenido dinámico con las funciones de WP.

ltarticle class=tutorial>
  ltheader class=tutorial__header>
    lth1 class=tutorial__title>Título del tutoriallt/h1>
    ltp class=tutorial__meta>Publicado el lttime datetime=2025-09-01>1 Sep 2025lt/time> • Nivel: Intermediolt/p>
  lt/header>

  ltnav class=tutorial__toc> 
    ltul class=toc__list>
      ltli>lta href=#intro>Introducciónlt/a>lt/li>
      ltli>lta href=#paso-1>Paso 1lt/a>lt/li>
      ltli>lta href=#ejemplos>Ejemploslt/a>lt/li>
      ltli>lta href=#conclusiones>Conclusioneslt/a>lt/li>
    lt/ul>
  lt/nav>

  ltsection class=tutorial__content>
    lth2 id=intro>Introducciónlt/h2>
    ltp>Texto del tutorial...lt/p>

    lth3 id=paso-1>Paso 1: Preparar el entornolt/h3>
    ltp>Explicación del paso.lt/p>

    ltdiv class=tutorial__callout tutorial__callout--info>
      ltstrong>Nota:lt/strong> Recomendación importante.
    lt/div>

    lth3 id=ejemplos>Ejemplo de códigolt/h3>
    ltpre class=code>/ bloque de código: se formatea desde CSS o con librería /lt/pre>

    ltnav class=tutorial__pager>
      lta href=/tutorial-anterior class=pager__prev>← Anteriorlt/a>
      lta href=/tutorial-siguiente class=pager__next>Siguiente →lt/a>
    lt/nav>
  lt/section>
lt/article>

CSS: layout principal con Grid / Flex y sidebar pegajoso

Se recomienda usar CSS Grid para el layout principal y position: sticky para mantener la tabla de contenidos visible. El ejemplo muestra un diseño de dos columnas que colapsa a una columna en dispositivos pequeños.

/ Archivo: css/tutorial-doc.css /

/ Variables de ejemplo /
:root{
  --max-width: 1200px
  --gutter: 24px
  --sidebar-width: 300px
  --color-bg: #ffffff
  --color-muted: #6b7280
  --accent: #2563eb
  --callout-bg: #f8fafc
}

/ Contenedor principal /
.tutorial {
  max-width: var(--max-width)
  margin: 0 auto
  padding: var(--gutter)
  color: #111827
  box-sizing: border-box
}

/ Grid: sidebar   contenido /
.tutorial {
  display: grid
  grid-template-columns: 1fr var(--sidebar-width)
  grid-column-gap: var(--gutter)
  align-items: start
}

/ Contenido principal /
.tutorial__content {
  background: var(--color-bg)
  padding: 0
  min-width: 0 / importante para truncado en grid /
}

/ Sidebar / TOC /
.tutorial__toc {
  position: relative
}
.toc__list {
  list-style: none
  padding: 0
  margin: 0
  background: #fbfdff
  border: 1px solid #e6eef8
  border-radius: 6px
  padding: 12px
}

/ Sticky para la TOC: se pega dentro del contenedor del artículo /
.tutorial__toc {
  position: sticky
  top: 20px
  align-self: start
}

/ Tipografía y espaciado /
.tutorial__title { font-size: 2rem margin: 0 0 8px 0 }
.tutorial__meta { color: var(--color-muted) margin-bottom: 16px }

/ Callouts /
.tutorial__callout {
  border-left: 4px solid var(--accent)
  background: var(--callout-bg)
  padding: 12px 16px
  margin: 16px 0
  border-radius: 4px
}
.tutorial__callout--warning { border-color: #f97316 }
.tutorial__callout--info { border-color: var(--accent) }

/ Código:
   Si usas librería de resaltado, aplica estilos al contenedor. Aquí un estilo base. /
pre.code, pre.EnlighterJSRAW {
  background: #0f1724
  color: #e6eef8
  padding: 16px
  overflow: auto
  border-radius: 6px
  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Roboto Mono, monospace
  font-size: 0.95rem
  line-height: 1.5
}

/ Paginación simple /
.tutorial__pager { display:flex justify-content:space-between gap: 12px margin-top: 32px }
.pager__prev, .pager__next {
  color: var(--accent)
  text-decoration: none
}

/ Responsive: colapsar a una sola columna en pantallas pequeñas /
@media (max-width: 900px) {
  .tutorial { grid-template-columns: 1fr }
  .tutorial__toc { order: -1 margin-bottom: 16px position: static } / se coloca encima /
}

Estilado de la tabla de contenidos y navegación

La TOC debe ser legible, con links suficientemente grandes y con enfoque visual para accesibilidad. Se puede añadir un estilo activo al ancla que coincida con el fragmento actual usando JS (o enlaces con clase .active generada por servidor).

.toc__list a {
  display: block
  padding: 8px
  color: #0f1724
  text-decoration: none
  border-radius: 4px
}
.toc__list a:hover, .toc__list a:focus, .toc__list a.active {
  background: rgba(37,99,235,0.08)
  color: var(--accent)
}

Ejemplo de PHP: registrar post type y enqueue del CSS

Registrar un post type para tutoriales y añadir el CSS al theme.

// En functions.php
function mi_theme_registrar_tutorial_cpt() {
  labels = array(
    name => Tutoriales,
    singular_name => Tutorial
  )
  args = array(
    labels => labels,
    public => true,
    has_archive => true,
    supports => array(title,editor,thumbnail,excerpt,revisions),
    show_in_rest => true,
  )
  register_post_type(tutorial, args)
}
add_action(init, mi_theme_registrar_tutorial_cpt)

function mi_theme_enqueue_tutorial_styles() {
  wp_enqueue_style(tutorial-doc, get_stylesheet_directory_uri() . /css/tutorial-doc.css, array(), 1.0)
}
add_action(wp_enqueue_scripts, mi_theme_enqueue_tutorial_styles)

Integración en la plantilla single-tutorial.php

Ejemplo mínimo de single-tutorial.php que carga el template part y muestra contenido.

lt?php
/ single-tutorial.php /
get_header()
if ( have_posts() ) : while ( have_posts() ) : the_post()
  get_template_part(template-parts/content, tutorial)
endwhile endif
get_footer()
?gt

Content template: content-tutorial.php (ejemplo)

lt?php
/ template-parts/content-tutorial.php /
title = get_the_title()
?>
ltarticle class=tutorial>
  ltheader class=tutorial__header>
    lth1 class=tutorial__title>lt?php echo esc_html(title) ?gtlt/h1>
    ltp class=tutorial__meta>Publicado el lt?php echo get_the_date() ?gtlt/p>
  lt/header>

  lt!-- Aquí podrías generar la TOC dinámicamente, por ejemplo parseando los headings del contenido con PHP o JS --gt
  ltnav class=tutorial__toc>lt!-- TOC generado dinámicamente --gtlt/nav>

  ltsection class=tutorial__content>
    lt?php the_content() ?gt
  lt/section>
lt/article>

Generación de la TOC (opciones)

• Generarla en servidor: parsea el contenido con DOMDocument y extrae h2/h3 para construir la lista. Es preciso sanear y asegurar IDs únicos.
• Generarla en cliente: usar JS para recorrer el contenido y detectar headings, insertar la TOC y añadir scrollspy.
• Usar plugins: algunos plugins generan TOC automáticamente a partir de shortcodes o filtros de contenido.

Accesibilidad y SEO

• Asegurar que los enlaces de la TOC son focusables y tienen suficiente contraste.
• Usar elementos semánticos (header, nav, article, section) en el marcado real del tema para favorecer a los lectores de pantalla.
• Marcar fechas y metadatos correctamente con elementos time y atributos datetime.
• Opcional: añadir JSON-LD con datos del tutorial (autor, fecha, descripción). Ejemplo abajo.

{
  @context: https://schema.org,
  @type: Article,
  headline: Título del tutorial,
  author: {
    @type: Person,
    name: Autor
  },
  datePublished: 2025-09-01,
  description: Resumen breve del tutorial
}

Optimización para móviles y rendimiento

1. Evitar cargar librerías de resaltado pesadas si solo usas bloques pequeños usa CSS simple o una librería ligera.
2. Minificar y combinar CSS cuando sea posible para desarrollo mantén separado.
3. Lazy-load de imágenes dentro del contenido (atributo loading=lazy).
4. Probar la experiencia lectora: espaciado, tamaño de fuente y contraste.

Consejos de diseño y microinteracciones

• Resalta el heading activo en la TOC con una pequeña animación o transición de color.
• Ofrece botones para copiar bloques de código (se implementa con JS guarda accesibilidad añadiendo aria-live para confirmación).
• Incluye enlaces Ver en GitHub o Descargar para snippets largos.
• Proporciona un índice de versiones o changelog si actualizas tutoriales frecuentemente.

Ejemplo final rápido: CSS HTML WP (resumen)

Con los bloques anteriores tienes lo esencial: estructura HTML en template-parts, CSS en un archivo en /css y el registro/enqueue en functions.php. Adapta clases y variables a tu sistema de diseño y añade scripts para la TOC dinámica si lo deseas.

Implementa este layout en tu theme o child theme y podrás ofrecer a tus lectores una experiencia de documentación clara, navegable y profesional, optimizada para WordPress y adaptable a distintos niveles de complejidad.