Publicar artigos no ReadMe
Conecte um projeto do ReadMe com sua Chave de API e publique artigos do Clevera como guias na categoria que você escolher, com capturas de tela enviadas para o ReadMe. Como callouts, etapas e vídeos são convertidos, como as atualizações funcionam e erros comuns.
Publique um artigo do Clevera como um guia em seu projeto do ReadMe, arquivado na categoria de guia que você escolher. As capturas de tela são enviadas para o ReadMe.
Antes de começar
- No Clevera: o workspace está no plano Pro ou Personalizado, e você é um proprietário ou administrador para conectar o ReadMe. Uma vez conectado, qualquer pessoa que possa editar um artigo pode publicá-lo. Veja Publicar artigos em suas outras ferramentas.
- No ReadMe: um projeto que você possa gerenciar, com pelo menos uma categoria em sua seção de Guias. Uma chave conecta um projeto.
- Um projeto atual do ReadMe: o Clevera publica através da API atual (v2) do ReadMe, que o ReadMe oferece para projetos no ReadMe Refactored. Projetos ainda na plataforma mais antiga do ReadMe não podem ser conectados.
- Versão: o Clevera publica na versão principal (estável) dos Guias do seu projeto.
- 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.
Encontre sua Chave de API do ReadMe
Em seu projeto do ReadMe, abra Configuration → API Keys, depois copie uma chave (crie uma se a lista estiver vazia). A chave dá acesso total a esse projeto, portanto, mantenha-a privada.
Conectar o ReadMe
Abrir a janela de conexão
No Clevera, clique no nome do seu workspace na barra lateral, escolha Integrações, encontre o ReadMe e clique em Conectar. A janela Conectar ReadMe diz "Cole uma chave. Nós a verificamos antes de salvar qualquer coisa."
Colar e verificar a chave
Cole a chave em Chave de API e clique em Verificar chave. Quando o ReadMe a aceitar, você verá "Chave aceita." e seu projeto em Sites para publicar.
Conectar
Clique em Conectar. Você verá "ReadMe conectado." e o ReadMe aparecerá em Conectado com o nome do seu projeto.
A chave não expira do lado do Clevera. Para conectar um projeto diferente, use Reconectar na conexão do ReadMe e cole a chave desse projeto; ela substituirá a antiga.
Publicar um artigo no ReadMe
Abrir a aba Publicar
No editor, clique em Compartilhar → Publicar e clique no bloco ReadMe em Pronto para publicar.
Escolher uma categoria de guia
Em Onde vai, Projeto mostra o projeto conectado. Escolha uma Categoria de guia: "O artigo vai para a seção Guias, sob esta categoria." Se você vir "Nenhuma categoria de guia ainda", crie uma no ReadMe primeiro.
Publicar
Clique em Publicar no ReadMe. O Clevera procura primeiro por uma cópia existente; se um guia com o mesmo endereço já existir, escolha o que fazer (veja Atualizar um guia). Quando terminar, você verá "Publicado no ReadMe." Clique em Abrir no ReadMe para ver o guia.
Você pode fechar a janela Compartilhar enquanto ela é executada; uma notificação avisa quando terminar.
O endereço do guia vem do seu título: "Set up billing" torna-se /docs/set-up-billing no seu site de documentação. Títulos em outros scripts ou com acentos são escritos primeiro em letras latinas. Se o endereço já estiver ocupado, o ReadMe dá ao novo guia um endereço ligeiramente diferente.
Como o guia aparece no ReadMe
O título do guia é o título do artigo. O guia contém apenas o artigo: o vídeo de onde o artigo veio não é adicionado.
| No Clevera | No ReadMe |
|---|---|
| Cabeçalhos, parágrafos | Cabeçalhos e texto |
| Negrito, itálico, tachado, código em linha, links | Mantidos. Links para outras páginas do Clevera mantêm apenas seu texto. |
| Destaque, sobrescrito, subscrito | Mantidos |
| Listas com marcadores e numeradas, checklists | Listas e checklists |
| 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 | Callouts do ReadMe com o título do callout: 📘 para info e nota, 👍 para dica e sucesso, 🚧 para aviso, ❗️ para perigo |
| Etapas numeradas | Uma lista numerada: o título de cada etapa em negrito, seu conteúdo aninhado abaixo dele |
| Abas | O rótulo de cada aba em negrito, seguido pelo seu conteúdo. Abas que contêm apenas código tornam-se abas de código do ReadMe. |
| Seções recolhíveis | Seções expansíveis |
| Cards | Uma lista de links com suas descrições; ícones de card são omitidos |
| Equações | Código |
| Capturas de tela | Imagens enviadas para o ReadMe, com a legenda em itálico |
| Vídeos e embeds no artigo | Embeds do ReadMe. Um vídeo do Clevera é incluído apenas quando o link de compartilhamento desse vídeo está ativado. |
Chaves e colchetes angulares no seu texto são escapados, para que o formato de página do ReadMe os mostre como foram escritos.
As capturas de tela são enviadas para o ReadMe, portanto, continuam funcionando mesmo se você excluir o artigo no Clevera. Uma captura de tela que falha ao ser enviada, ou um arquivo de vídeo dentro do artigo, permanece como um link para o Clevera que expira após algum tempo; publique novamente para renová-lo.
Atualizar um guia
A publicação é de mão única. O guia não é atualizado quando você edita o artigo no Clevera, e as edições feitas no ReadMe nunca voltam para o Clevera. Depois de editar o artigo, publique-o novamente.
O Clevera procura por um guia com o mesmo endereço em qualquer lugar nos seus Guias e mostra "Este artigo já está no ReadMe." Clique em Visualizar para abri-lo, então escolha:
- Atualizar o artigo existente sobrescreve esse guia: mesmo endereço, novo título e conteúdo. Clique em Atualizar no ReadMe.
- Criar um novo artigo cria um novo guia sob o Novo título que você inserir, com seu próprio endereço. Clique em Criar novo artigo.
Alterações feitas no ReadMe desde a última publicação são sobrescritas quando o Clevera atualiza um guia.
Desconectar e revogar acesso
- No Clevera, abra Integrações, clique em ReadMe, depois em Desconectar e confirme. Os guias que você já publicou permanecem no ReadMe.
- No ReadMe, abra Configuration → API Keys e exclua a chave que você deu ao Clevera.
Solução de problemas
| Você vê | O que fazer |
|---|---|
| "Cole uma chave primeiro." | O campo da chave está vazio. |
| "Chave de API inválida. Por favor, verifique sua Chave de API do ReadMe." | A chave está incorreta ou foi excluída. Copie-a novamente de Configuration → API Keys. |
| "Falha ao buscar informações do projeto no ReadMe." ou "Não foi possível verificar essa chave. Tente novamente." | O ReadMe não respondeu, ou o projeto não está no ReadMe Refactored, que o Clevera precisa. Tente novamente, depois tente uma nova chave; se o projeto estiver na plataforma mais antiga do ReadMe, ele não pode ser conectado. |
| "Não foi possível validar a Chave de API. Por favor, verifique sua Chave de API do ReadMe." ou "Falha ao conectar ao ReadMe. Por favor, verifique sua Chave de API." | Verifique a chave e conecte novamente. |
| "Nenhuma categoria de guia ainda" / "Crie uma categoria de guia no ReadMe para publicar aqui." | Adicione uma categoria aos seus Guias no ReadMe, depois reabra a aba Publicar. |
| "Escolha uma categoria primeiro." ou "Escolha uma categoria do ReadMe para publicar este guia." | Escolha uma categoria de guia antes de publicar. |
| "Você pode visualizar este item, mas não publicá-lo. Peça a alguém que possa editá-lo." | Você precisa de acesso de edição ao artigo para publicá-lo. |
| "Chave de API não encontrada. Por favor, reconecte o ReadMe." | Conecte o ReadMe novamente 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 depois publique. |
| "Não foi possível publicar no ReadMe" com uma mensagem do ReadMe, como uma sobre o slug ou categoria | O ReadMe recusou o guia. Verifique se a categoria ainda existe, ou renomeie o artigo e clique em Tente novamente. |
| "Falha ao atualizar o guia no ReadMe" | O guia que você tentou atualizar foi excluído ou renomeado no ReadMe. Publique novamente e escolha Criar um novo artigo. |
| "Falha ao publicar no ReadMe. Por favor, tente novamente." | Clique em Tente novamente. Se continuar falhando, conecte novamente com uma chave nova. |