​
Introdução

O editor web é uma interface visual para criar, editar e revisar documentação diretamente no seu navegador.

O editor web oferece uma experiência What-You-See-Is-What-You-Get (WYSIWYG) enquanto mantém a sincronização com seu repositório Git, o que permite que você veja atualizações em tempo real e colabore com sua equipe nas mudanças da documentação.

​
Editor web vs. CLI

O editor web permite que você escreva e edite sua documentação no seu navegador sem precisar de ferramentas de desenvolvimento local ou usar a linha de comando. Você deve usar o editor web se quiser manter sua documentação em um só lugar com uma única ferramenta.

O CLI é uma ferramenta de linha de comando que permite criar e gerenciar sua documentação localmente usando o IDE de sua escolha. Você deve usar o CLI se quiser integrar a documentação ao seu fluxo de trabalho de desenvolvimento existente.

Tanto o editor web quanto o CLI são totalmente integrados com seu repositório Git, então você pode usá-los de forma intercambiável e diferentes membros da sua equipe podem usar qualquer ferramenta com base em suas preferências.

​
Modos do Editor

O editor web oferece dois modos para acomodar diferentes preferências e necessidades de edição.

Você pode alternar entre os modos naturais a qualquer momento usando o botão no canto superior direito da barra de ferramentas do editor.

​
Modo Visual

O modo visual fornece uma experiência WYSIWYG onde as alterações que você faz no editor são as alterações que serão publicadas no seu site de documentação. Este modo é ideal para quando você quer ver como suas alterações ficarão em tempo real.

Você pode adicionar blocos de conteúdo e outros componentes à sua documentação no modo visual usando o menu suspenso de componentes.

  1. Pressione a tecla / para abrir o menu de componentes.
  2. Selecione um componente do menu.

​
Modo Markdown

O modo Markdown fornece acesso direto ao código MDX subjacente da sua documentação. Este modo é preferível quando você precisa de controle preciso sobre as propriedades dos componentes ou quando prefere escrever em sintaxe Markdown/MDX.

​
Fazendo Alterações

  1. Navegar pelos arquivos: Use o explorador de arquivos na barra lateral para navegar pela sua documentação.
  2. Abrir um arquivo: Clique no arquivo que você deseja editar para abri-lo no editor.
  3. Fazer alterações: Edite o conteúdo usando o modo visual ou Markdown. As alterações são automaticamente salvas como rascunhos.
  4. Visualizar alterações: Veja como suas alterações aparecerão no modo visual.

​
Publicação

A publicação atualiza diretamente seu branch de implantação configurado. Para fluxos de trabalho colaborativos, considere usar branches e pull requests em vez disso.

Quando você estiver pronto para tornar suas alterações ativas, clique no botão Publicar no canto superior direito do editor web.

Suas alterações serão implantadas no seu site de produção imediatamente.

​
Branches

Branches permitem que você trabalhe em alterações na documentação sem atualizar a versão principal até que você esteja pronto para que suas alterações entrem em vigor.

Use branches para atualizações significativas, novas seções ou quando vários membros da equipe estão trabalhando em diferentes partes da documentação simultaneamente.

​
Criando um Branch

  1. Selecione o nome do branch na barra de ferramentas do editor (geralmente main por padrão).
  2. Selecione Novo Branch.
  3. Digite um nome descritivo para o seu branch.
  4. Selecione Criar Branch.

​
Alternando Branches

  1. Selecione o nome do branch atual na barra de ferramentas do editor.
  2. Selecione o branch para o qual você deseja mudar no menu suspenso.

​
Salvando Alterações em um Branch

Para salvar suas alterações em um branch, selecione o botão Salvar Alteraçõesbotão no canto superior direito do editor.

Quando você está trabalhando em um branch, suas alterações não são salvas automaticamente.

​
Pull Requests

Pull requests (ou PRs) permitem que você e outras pessoas revisem as alterações que você fez em um branch e depois mesclem essas alterações em sua documentação principal.

​
Criando um Pull Request em um Branch

  1. Faça suas alterações em um branch.
  2. Clique noPublish Pull Requestbotão no canto superior direito do editor.
  3. Adicione um Título e Descrição do Pull Request para o seu pull request. Um bom título e descrição ajudarão os revisores a entender as alterações que você fez.
  4. Clique emPublish Pull Request.

​
Revisando Pull Requests

Você pode revisar pull requests na sua plataforma Git (GitHub, GitLab).

Depois de criar um pull request, você pode ver uma implantação de preview das alterações.

Depois que um revisor aprovar um pull request, você pode mesclar o pull request em seu branch principal e as alterações serão implantadas em seu site de documentação ao vivo.

​
Sincronização Git

O editor web se integra ao seu repositório Git, garantindo que todas as alterações sejam devidamente versionadas e rastreadas.

​
Como funciona a sincronização Git

  • Autenticação: O editor web se conecta ao seu repositório Git através do nossoGitHub AppouGitLab integration.

  • Busca automática: Quando você abre o editor, ele busca automaticamente o conteúdo mais recente do branch principal do seu repositório.

  • Rastreamento de alterações: Conforme você faz edições, o editor web rastreia as alterações e pode commitá-las em seu repositório.

  • Branching: Você pode fazer alterações diretamente no seu branch principal ou em um branch separado, dependendo das suas preferências de fluxo de trabalho.

  • Pull requests: Para fluxos de trabalho colaborativos, você pode criar pull requests a partir do editor web.

​
Terminologia Git

Entender os seguintes termos pode ajudá-lo a trabalhar de forma mais eficaz com o editor web e o fluxo de trabalho Git.

​
Solução de problemas

Aqui estão soluções para problemas comuns que você pode encontrar com o editor web.