DocumentaciónAyuda

Importar documentación desde un repositorio

Cómo preparar la carpeta docs/usabilidad de tu repositorio para importarla a un espacio de conocimiento y cómo revisar el informe de cada importación.

En esta página

Si la documentación de tu producto vive en un repositorio, junto a su código, puedes escribirla en archivos Markdown y dejar que se importe sola a un espacio de Conocimiento en cada cambio. El repositorio pasa a ser la fuente: Elion ITSM crea, actualiza y archiva las páginas por ti.

Antes de empezar

  • Una llave de importación del espacio guardada como secreto en el repositorio y la GitHub Action en el repositorio. Lee Llaves de importación.

  • Para ver el informe de las importaciones necesitas Administrar en Conocimiento (rol Administrador).

Cómo se arma la carpeta

Toda la documentación va en la carpeta docs/usabilidad/ del repositorio. Cada carpeta es una sección del menú y cada archivo .md es una página, con hasta 4 niveles.

docs/usabilidad/
  index.md                      → portada
  01-primeros-pasos/
    index.md                    → entrada de la sección "Primeros pasos"
    01-iniciar-sesion.md
    02-cambiar-tu-contrasena.md
  02-pedidos/
    index.md
    01-crear-un-pedido.md
    02-despachos/
      index.md
      01-programar-un-despacho.md
  _img/                         → imágenes (no aparece en el menú)
    pedidos-lista.png
  • Orden. El número del comienzo (01-, 02-) define el orden en el menú y no aparece en la dirección. Lo que no lleva número va después, en orden alfabético.

  • Dirección. Es el nombre sin el número ni .md: 02-pedidos/01-crear-un-pedido.md queda como /pedidos/crear-un-pedido. Usa minúsculas, sin tildes ni espacios, con guiones.

  • Secciones. El index.md de cada carpeta es el texto de entrada de la sección. Si falta, la sección se crea igual con el nombre de la carpeta.

  • Ignorados. Las carpetas que empiezan con _ o . (salvo _img) y los archivos que no son .md ni imágenes de _img/ no se importan.

  • Límites. Cada .md puede pesar hasta 1 MB y cada imagen hasta 2 MB. La carpeta completa, hasta 50 MB.

El encabezado de cada página

Cada archivo empieza con un encabezado entre dos líneas ---:

---
title: Crear un pedido
description: Cómo registrar un pedido nuevo y enviarlo a despacho.
tags: [pedidos, despacho]
updated: 2026-10-08
---

Campo

Obligatorio

Uso

title

sí

Título de la página y del menú (hasta 80 caracteres).

description

sí

Resumen de una o dos líneas (hasta 200 caracteres). Aparece en la búsqueda.

tags

no

Etiquetas para la búsqueda.

updated

no

Fecha de la última revisión del contenido (AAAA-MM-DD).

menu_title

no

Título corto para el menú, si title es largo.

redirect_from

no

Direcciones anteriores de la página, para no romper enlaces si la mueves.

draft

no

true importa la página como borrador: no se publica.

Si title o description llevan dos puntos seguidos de un espacio (: ), escribe el valor entre comillas: description: "Configura el despacho: horario, zonas y costos.". Sin comillas, el encabezado queda inválido.

Qué se puede usar en el texto

Elemento

Cómo se escribe

Títulos

##, ### y ####. El título principal lo pone title: no uses # en el texto.

Texto

Párrafos, negrita, cursiva, código y tachado.

Listas

-, 1. y listas de tareas - [ ].

Tablas

Tablas de GitHub.

Bloques de código

Con el lenguaje: bash, sh, json, yaml, sql, ts, js, html, css, xml, log o text.

Citas

>

Avisos

> [!NOTE], > [!TIP], > [!WARNING] y > [!CAUTION].

Línea separadora

---

Enlaces externos

[texto](https://…). Solo https: y mailto:.

Enlaces a otra página

La ruta al .md: [Crear un pedido](../02-pedidos/01-crear-un-pedido.md).

Imágenes

Siempre desde _img/, en PNG, JPEG o WebP: ![Lista de pedidos](../_img/pedidos-lista.png). El texto entre corchetes es obligatorio.

No se admiten HTML, iframes, scripts, videos, notas al pie ni fórmulas. Lo que no está en la tabla se omite al importar y queda anotado en el informe.

Cómo funciona cada importación

La importación es idempotente: cada archivo se reconoce por su ruta, y correrla dos veces con lo mismo no cambia nada.

Si el archivo…

Elion ITSM…

es nuevo

crea la página y la publica (o la deja en borrador, con draft: true).

cambió

crea una versión nueva y la publica. En el historial queda con la nota Importado y el commit.

no cambió

no hace nada.

se borró

archiva la página; no la elimina. Si el archivo vuelve, la página vuelve con su número y su historial.

solo cambió de número (para reordenar)

mueve la página y conserva su número KB-… y su historial.

Cuando el espacio está incluido en el centro de ayuda, el sitio muestra los cambios al terminar la importación.

Las páginas importadas quedan en solo lectura

En Elion ITSM, una página importada muestra el aviso Importada desde … con su archivo de origen: Se edita en el repositorio del producto; aquí queda en solo lectura (los comentarios sí se pueden dejar).

Su editor queda bloqueado y la página no se puede cambiar desde Elion ITSM. Para corregirla, edita el archivo en el repositorio y deja que la próxima importación la actualice. Lee Páginas importadas.

Revisar el informe de las importaciones

  1. Entra a Conocimiento y abre el espacio.

  2. Presiona Importaciones.

Se abre Importaciones de … con las últimas 20 importaciones del espacio, de la más reciente a la más antigua. Cada una muestra:

  • la fecha y hace cuánto fue;

  • el origen: GitHub Action, Zip subido o Terminal;

  • el commit (sus primeros 7 caracteres);

  • el resumen, por ejemplo 3 creadas · 1 actualizada · 12 sin cambios;

  • si las hay, N advertencias. Presiónalo para ver cada una con su archivo.

Las advertencias avisan de lo que se omitió o se tuvo que ajustar: elementos no admitidos, imágenes que faltan, enlaces a páginas que no existen, encabezados inválidos o nombres que se tuvieron que normalizar. Se corrigen en el repositorio; la próxima importación las vuelve a revisar.

Si el espacio nunca se importó, verás Este espacio todavía no tiene importaciones.

Si la GitHub Action falla, revisa su registro en la pestaña Actions de GitHub. Una llave revocada o vencida se rechaza: crea o rota la llave y actualiza el secreto.

Relacionado

Buscar en Elion ITSM

Escribe al menos 2 letras para buscar en Elion ITSM.

↑↓ moverse · Enter abrir · Esc cerrar