Import documentation from a repository
How to prepare your repository's docs/usabilidad folder to import it into a knowledge space and how to review each import's report.
On this page
If your product's documentation lives in a repository, next to its code, you can write it in Markdown files and let it import itself into a Knowledge space on every change. The repository becomes the source: Elion ITSM creates, updates and archives the pages for you.
Before you start
An import key for the space stored as a secret in the repository, and the GitHub Action in the repository. Read Import keys.
To see the import report you need Administer in Knowledge (Administrator role).
How the folder is organized
All the documentation goes in the repository's docs/usabilidad/ folder. Each folder is a menu section and each .md file is a page, with up to 4 levels.
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.pngOrder. The leading number (
01-,02-) sets the order in the menu and does not appear in the address. Anything without a number goes after, in alphabetical order.Address. It is the name without the number or
.md:02-pedidos/01-crear-un-pedido.mdbecomes/pedidos/crear-un-pedido. Use lowercase, without accents or spaces, with hyphens.Sections. Each folder's
index.mdis the section's intro text. If it is missing, the section is still created with the folder name.Ignored. Folders that start with
_or.(except_img) and files that are neither.mdnor images in_img/are not imported.Limits. Each
.mdcan be up to 1 MB and each image up to 2 MB. The whole folder, up to 50 MB.
Each page's header
Each file starts with a header between two --- lines:
---
title: Crear un pedido
description: Cómo registrar un pedido nuevo y enviarlo a despacho.
tags: [pedidos, despacho]
updated: 2026-10-08
---Field | Required | Use |
|---|---|---|
| yes | Page and menu title (up to 80 characters). |
| yes | One- or two-line summary (up to 200 characters). It appears in search. |
| no | Tags for search. |
| no | Date of the last content review (YYYY-MM-DD). |
| no | Short title for the menu, if |
| no | The page's earlier addresses, so links do not break if you move it. |
| no |
|
If title or description contain a colon followed by a space (: ), put the value in quotes: description: "Configura el despacho: horario, zonas y costos.". Without quotes, the header is invalid.
What you can use in the text
Element | How to write it |
|---|---|
Headings |
|
Text | Paragraphs, bold, italics, |
Lists |
|
Tables | GitHub tables. |
Code blocks | With the language: |
Quotes |
|
Callouts |
|
Divider line |
|
External links |
|
Links to another page | The path to the |
Images | Always from |
HTML, iframes, scripts, videos, footnotes and formulas are not supported. Anything not in the table is skipped on import and noted in the report.
How each import works
The import is idempotent: each file is recognized by its path, and running it twice with the same content changes nothing.
If the file… | Elion ITSM… |
|---|---|
is new | creates the page and publishes it (or leaves it as a draft, with |
changed | creates a new version and publishes it. In the history it is marked with the note Imported and the commit. |
did not change | does nothing. |
was deleted | archives the page; it does not delete it. If the file comes back, the page comes back with its number and history. |
only changed its number (to reorder) | moves the page and keeps its |
When the space is included in the help center, the site shows the changes when the import finishes.
Imported pages are read-only
In Elion ITSM, an imported page shows the notice Imported from … with its source file: It is edited in the product repository; here it is read-only (comments are still allowed).
Its editor is locked and the page cannot be changed from Elion ITSM. To fix it, edit the file in the repository and let the next import update it. Read Imported pages.
Review the import report
Go to Knowledge and open the space.
Click Imports.
Imports of … opens with the space's last 20 imports, from newest to oldest. Each one shows:
the date and how long ago it was;
the source: GitHub Action, Uploaded zip or Terminal;
the commit (its first 7 characters);
the summary, for example 3 created · 1 updated · 12 unchanged;
if there are any, N warnings. Click it to see each one with its file.
Warnings tell you what was skipped or had to be adjusted: unsupported elements, missing images, links to pages that do not exist, invalid headers or names that had to be normalized. Fix them in the repository; the next import checks them again.
If the space was never imported, you see This space has no imports yet.
If the GitHub Action fails, check its log in the Actions tab on GitHub. A revoked or expired key is rejected: create or rotate the key and update the secret.