Skill de Markdown para mdsvr

Genera un conjunto completo, válido y de múltiples archivos de documentación Markdown para usar con mdsvr — compatible tanto con el modo servidor como con la exportación estática.

Cuando se active esta skill, genere múltiples archivos .md que formen un sitio de documentación cohesivo, siguiendo estrictamente todas las convenciones de mdsvr.

Paso 1 — Entender la Solicitud

Antes de generar archivos, extraiga de la solicitud del usuario:

Tema / nombre del producto — ¿qué se está documentando?
Público objetivo — desarrolladores, usuarios finales, equipos de operaciones, etc.
Alcance — ¿cuántas páginas/secciones se necesitan?
Idioma — ¿Vietnamita, Inglés o bilingüe?
¿Diagramas necesarios? — si es así, lea references/rules/mermaid.md para las reglas de sintaxis.

Si alguno de estos puntos no está claro, haga UNA pregunta enfocada antes de proceder.

Paso 2 — Planificar la Estructura de Archivos

Diseñe una jerarquía lógica antes de escribir el contenido. Un sitio de documentación típico de mdsvr:

docs/
├── README.md                    ← Página de inicio (obligatorio)
├── 01-getting-started/
│   ├── README.md                ← Índice de sección
│   ├── 01-installation.md
│   ├── 02-quickstart.md
│   └── 03-configuration.md
├── 02-guides/
│   ├── README.md
│   ├── 01-basic-usage.md
│   └── 02-advanced.md
├── 03-api-reference/
│   ├── README.md
│   └── 01-endpoints.md
└── 04-troubleshooting.md

Adapte la estructura al tema del usuario. Escale hacia arriba o hacia abajo según sea necesario.

Paso 3 — Aplicar Reglas de Archivos y Enlaces de mdsvr (OBLIGATORIO)

3.1 Reglas de Nomenclatura de Archivos

Regla	❌ Incorrecto	✅ Correcto
Sin puntos en medio del nombre	`0.1.quickstart.md`	`01-quickstart.md`
Sin puntos en medio del nombre	`config.v2.md`	`config-v2.md`
Usar kebab-case	`GettingStarted.md`	`getting-started.md`
Usar prefijo numérico para orden	`guide.md` (en la barra lateral)	`01-guide.md`
Nombres descriptivos	`page1.md`	`installation.md`
El índice del directorio debe ser	`index.md`	`README.md`

3.2 Reglas de Estructura de Enlaces

Regla	❌ Incorrecto	✅ Correcto
Usar solo rutas relativas	`[Guía](/docs/guide)`	`[Guía](./guia)`
Sin extensión `.md` en enlaces	`[Config](./setup.md)`	`[Config](./config)`
Enlazar al directorio, no al README	`[Inicio](./01-getting-started/README)`	`[Inicio](./01-getting-started)`
Los enlaces con ancla deben coincidir con los encabezados	`[Ver](#install-steps)` (si el encabezado no existe)	Coincidir exactamente

3.3 Reglas de Estructura de Encabezados

Regla	❌ Incorrecto	✅ Correcto
Cada página necesita H1	(la página comienza con H2)	`# Título de la página` como primer encabezado
No saltar niveles de encabezado	H1 → H3	H1 → H2 → H3
Los encabezados deben ser descriptivos	`## Sección 1`	`## Requisitos de Instalación`

Paso 4 — Aplicar Frontmatter a Cada Archivo

Cada archivo .md debe incluir frontmatter YAML para SEO y metadatos de mdsvr:

---
title: "Título de la Página"
description: "Descripción de una oración del contenido de esta página."
---

Paso 5 — Directrices de Contenido

README.md (Página de Inicio) — Obligatorio

Debe existir en la raíz de la carpeta docs.
Incluir: resumen del proyecto, enlaces de navegación rápida a todas las secciones.
Usar un llamado de bienvenida si es apropiado.

README.md de Sección (Índice de Directorio)

Resumir lo que cubre la sección.
Listar todas las páginas de la sección con enlaces relativos.

Páginas de Contenido

Un tema enfocado por página.
Comenzar con un breve párrafo de introducción.
Usar componentes MDX cuando sea apropiado:
- :::note, :::warning, :::tip, :::danger para llamadas de atención.
- Listas numeradas para procedimientos paso a paso.
Enlazar libremente a páginas relacionadas usando rutas relativas.
Terminar con una sección "Próximos Pasos" o "Relacionado" cuando sea útil.

Paso 6 — Diagramas Mermaid (Cuando sea Necesario)

Si la documentación se beneficia de diagramas (arquitectura, flujos, secuencias, ERDs, máquinas de estado, etc.), incruste diagramas Mermaid en línea en los archivos .md relevantes.

Antes de generar cualquier diagrama, lea references/rules/mermaid.md para la referencia completa de sintaxis y reglas de generación. Todas las reglas en ese archivo son obligatorias.

Lista de verificación rápida (de mermaid.md):

Elija el tipo de diagrama más apropiado — NO use flowchart por defecto.
Siempre declare la dirección en los diagramas de flujo: flowchart TD o flowchart LR.
IDs de nodos: solo letras, números, guiones bajos. Sin -, ., (, ).
Las etiquetas de nodos con espacios deben usar comillas dobles: A["Mi Etiqueta"].
Los subgrafos deben tener IDs explícitos: subgraph miid["Etiqueta"].
Diagramas de secuencia: declare todas las líneas participant antes de los mensajes.
Sin colores ni estilos codificados a menos que el usuario lo solicite explícitamente.
Use emojis en lugar de colores para transmitir significado semántico.
Un diagrama por bloque de código; valide la sintaxis antes de generar la salida.

Paso 7 — Crear Archivos y Entregar

Use create_file para escribir cada archivo .md en el sistema de archivos. Luego comprima todo en un zip y llame a present_files para que el usuario pueda descargar el resultado.

7.1 Escribir cada archivo

Para cada archivo en la estructura planificada, llame a create_file con la ruta completa bajo /mnt/user-data/outputs/<nombre-del-proyecto>/:

/mnt/user-data/outputs/mi-proyecto/README.md
/mnt/user-data/outputs/mi-proyecto/01-getting-started/README.md
/mnt/user-data/outputs/mi-proyecto/01-getting-started/01-installation.md
...

Escriba el contenido final completo en cada llamada — no escriba marcadores de posición.

7.2 Comprimir y presentar

Después de que todos los archivos estén escritos, comprima la carpeta de salida y llame a present_files:

cd /mnt/user-data/outputs
zip -r mi-proyecto-docs.zip mi-proyecto/

Luego llame a present_files con la ruta al archivo .zip.

7.3 Resumen en el chat

Después de present_files, escriba un mensaje corto en el chat que contenga:

Árbol de archivos — muestre la estructura completa del directorio que se generó.
Cómo servir — una línea: npx mdsvr ./mi-proyecto o mdsvr ./mi-proyecto.
Número de páginas — p.ej. "Se generaron 8 páginas en 3 secciones."

Referencia Rápida — Errores Comunes a Evitar

❌ Ruta absoluta en enlace:     [Página](/docs/pagina)
✅ Ruta relativa:               [Página](./pagina)

❌ Extensión .md en enlace:     [Página](./pagina.md)
✅ Sin extensión:               [Página](./pagina)

❌ Enlace al archivo README:     [Sección](./01-seccion/README)
✅ Enlace al directorio:        [Sección](./01-seccion)

❌ Punto en el nombre del archivo: 01.inicio.md
✅ Separador con guión:          01-inicio.md

❌ Falta H1:                     ## Introducción  (primer encabezado es H2)
✅ Comenzar con H1:              # Introducción

❌ Nivel de encabezado saltado:  # Título → ### Sub (salta H2)
✅ Jerarquía correcta:           # Título → ## Sección → ### Subsección

❌ Sin frontmatter:              (el archivo comienza directamente con #)
✅ Frontmatter presente:         --- title: "..." description: "..." ---

Archivos de Referencia

references/rules/mermaid.md — Referencia completa de sintaxis de Mermaid v11 para los 19 tipos de diagramas. Léalo siempre que se necesite algún diagrama en la documentación.

satoshiman/mdsvr

¿Qué es mdsvr?

Preguntar en tu IA favorita

Documentación