Pular para o conteúdo principal

Painel editorial

O painel editorial permite criar, revisar e publicar documentos usando uma interface visual. As páginas continuam armazenadas como Markdown no GitHub, preservando histórico, autoria e possibilidade de revisão.

O que é possível fazer​

  • Criar seções, subseções e páginas.
  • Editar Markdown no modo visual ou no modo de texto.
  • Adicionar imagens, arquivos, tabelas, links e blocos de código.
  • Inserir blocos de informação, dica, atenção e perigo.
  • Organizar a posição de cada página no menu.
  • Salvar rascunhos e encaminhar alterações para revisão.
  • Publicar uma alteração sem executar comandos de build ou deploy.

Acessar o painel​

O acesso em produção é permitido somente para contas do GitHub autorizadas no repositório privado.

Criar uma página​

  1. Abra Documentação.
  2. Selecione Nova Página.
  3. Preencha o título.
  4. Informe o caminho da página, por exemplo backend/pedidos/criar-pedido.
  5. Escreva o conteúdo usando o editor visual ou Markdown.
  6. Se necessário, defina a ordem da página no menu.
  7. Selecione Salvar para criar um rascunho.
  8. Encaminhe para revisão e publique quando estiver pronto.

Depois da publicação, a alteração é enviada ao GitHub. O build e o deploy são executados automaticamente pela Action do projeto.

Criar uma seção​

Uma seção é representada por uma pasta com uma página inicial:

  1. Crie uma nova página.
  2. No caminho, informe nome-da-secao/index.
  3. Use o nome da seção como título.
  4. Publique a página inicial.
  5. Para adicionar conteúdo, crie páginas como nome-da-secao/primeira-pagina.

A seção e suas páginas passam a aparecer automaticamente no sidebar. Seções podem ser aninhadas, por exemplo backend/integracoes/pagamentos.

Adicionar imagens e arquivos​

Use o botão de mídia do editor para enviar o arquivo. Os uploads ficam em static/uploads e são versionados junto com a documentação.

Antes de publicar:

  • Use nomes de arquivo descritivos.
  • Evite espaços e caracteres especiais.
  • Preencha o texto alternativo das imagens.
  • Comprima imagens muito grandes.
  • Não envie credenciais, tokens ou dados de clientes.

Executar o painel localmente​

Abra dois terminais na raiz do projeto.

No primeiro:

npm start

No segundo:

npx decap-server

Depois, acesse http://localhost:3000/vidya-docs/admin/. Nesse modo, as alterações são gravadas diretamente na cópia local do repositório e o fluxo de Pull Request fica desativado.

Habilitar o login do GitHub em produção​

O GitHub exige um serviço seguro para trocar o código OAuth pelo token de acesso. O segredo do OAuth nunca deve ser colocado neste repositório.

  1. Implante o proxy OAuth recomendado pelo Decap CMS em um Cloudflare Worker.

  2. Crie um GitHub OAuth App.

  3. Configure o callback como https://URL-DO-WORKER/callback.

  4. No Worker, salve o Client ID e o Client Secret como secrets.

  5. Como este repositório é privado, habilite GITHUB_REPO_PRIVATE.

  6. Em static/admin/config.yml, adicione dentro de backend:

    base_url: https://URL-DO-WORKER auth_endpoint: /auth

  7. Publique a configuração e teste o login pelo endereço do painel.

Fluxo editorial​

Rascunho → Em revisão → Pull Request → Publicação → Build → GitHub Pages

Cada publicação gera uma alteração rastreável. Quando o Pull Request é aprovado e incorporado à main, a Action valida o TypeScript, gera o site e publica a nova versão.

Boas práticas​

  • Prefira títulos curtos e objetivos.
  • Use apenas um título principal por documento.
  • Divida conteúdos extensos em subseções.
  • Confira links e imagens na pré-visualização.
  • Use blocos de destaque apenas para informações importantes.
  • Não altere o identificador ou o endereço de uma página existente sem avaliar links externos.