Publicar artigos no GitBook
Conecte o GitBook com uma chave de acesso pessoal e publique artigos do Clevera como páginas em seus espaços do GitBook. Onde criar a chave, como escolher sites, como dicas, etapas e guias são convertidos, o que a atualização faz e erros comuns.
Publique um artigo do Clevera como uma página em um espaço do GitBook. O GitBook se conecta com uma chave de acesso pessoal em vez de um login, e a página aparece no nível superior do espaço que você escolher.
Antes de começar
- No Clevera: o workspace está no plano Pro ou Personalizado, e você é um proprietário ou administrador para conectar o GitBook. Uma vez conectado, qualquer pessoa que possa editar um artigo pode publicá-lo. Veja Publicar artigos em suas outras ferramentas.
- No GitBook: qualquer plano. A chave atua como o usuário do GitBook que a criou, portanto, essa pessoa precisa de acesso de edição aos espaços nos quais você publica.
- Um artigo: gere-o primeiro. A publicação envia apenas o artigo. Para incluir um vídeo, coloque-o dentro do artigo; veja Mostrar um vídeo em um artigo.
Criar uma chave de acesso do GitBook
- No GitBook, abra as configurações da sua conta e vá para Developer (
app.gitbook.com/account/developer). - Crie um novo token de acesso pessoal, dê a ele um nome como "Clevera" e copie-o. O GitBook o mostra apenas uma vez.
Conectar o GitBook
Abrir a janela de conexão
No Clevera, clique no nome do seu workspace na barra lateral, escolha Integrações, encontre o GitBook e clique em Conectar. A janela Conectar GitBook diz "Cole uma chave. Nós a verificamos antes de salvar qualquer coisa." e tem um link Open GitBook para a página de desenvolvedor.
Colar e verificar a chave
Cole a chave em Chave de acesso e clique em Verificar chave. Quando o GitBook a aceitar, você verá "Chave aceita."
Escolher os sites
Em Sites para publicar, o Clevera lista seus sites de documentação (ou espaços) e seleciona todos eles. Abra a lista para desmarcar qualquer um que você não queira, por exemplo "2 de 3 selecionados", e clique em Conectar. Você verá "GitBook conectado.".
O Clevera verifica a chave antes de salvar qualquer coisa.
Se sua conta do GitBook não tiver nenhum espaço, o Clevera cria um chamado "Clevera" na sua primeira organização para que você possa publicar imediatamente.
A chave não expira do lado do Clevera. Para alterar a chave ou os sites, abra o menu ⋯ na conexão do GitBook, escolha Reconectar e passe pela mesma janela; a nova chave e a nova escolha substituirão as antigas.
Publicar um artigo no GitBook
Abrir a aba Publicar
No editor, clique em Compartilhar → Publicar e clique no bloco do GitBook em Pronto para publicar.
Escolher um espaço
Em Onde vai, a lista mostra os espaços por trás dos sites que você escolheu, com seus ícones.
Publicar
Clique em Publicar no GitBook. O Clevera procura primeiro por uma cópia existente; se uma página com o mesmo título já estiver no espaço, escolha o que fazer (veja Atualizar uma página que você publicou). Quando terminar, você verá "Publicado no GitBook." Clique em Abrir no GitBook para ver a página.
Você pode fechar a janela Compartilhar enquanto ela é executada; uma notificação avisa quando terminar.
A página é adicionada no nível superior do espaço, e seu endereço vem do título: "Set up billing" torna-se /set-up-billing. Títulos em outros alfabetos ou com acentos são escritos primeiro em letras latinas; um título sem nada para escrever recebe um código curto fixo. Mova ou renomeie a página no GitBook depois, se desejar.
Como a página fica no GitBook
O título da página é o título do artigo. A página contém apenas o artigo: o vídeo de onde o artigo veio não é adicionado.
| No Clevera | No GitBook |
|---|---|
| Cabeçalhos, parágrafos | Cabeçalhos e texto |
| Negrito, itálico, tachado, código em linha, links | Mantidos |
| Destaque, sobrescrito, subscrito | Mantidos |
| Listas com marcadores e numeradas, listas de verificação | Listas e listas de tarefas |
| Citações | Citações |
| Blocos de código | Blocos de código com a linguagem e o título do código |
| Divisores | Divisores |
| Tabelas | Tabelas com o texto de cada célula |
| Callouts | Blocos de dica: info → Info, note → Info, tip → Success, success → Success, warning → Warning, danger → Danger |
| Etapas numeradas | Um stepper do GitBook, uma etapa por etapa |
| Guias | Guias do GitBook |
| Seções recolhíveis | Blocos expansíveis |
| Cartões | Uma lista de links com suas descrições; ícones de cartão são omitidos |
| Equações | Matemática do GitBook |
| Capturas de tela | Imagens carregadas no espaço, com a legenda |
| Vídeos e incorporações no artigo | Blocos de incorporação. Um vídeo do Clevera é incluído apenas quando o link de compartilhamento desse vídeo está ativado. |
As capturas de tela são carregadas no espaço como arquivos, portanto, continuam funcionando mesmo se você excluir o artigo no Clevera. Um arquivo de vídeo carregado no artigo permanece como um link para o Clevera que expira após algum tempo; publique novamente para renová-lo.
Atualizar uma página que você publicou
A publicação é de mão única. A página do GitBook não é atualizada quando você edita o artigo no Clevera, e as edições feitas no GitBook nunca voltam para o Clevera. Depois de editar o artigo, publique-o novamente no mesmo espaço. O Clevera procura por uma página com o mesmo título (letras maiúsculas ou minúsculas não importam) ou o mesmo endereço e mostra "Este artigo já está no GitBook."
- Atualizar o artigo existente substitui o conteúdo e o título da página. O endereço permanece o mesmo. As alterações feitas no GitBook desde então são substituídas; o histórico do GitBook permite que você as recupere. Clique em Atualizar no GitBook.
- Criar um novo artigo adiciona uma segunda página sob o Novo título que você inserir (o Clevera sugere um como "Set up billing (2)"), com seu próprio endereço. Clique em Criar novo artigo.
Desconectar e revogar acesso
- No Clevera, abra Integrações, clique em GitBook, depois em Desconectar e confirme. As páginas que você já publicou permanecem no GitBook.
- No GitBook, exclua a chave de acesso na página Developer para que ela não possa ser usada novamente.
Solução de problemas
| Você vê | O que fazer |
|---|---|
| "Cole uma chave primeiro." | O campo da chave está vazio. |
| "Chave de acesso do GitBook inválida. Verifique e tente novamente." | A chave está incorreta ou foi excluída. Crie uma nova e cole-a. |
| "Falha ao validar a chave de acesso do GitBook." ou "Não foi possível verificar essa chave. Tente novamente." | O GitBook não respondeu. Tente novamente em instantes. |
| "Escolha pelo menos um site." | Marque pelo menos um site antes de Conectar. |
| "Nenhum espaço ou site de documentação do GitBook encontrado, e não foi possível criar um automaticamente. Crie um espaço no GitBook e tente novamente." | Crie um espaço no GitBook e conecte-se novamente. |
| "Falha ao conectar ao GitBook. Verifique sua chave de acesso." | Verifique a chave e conecte-se novamente. |
| "Não foi possível carregar seus espaços do GitBook. Tente novamente." | Clique em Tente novamente. Se repetir, reconecte o GitBook. |
| "Selecione um espaço para publicar." | Escolha um espaço primeiro. |
| Um espaço está faltando na lista | Ele não faz parte dos sites que você escolheu, ou o usuário da chave não pode vê-lo. Reconecte e escolha o site. |
| "O GitBook rejeitou o conteúdo da página" ou "O GitBook não pôde mesclar a solicitação de alteração", com o motivo do GitBook | O usuário da chave não pode editar esse espaço, ou o GitBook recusou a alteração. Verifique o acesso no GitBook e clique em Tente novamente. |
| "Chave de acesso não encontrada. Reconecte o GitBook." | Reconecte o GitBook com uma chave. |
| "O conteúdo do artigo está vazio ou inválido." | O artigo ainda não tem conteúdo. Abra-o, verifique-o e publique. |
| "A página a ser substituída não foi encontrada no GitBook. Ela pode ter sido movida ou excluída." | Escolha Criar um novo artigo em vez disso. |
| "Falha ao publicar no GitBook. Tente novamente." ou "Falha ao atualizar a página no GitBook. Tente novamente." | Clique em Tente novamente. Se continuar falhando, reconecte com uma chave nova. |