Sistema de Documentación
MuseDock incluye un sistema de documentación integrado que permite a cualquier tenant crear páginas de docs con navegación lateral, tabla de contenidos automática y layout profesional, sin necesidad de plugins ni herramientas externas.
Cómo funciona
El sistema se basa en el mismo modelo de posts del blog, pero con un tipo de contenido diferenciado (post_type=docs). Cuando un post tiene este tipo, MuseDock lo renderiza automáticamente con la plantilla de documentación en vez de la de blog.
La separación es completa: los docs no aparecen en el listado del blog, y los posts de blog no aparecen en la sección de docs. Cada tipo usa su propio prefijo de URL (/blog/ para posts, /docs/ para documentación) y su propia plantilla visual.
Crear la estructura de categorías
Antes de crear contenido, necesitas organizar las secciones de tu documentación. Ve a Blog > Categorías y crea una categoría padre llamada "Docs" con las subcategorías que necesites.
Por ejemplo, para documentar un producto SaaS podrías crear:
Docs
├── Getting Started
├── Configuration
├── API Reference
├── Integrations
└── Troubleshooting
Cada subcategoría se convierte en una sección del sidebar de navegación. El campo sort_order de cada categoría controla el orden en que aparecen.
Crear un post de documentación
Ve a Blog > Posts > Crear y selecciona el tipo "Documentación". Al hacerlo, el selector de categorías mostrará únicamente las categorías hijas de "Docs". Si seleccionas tipo "Post", verás las demás categorías.
Rellena el post como cualquier otro:
- Título: el nombre de la página de docs (por ejemplo, "Instalación").
- Categoría: la sección donde aparecerá (por ejemplo, "Getting Started").
- Slug: se genera automáticamente desde el título. La URL final será
/docs/tu-slug. - Contenido: escribe normalmente usando el editor.
El prefijo /docs/ se asigna automáticamente. No tienes que configurar nada manualmente.
Escribir contenido para docs
Usar headings para la tabla de contenidos
La tabla de contenidos (TOC) del sidebar derecho se genera automáticamente a partir de los H2 y H3 del contenido. Los H2 son secciones principales y los H3 aparecen indentados debajo de su H2 padre.
Estructura recomendada:
## Requisitos previos ← aparece como sección principal en el TOC
### PHP ← aparece indentado bajo "Requisitos previos"
### PostgreSQL ← aparece indentado bajo "Requisitos previos"
## Instalación ← nueva sección principal en el TOC
### Clonar el repositorio ← indentado bajo "Instalación"
### Configurar .env ← indentado bajo "Instalación"
No uses H1 en el contenido — el título del post ya es el H1 de la página.
Botón TOC en el editor
El editor TinyMCE incluye un botón "Insertar Tabla de Contenidos" en la toolbar (icono de lista numerada). Al pulsarlo:
- Escanea todos los H2 y H3 del contenido.
- Genera IDs automáticos en cada heading basados en el texto.
- Inserta un bloque visual al principio del contenido con enlaces a cada sección.
- Los H3 aparecen indentados respecto a los H2.
Este TOC insertado en el contenido es opcional y complementario al TOC automático del sidebar derecho. Es útil si quieres que los lectores vean el índice antes de hacer scroll.
Code blocks
Los bloques de código se renderizan con fondo oscuro y un botón "Copiar" en la esquina superior derecha. Usa la sintaxis estándar de markdown o el formateador de código del editor.
Blockquotes como callouts
Los blockquotes se renderizan como callouts con borde azul, útiles para notas, advertencias o información destacada.
Esto es un ejemplo de callout. Úsalo para información importante que el lector no debería pasar por alto.
Tablas
Las tablas se renderizan con el estilo de documentación: bordes sutiles, header destacado y ancho completo. Útil para tablas de referencia de parámetros, claves de configuración o comparativas.
Lo que se genera automáticamente
Al publicar un post de tipo documentación, la página incluye:
Sidebar izquierdo con la navegación jerárquica por secciones (subcategorías de Docs). Incluye acordeón desplegable, búsqueda rápida dentro de los docs, y highlight de la página actual.
Tabla de contenidos en el sidebar derecho, generada desde los H2/H3 del contenido, con scroll-spy que marca la sección visible mientras el usuario hace scroll.
Breadcrumbs con la ruta completa: Home > Docs > Sección > Página actual.
Navegación Prev/Next en la parte inferior de la página para moverse entre páginas de docs en orden.
Layout limpio: sin fecha de publicación, sin nombre de autor, sin tags. El aspecto es de documentación técnica, no de blog.
Página índice
Al visitar /docs/ sin slug, se muestra una landing page con un grid de cards — una por cada sección (categoría), mostrando el nombre de la sección, su descripción y la lista de artículos que contiene. Cada card enlaza directamente al primer artículo de la sección.
Redirects automáticos
Si alguien accede a /blog/slug-de-un-doc, el sistema detecta que ese slug pertenece a un post de tipo docs y redirige automáticamente con un 301 a /docs/slug-de-un-doc. Esto previene URLs duplicadas y consolida el SEO.
Responsive
En escritorio, la página de docs muestra tres columnas: sidebar de navegación a la izquierda, contenido en el centro y TOC a la derecha.
En móvil, el sidebar colapsa en la parte superior como un desplegable y el TOC se oculta para priorizar el contenido.
Disponibilidad para tenants
El sistema de documentación está disponible para cualquier tenant. No requiere activación ni configuración especial. Cualquier tenant que necesite documentar sus servicios, productos o API puede crear posts de tipo documentación y tendrá automáticamente el sistema completo con sidebar, TOC, breadcrumbs y navegación.
Casos de uso típicos: documentación de un SaaS, guías de usuario de un servicio, documentación interna de una empresa, base de conocimiento para soporte técnico, o manuales de productos.