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.pngOrden. 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.mdqueda como/pedidos/crear-un-pedido. Usa minúsculas, sin tildes ni espacios, con guiones.Secciones. El
index.mdde 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.mdni imágenes de_img/no se importan.Límites. Cada
.mdpuede 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 |
|---|---|---|
| sí | Título de la página y del menú (hasta 80 caracteres). |
| sí | Resumen de una o dos líneas (hasta 200 caracteres). Aparece en la búsqueda. |
| no | Etiquetas para la búsqueda. |
| no | Fecha de la última revisión del contenido (AAAA-MM-DD). |
| no | Título corto para el menú, si |
| no | Direcciones anteriores de la página, para no romper enlaces si la mueves. |
| no |
|
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 |
|
Texto | Párrafos, negrita, cursiva, |
Listas |
|
Tablas | Tablas de GitHub. |
Bloques de código | Con el lenguaje: |
Citas |
|
Avisos |
|
Línea separadora |
|
Enlaces externos |
|
Enlaces a otra página | La ruta al |
Imágenes | Siempre desde |
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 |
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 |
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
Entra a Conocimiento y abre el espacio.
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.