DocumentaciónHelp

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.png
  • Order. 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.md becomes /pedidos/crear-un-pedido. Use lowercase, without accents or spaces, with hyphens.

  • Sections. Each folder's index.md is 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 .md nor images in _img/ are not imported.

  • Limits. Each .md can 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

title

yes

Page and menu title (up to 80 characters).

description

yes

One- or two-line summary (up to 200 characters). It appears in search.

tags

no

Tags for search.

updated

no

Date of the last content review (YYYY-MM-DD).

menu_title

no

Short title for the menu, if title is long.

redirect_from

no

The page's earlier addresses, so links do not break if you move it.

draft

no

true imports the page as a draft: it is not published.

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

##, ### and ####. The main title comes from title: do not use # in the text.

Text

Paragraphs, bold, italics, code and strikethrough.

Lists

-, 1. and task lists - [ ].

Tables

GitHub tables.

Code blocks

With the language: bash, sh, json, yaml, sql, ts, js, html, css, xml, log or text.

Quotes

>

Callouts

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

Divider line

---

External links

[text](https://…). Only https: and mailto:.

Links to another page

The path to the .md: [Crear un pedido](../02-pedidos/01-crear-un-pedido.md).

Images

Always from _img/, in PNG, JPEG or WebP: ![Lista de pedidos](../_img/pedidos-lista.png). The text in brackets is required.

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 draft: true).

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 KB-… number and its history.

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

  1. Go to Knowledge and open the space.

  2. 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.

Related

Search Elion ITSM

Type at least 2 characters to search Elion ITSM.

↑↓ to navigate · Enter to open · Esc to close