DocumentaciónAjuda

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.png
  • Ordem. 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.md fica como /pedidos/crear-un-pedido. Use minúsculas, sem acentos nem espaços, com hifens.

  • Seções. O index.md de 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 .md nem imagens de _img/ não são importados.

  • Limites. Cada .md pode 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

title

sim

Título da página e do menu (até 80 caracteres).

description

sim

Resumo de uma ou duas linhas (até 200 caracteres). Aparece na busca.

tags

não

Etiquetas para a busca.

updated

não

Data da última revisão do conteúdo (AAAA-MM-DD).

menu_title

não

Título curto para o menu, se title for longo.

redirect_from

não

Endereços anteriores da página, para não quebrar links se você a mover.

draft

não

true importa a página como rascunho: ela não é publicada.

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

##, ### e ####. O título principal vem de title: não use # no texto.

Texto

Parágrafos, negrito, itálico, código e tachado.

Listas

-, 1. e listas de tarefas - [ ].

Tabelas

Tabelas do GitHub.

Blocos de código

Com a linguagem: bash, sh, json, yaml, sql, ts, js, html, css, xml, log ou text.

Citações

>

Avisos

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

Linha separadora

---

Links externos

[texto](https://…). Só https: e mailto:.

Links para outra página

O caminho até o .md: [Crear un pedido](../02-pedidos/01-crear-un-pedido.md).

Imagens

Sempre a partir de _img/, em PNG, JPEG ou WebP: ![Lista de pedidos](../_img/pedidos-lista.png). O texto entre colchetes é obrigatório.

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

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 KB-… e seu histórico.

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

  1. Entre em Conhecimento e abra o espaço.

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

Relacionado

Pesquisar em Elion ITSM

Digite pelo menos 2 letras para pesquisar em Elion ITSM.

↑↓ navegar · Enter abrir · Esc fechar