Importar documentação de um repositório
Como preparar a pasta docs/usabilidad do seu repositório para importá-la a um espaço de conhecimento e como revisar o relatório de cada importação.
Nesta página
Se a documentação do seu produto vive em um repositório, junto com o código, você pode escrevê-la em arquivos Markdown e deixar que ela seja importada sozinha para um espaço de Conhecimento a cada mudança. O repositório passa a ser a fonte: o Elion ITSM cria, atualiza e arquiva as páginas por você.
Antes de começar
Uma chave de importação do espaço guardada como segredo no repositório e a GitHub Action no repositório. Leia Chaves de importação.
Para ver o relatório das importações, você precisa de Administrar em Conhecimento (função Administrador).
Como a pasta é montada
Toda a documentação vai na pasta docs/usabilidad/ do repositório. Cada pasta é uma seção do menu e cada arquivo .md é uma página, com até 4 níveis.
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.pngOrdem. O número do começo (
01-,02-) define a ordem no menu e não aparece no endereço. O que não tem número vai depois, em ordem alfabética.Endereço. É o nome sem o número nem
.md:02-pedidos/01-crear-un-pedido.mdfica como/pedidos/crear-un-pedido. Use minúsculas, sem acentos nem espaços, com hifens.Seções. O
index.mdde cada pasta é o texto de entrada da seção. Se ele faltar, a seção é criada mesmo assim com o nome da pasta.Ignorados. As pastas que começam com
_ou.(exceto_img) e os arquivos que não são.mdnem imagens de_img/não são importados.Limites. Cada
.mdpode ter até 1 MB e cada imagem até 2 MB. A pasta completa, até 50 MB.
O cabeçalho de cada página
Cada arquivo começa com um cabeçalho entre duas linhas ---:
---
title: Crear un pedido
description: Cómo registrar un pedido nuevo y enviarlo a despacho.
tags: [pedidos, despacho]
updated: 2026-10-08
---Campo | Obrigatório | Uso |
|---|---|---|
| sim | Título da página e do menu (até 80 caracteres). |
| sim | Resumo de uma ou duas linhas (até 200 caracteres). Aparece na busca. |
| não | Etiquetas para a busca. |
| não | Data da última revisão do conteúdo (AAAA-MM-DD). |
| não | Título curto para o menu, se |
| não | Endereços anteriores da página, para não quebrar links se você a mover. |
| não |
|
Se title ou description tiverem dois-pontos seguidos de espaço (: ), escreva o valor entre aspas: description: "Configura el despacho: horario, zonas y costos.". Sem aspas, o cabeçalho fica inválido.
O que pode ser usado no texto
Elemento | Como se escreve |
|---|---|
Títulos |
|
Texto | Parágrafos, negrito, itálico, |
Listas |
|
Tabelas | Tabelas do GitHub. |
Blocos de código | Com a linguagem: |
Citações |
|
Avisos |
|
Linha separadora |
|
Links externos |
|
Links para outra página | O caminho até o |
Imagens | Sempre a partir de |
Não são aceitos HTML, iframes, scripts, vídeos, notas de rodapé nem fórmulas. O que não está na tabela é omitido na importação e fica anotado no relatório.
Como funciona cada importação
A importação é idempotente: cada arquivo é reconhecido pelo caminho, e executá-la duas vezes com o mesmo conteúdo não muda nada.
Se o arquivo… | O Elion ITSM… |
|---|---|
é novo | cria a página e a publica (ou a deixa como rascunho, com |
mudou | cria uma versão nova e a publica. No histórico ela fica com a nota Importado e o commit. |
não mudou | não faz nada. |
foi apagado | arquiva a página; não a exclui. Se o arquivo voltar, a página volta com seu número e seu histórico. |
só mudou de número (para reordenar) | move a página e mantém seu número |
Quando o espaço está incluído na central de ajuda, o site mostra as mudanças ao terminar a importação.
As páginas importadas ficam somente leitura
No Elion ITSM, uma página importada mostra o aviso Importada de … com o arquivo de origem: É editada no repositório do produto; aqui fica somente leitura (comentários são permitidos).
O editor fica bloqueado e a página não pode ser alterada pelo Elion ITSM. Para corrigi-la, edite o arquivo no repositório e deixe que a próxima importação a atualize. Leia Páginas importadas.
Revisar o relatório das importações
Entre em Conhecimento e abra o espaço.
Clique em Importações.
Abre-se Importações de … com as últimas 20 importações do espaço, da mais recente para a mais antiga. Cada uma mostra:
a data e há quanto tempo foi;
a origem: GitHub Action, Zip enviado ou Terminal;
o commit (seus 7 primeiros caracteres);
o resumo, por exemplo 3 criadas · 1 atualizada · 12 sem alterações;
se houver, N avisos. Clique para ver cada um com seu arquivo.
Os avisos informam o que foi omitido ou precisou ser ajustado: elementos não aceitos, imagens que faltam, links para páginas que não existem, cabeçalhos inválidos ou nomes que precisaram ser normalizados. Eles são corrigidos no repositório; a próxima importação os verifica de novo.
Se o espaço nunca foi importado, você verá Este espaço ainda não tem importações.
Se a GitHub Action falhar, revise o registro dela na aba Actions do GitHub. Uma chave revogada ou vencida é rejeitada: crie ou rotacione a chave e atualize o segredo.