Integração com ReadMe

Publique guias de desenvolvedor no ReadMe a partir de uma gravação de tela

Sua referência de API explica os endpoints. Seus guias explicam tudo ao redor deles. Grave um fluxo uma vez, e a Clevera escreve o guia com capturas de tela e o publica no seu hub de desenvolvedor ReadMe, na categoria de guia que você escolher.

Começar gratuitamente Ler o guia do ReadMe

Guias no seu hub de desenvolvedor

Callouts e abas de código do ReadMe

Capturas de tela enviadas ao ReadMe

Atualização por endereço

O que você pode fazer

Os guias sobre sua API,
escritos a partir do próprio produto.

Desenvolvedores chegam ao seu hub ReadMe para começar: criar uma conta, encontrar a chave de API, configurar um webhook, testar no dashboard. Essas páginas são capturas de tela e cliques, e ficam obsoletas toda vez que o dashboard muda. A Clevera as escreve a partir de uma gravação.

Primeiros passos, mostrados clique a clique

Grave o caminho desde o cadastro até a primeira chamada de API no seu dashboard. A Clevera o transforma em um guia com passos numerados e uma captura de tela para cada um.

Código continua sendo código

Blocos de código mantêm sua linguagem e título. Abas que contêm apenas código tornam-se abas de código do ReadMe, para que exemplos em cURL, Node e Python fiquem lado a lado.

Arquivado onde os desenvolvedores navegam

Escolha uma categoria de guia, como Primeiros Passos ou Webhooks, e o guia aparecerá lá na seção de Guias do seu hub.

Capturas de tela hospedadas pelo ReadMe

As capturas de tela são enviadas ao ReadMe, para que o guia continue funcionando mesmo se você excluir o artigo na Clevera.

Atualize guias quando o dashboard mudar

Grave o fluxo novamente, atualize o artigo na Clevera e publique de novo. A Clevera encontra o guia pelo seu endereço e o sobrescreve no local.

Seguro com o formato de página do ReadMe

Chaves e colchetes no seu texto são escapados, para que placeholders como {API_KEY} apareçam exatamente como escritos.

Como funciona

Da gravação ao guia no ReadMe
em quatro passos.

Cole a chave de API do seu projeto uma vez. Depois disso, qualquer artigo no workspace pode se tornar um guia no seu hub.

1
Conecte seu projeto
Copie uma chave de API da Configuração do seu projeto ReadMe, cole-a na Clevera e deixe que ela verifique a chave.
2
A Clevera escreve o guia
A partir da sua gravação de tela, a Clevera escreve o guia: passos, capturas de tela, callouts e código.
3
Escolha uma categoria de guia
Em Compartilhar, abra Publicar, escolha a categoria do guia e clique em Publicar no ReadMe.
4
Está nos seus Guias
O guia aparece sob essa categoria na versão principal do seu projeto, em um endereço criado a partir do seu título.

Veja na Clevera

Publicando no ReadMe,
a partir da janela Compartilhar do artigo.

Nada de colar no editor do ReadMe, nada de enviar capturas de tela uma por uma, nada de reescrever callouts na sintaxe do ReadMe. A janela Compartilhar publica o guia para você.

Uma chave, um projeto

No ReadMe, abra a Configuração → Chaves de API do seu projeto e copie uma chave. Cole-a na Clevera e clique em Verificar chave; a Clevera mostra o projeto ao qual a chave pertence antes de salvar qualquer coisa.

A chave dá acesso total a esse projeto, portanto, mantenha-a privada. Para publicar em um projeto diferente, reconecte com a chave desse projeto.

A janela Conectar ReadMe na Clevera com uma chave de API aceita e o projeto Acme Developers — Conecte o ReadMe: a chave de API aceita e o projeto Acme Developers encontrado.

Escolha a categoria do guia

Projeto mostra o hub conectado. Escolha uma Categoria de guia: o guia vai para a seção de Guias, sob essa categoria. Ainda não tem categorias? Crie uma no ReadMe primeiro.

O endereço vem do título, então “Crie sua primeira chave de API” torna-se /docs/create-your-first-api-key.

Publicar no ReadMe na Clevera: o projeto Acme Developers e a categoria de guia Getting Started — Publicar no ReadMe: o projeto Acme Developers e a categoria de guia Primeiros Passos.

Preenchido para você

O que chega ao seu hub de desenvolvedor
e o que você decide.

A Clevera converte o artigo para o formato de página do próprio ReadMe, para que o guia use os callouts, blocos de código e embeds do ReadMe e possa ser editado no ReadMe como qualquer outro.

Categoria de guiaVocê escolhe: Qualquer categoria nos Guias do seu projeto. A Clevera publica na versão principal (estável) da sua documentação.
Título e endereçoDefinidos para você: O título do artigo e um endereço criado a partir dele sob /docs/. Se esse endereço já estiver em uso, o ReadMe dá ao novo guia um endereço ligeiramente diferente.
VisibilidadeVocê decide: A Clevera não a define, então um novo guia recebe o padrão do ReadMe: público. Altere-a no ReadMe logo após publicar se quiser revisar primeiro. Atualizações mantêm a visibilidade que o guia já possui.
CalloutsConvertidos para você: Callouts do ReadMe com seus títulos: 📘 para informações e notas, 👍 para dicas e sucesso, 🚧 para avisos e ❗️ para perigo.
Código e abasConvertidos para você: Blocos de código mantêm sua linguagem e título. Abas que contêm apenas código tornam-se abas de código do ReadMe; outras abas tornam-se seções rotuladas.
Passos e alternadoresConvertidos para você: Passos numerados tornam-se uma lista numerada com o título de cada passo em negrito. Seções recolhíveis tornam-se seções expansíveis do ReadMe.
Capturas de tela e vídeosDefinidos para você: Capturas de tela são enviadas ao ReadMe com suas legendas. Vídeos colocados no artigo tornam-se embeds do ReadMe; um vídeo da Clevera precisa estar com o link de compartilhamento ativado.

Configuração

Configure a integração com o ReadMe
em cerca de dois minutos.

Você precisa de um workspace Clevera no plano Pro ou superior, e um projeto ReadMe no ReadMe Refactored com pelo menos uma categoria de guia. O proprietário do workspace ou um Administrador conecta o ReadMe uma vez; depois disso, qualquer pessoa que possa editar um artigo pode publicá-lo. A publicação não consome créditos.

1
Copie uma chave de API do ReadMe
No seu projeto ReadMe, abra Configuração → Chaves de API e copie uma chave, ou crie uma se a lista estiver vazia.
2
Conecte o ReadMe na Clevera
Abra o menu do workspace, escolha Integrações, encontre ReadMe e clique em Conectar. Cole a chave em Chave de API e clique em Verificar chave.
3
Confirme o projeto
Quando você vir “Chave aceita.” e seu projeto sob Sites para publicar, clique em Conectar.
4
Publicar um artigo
No editor de artigos, clique em Compartilhar, abra Publicar, clique no bloco do ReadMe, escolha uma Categoria de guia e clique em Publicar no ReadMe.
5
Abra-o no ReadMe
Quando você vir “Publicado no ReadMe.”, clique em Abrir no ReadMe, e defina a visibilidade do guia se ele ainda não deveria ser público.

Perguntas sobre a integração com o ReadMe

Funciona com projetos no ReadMe Refactored, porque a Clevera usa a API atual (v2) do ReadMe. Projetos ainda na plataforma antiga do ReadMe não podem ser conectados.

Não. A Clevera publica na seção de Guias: as páginas de primeiros passos, tutoriais e dashboard ao redor da sua referência. Suas páginas de referência de API permanecem como estão.

Na versão principal (estável) dos Guias do seu projeto.

Sim, por padrão. A Clevera não define uma visibilidade, então o ReadMe usa seu padrão, que é público. Oculte o guia no ReadMe logo após publicar se quiser revisá-lo primeiro; atualizações posteriores mantêm essa visibilidade.

A Clevera procura por um guia com o mesmo endereço em qualquer lugar nos seus Guias e mostra “Este artigo já está no ReadMe.” Atualize-o para sobrescrever o guia no mesmo endereço, ou crie um novo guia com um novo título. Alterações feitas no ReadMe desde a última publicação são sobrescritas por uma atualização.

Não. A publicação é unidirecional, da Clevera para o ReadMe. Um guia no ReadMe não muda quando você edita o artigo na Clevera até que você publique novamente, portanto, mantenha o artigo na Clevera como a fonte para qualquer guia que mostre seu dashboard.

O proprietário do workspace ou um Administrador conecta o ReadMe uma vez com a chave do projeto. Depois disso, qualquer pessoa que possa editar um artigo pode publicá-lo no ReadMe, sem nunca ver a chave. Alguém que apenas pode visualizar o artigo não pode publicá-lo.

Sim, esse é um recurso separado e gratuito. Veja a importação do ReadMe e como a Clevera se compara ao ReadMe. Esta integração é para equipes que mantêm seu hub de desenvolvedor no ReadMe.

Publicar no ReadMe faz parte dos planos Pro e Custom da Clevera e não consome créditos; criar o artigo consome créditos normalmente. Veja preços.