Autoría y contenido

Esta sección está pensada para quien publica documentación y no quiere tocar el motor.

Regla básica#

El autor de contenido solo debería preocuparse de:

1. crear la carpeta de su categoría si no existe
2. completar su category.json
3. redactar Markdown con front matter correcto
4. subir los assets del producto a esa misma carpeta

Estructura recomendada de una nueva web#

CoreDocs.Tech/
  content/
    Mi.Producto/
      category.json
      introduccion.md
      instalacion.md
      integracion-api.md
      assets/
        logo.svg
        diagrama.png

Buenas prácticas editoriales#

• usa un artículo por tema funcional claro
• evita páginas demasiado largas con más de un objetivo
• reutiliza la misma ruta de tags para agrupar artículos relacionados
• deja el H1 dentro del contenido, salvo que quieras depender solo del title del front matter
• guarda capturas y PDFs dentro de la categoría, nunca fuera

Cuándo crear secciones y subsecciones#

No hace falta crear una subsección por cada artículo.

Usa una sola sección cuando varios artículos forman parte de una misma área:

---
title: Alta de proyectos
tags:
  - Operativa funcional
---

Solo usa una segunda profundidad cuando realmente exista un agrupador útil:

---
title: API de cuotas
tags:
  - Integración
  - Endpoints
---

Flujo de alta de una nueva categoría#

1. Crear carpeta bajo CoreDocs.Tech/content/.
2. Añadir category.json.
3. Redactar al menos un artículo inicial con front matter.
4. Ejecutar o lanzar el generador.
5. Revisar navegación, búsqueda y enlaces internos.

Qué no debe hacer el autor#

• no editar plantillas de Jinja si solo está publicando contenido
• no tocar dist/
• no mantener JSON de estructura para secciones o subsecciones
• no usar rutas absolutas al disco local para enlazar imágenes