{"id":23904,"date":"2017-06-05T20:43:19","date_gmt":"2017-06-05T23:43:19","guid":{"rendered":"https:\/\/blog.locaweb.com.br\/?p=23904"},"modified":"2022-08-31T16:48:05","modified_gmt":"2022-08-31T19:48:05","slug":"usando-mermaid-para-criar-diagramas-no-gitbook","status":"publish","type":"post","link":"https:\/\/www.locaweb.com.br\/blog\/temas\/codigo-aberto\/usando-mermaid-para-criar-diagramas-no-gitbook\/","title":{"rendered":"Usando Mermaid para criar diagramas no Gitbook"},"content":{"rendered":"<p><span style=\"font-weight: 400\">Na Locaweb come\u00e7amos a usar o <\/span><a href=\"https:\/\/www.gitbook.com\/\"><i><span style=\"font-weight: 400\">Gitbook<\/span><\/i><\/a><span style=\"font-weight: 400\"> para algumas documenta\u00e7\u00f5es h\u00e1 certo tempo. N\u00e3o participei da decis\u00e3o do uso dessa ferramenta, mas posso listar alguns pontos positivos dela:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400\"><span style=\"font-weight: 400\">Poder escrever os textos em markdown (que s\u00e3o convertidos automaticamente para html na publica\u00e7\u00e3o)<\/span><\/li>\n<li style=\"font-weight: 400\"><span style=\"font-weight: 400\">A busca por palavras \u00e9 muito r\u00e1pida! (<\/span><a href=\"https:\/\/fabioperrella.gitbooks.io\/teste\/content\/\"><span style=\"font-weight: 400\">neste link<\/span><\/a><span style=\"font-weight: 400\"> criei uma documenta\u00e7\u00e3o de exemplo, basta procurar por \u201canswer\u201d para ver a velocidade)<\/span><\/li>\n<li style=\"font-weight: 400\"><span style=\"font-weight: 400\">Existem v\u00e1rios plugins dispon\u00edveis. Por exemplo, estamos usando esses: [ &#8220;mermaid&#8221;, &#8220;toggle-chapters&#8221;, &#8220;toc&#8221;, &#8220;callouts&#8221; ]<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400\">Nesse post vou focar no uso do plugin <\/span><b><i>Mermaid<\/i><\/b><span style=\"font-weight: 400\"> e n\u00e3o pretendo detalhar como usar o <\/span><i><span style=\"font-weight: 400\">Gitbook<\/span><\/i><span style=\"font-weight: 400\">, que pode ser visto <\/span><a href=\"https:\/\/github.com\/GitbookIO\/gitbook\/blob\/master\/docs\/setup.md\"><span style=\"font-weight: 400\">aqui<\/span><\/a><span style=\"font-weight: 400\">. Outra op\u00e7\u00e3o \u00e9 usar a vers\u00e3o \u201cna nuvem\u201d. Para isso basta criar uma conta no <\/span><a href=\"https:\/\/www.gitbook.com\"><span style=\"font-weight: 400\">gitbook.com<\/span><\/a><span style=\"font-weight: 400\">.<\/span><\/p>\n<p><span style=\"font-weight: 400\">Na \u00e1rea de desenvolvimento de software frequentemente precisamos desenhar diagramas para documentar algo. Isso pode ajudar muito o entendimento dos sistemas, com uso de diagramas de sequ\u00eancia ou de estado, por exemplo.<\/span><\/p>\n<p><span style=\"font-weight: 400\">J\u00e1 usei diversas ferramentas para desenhar diagramas, mas vejo o mesmo problema para todas elas. Quando precisamos editar alguma coisa \u00e9 necess\u00e1rio abrir o arquivo original no editor para depois exportar a imagem para PNG ou Jpeg e, \u00e0s vezes, j\u00e1 n\u00e3o temos mais o arquivo original ou at\u00e9 o programa para edi\u00e7\u00e3o. Assim fica imposs\u00edvel editar!<\/span><\/p>\n<p><span style=\"font-weight: 400\">H\u00e1 pouco tempo conheci o <\/span><a href=\"https:\/\/knsv.github.io\/mermaid\/\"><i><span style=\"font-weight: 400\">Mermaid<\/span><\/i><\/a><span style=\"font-weight: 400\">, uma \u201clinguagem\u201d para especificar diagramas. Com ele, conseguimos fazer diagramas de sequ\u00eancia, de fluxo, de gantt, etc.<\/span><\/p>\n<p><span style=\"font-weight: 400\">Na Locaweb fizemos alguns diagramas de sequ\u00eancia para facilitar o entendimento das integra\u00e7\u00f5es entre sistemas. No site do <\/span><i><span style=\"font-weight: 400\">Mermaid<\/span><\/i><span style=\"font-weight: 400\">, a especifica\u00e7\u00e3o para esse tipo de diagrama se encontra <\/span><a href=\"https:\/\/knsv.github.io\/mermaid\/#notes\"><span style=\"font-weight: 400\">neste link<\/span><\/a><span style=\"font-weight: 400\">.<\/span><\/p>\n<p><span style=\"font-weight: 400\">\u00c9 poss\u00edvel editar em modo \u201clive\u201d no pr\u00f3prio site do <\/span><i><span style=\"font-weight: 400\">Mermaid <\/span><\/i><span style=\"font-weight: 400\">&#8211; <\/span><a href=\"https:\/\/knsv.github.io\/mermaid\/live_editor\/\"><span style=\"font-weight: 400\">por aqui<\/span><\/a><span style=\"font-weight: 400\">.<\/span><\/p>\n<p><span style=\"font-weight: 400\">Outro jeito de se testar \u00e9 usando o <\/span><a href=\"https:\/\/hackmd.io\"><span style=\"font-weight: 400\">hackmd.io<\/span><\/a><span style=\"font-weight: 400\">. Basta criar um documento <\/span><i><span style=\"font-weight: 400\">markdown<\/span><\/i><span style=\"font-weight: 400\"> e colocar o c\u00f3digo do diagrama dentro do bloco <\/span><i><span style=\"font-weight: 400\">Mermaid<\/span><\/i><span style=\"font-weight: 400\">, como o exemplo abaixo:<\/span><\/p>\n<pre class=\"brush: plain\">```mermaid\ngraph LR;\nFeature--&gt;B[Possui pai?];\nB-- n\u00e3o --&gt;C[Product];\nB-- sim --&gt;D[\"O pai \u00e9 processado?\"];\n```\n<\/pre>\n<p><span style=\"font-weight: 400\">Esse c\u00f3digo gera o seguinte diagrama:<\/span><\/p>\n<p><a href=\"https:\/\/www.locaweb.com.br\/blog\/wp-content\/uploads\/2017\/06\/diagrama-mermaid-1.png\"><img decoding=\"async\" class=\"alignnone size-full wp-image-23907\" src=\"https:\/\/www.locaweb.com.br\/blog\/wp-content\/uploads\/2017\/06\/diagrama-mermaid-1.png\" alt=\"\" width=\"495\" height=\"178\" \/><\/a><\/p>\n<p><span style=\"font-weight: 400\">Voltando ao <\/span><b><i>Gitbook<\/i><\/b><span style=\"font-weight: 400\">, para usar o<\/span><i><span style=\"font-weight: 400\"> Mermaid<\/span><\/i><span style=\"font-weight: 400\">, basta adicionar o plugin <\/span><b><i>Mermaid<\/i><\/b><span style=\"font-weight: 400\"> na lista de plugins no arquivo <\/span><b><i>book.json<\/i><\/b><span style=\"font-weight: 400\">, como a seguir:<\/span><\/p>\n<pre class=\"brush: json;\">{\n  \"plugins\" : [ \"mermaid\" ]\n}\n<\/pre>\n<p><span style=\"font-weight: 400\">Mais detalhes sobre esse plugin podem ser vistos na <\/span><a href=\"https:\/\/github.com\/JozoVilcek\/gitbook-plugin-mermaid\"><span style=\"font-weight: 400\">em sua p\u00e1gina<\/span><\/a><span style=\"font-weight: 400\">.<\/span><\/p>\n<p><span style=\"font-weight: 400\">Diferentemente do<\/span><i><span style=\"font-weight: 400\"> hackmd<\/span><\/i><span style=\"font-weight: 400\">, o c\u00f3digo do diagrama deve ficar dentro do bloco {% mermaid %} como abaixo:<\/span><\/p>\n<pre class=\"brush: plain;\">{% mermaid %}\ngraph LR;\nFeature--&gt;B[Possui pai?];\nB-- n\u00e3o --&gt;C[Product];\nB-- sim --&gt;D[\"O pai \u00e9 processado?\"];\n{% endmermaid %}\n<\/pre>\n<p>Espero que com essas dicas, voc\u00ea possa come\u00e7ar a criar mais diagramas para documentar suas aplica\u00e7\u00f5es. Qualquer d\u00favida, comenta a\u00ed!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Na Locaweb come\u00e7amos a usar o Gitbook para algumas documenta\u00e7\u00f5es h\u00e1 certo tempo. N\u00e3o participei da decis\u00e3o do uso dessa ferramenta, mas posso listar alguns pontos positivos dela: Poder escrever os textos em markdown (que s\u00e3o convertidos automaticamente para html na publica\u00e7\u00e3o) A busca por palavras \u00e9 muito r\u00e1pida! (neste link criei uma documenta\u00e7\u00e3o de [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":23918,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[5],"tags":[],"class_list":["post-23904","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-codigo-aberto"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/posts\/23904","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/comments?post=23904"}],"version-history":[{"count":1,"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/posts\/23904\/revisions"}],"predecessor-version":[{"id":36484,"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/posts\/23904\/revisions\/36484"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/media\/23918"}],"wp:attachment":[{"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/media?parent=23904"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/categories?post=23904"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.locaweb.com.br\/blog\/wp-json\/wp\/v2\/tags?post=23904"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}