Lucas Santos for Microsoft Azure

Posted on Mar 25, 2020 • Edited on Jul 31, 2020

Escrita Eficiente de Artigos com VSCode

#markdown #vscode #latex #writing

Photo by Kaitlyn Baker on Unsplash

Eu escrevo desde que me conheço por gente e, como muitos devem ter percebido, eu gosto bastante de escrever artigos. Eu acredito que artigos são uma das formas mais importantes de comunicação porque elas resistem um longo tempo e podem atingir muito mais gente se compararmos com uma palestra, por exemplo.

Muitas pessoas me perguntam quais são as ferramentas que uso para escrever meus artigos e quais são as técnicas e outras dicas que podemos utilizar para escrever artigos de forma simples e rápida, vamos deixar as técnicas e dicas para outro artigo que vou publicar mais a frente e, neste artigo, vamos nos focar nas ferramentas.

Conheça suas ferramentas

Durante todos os anos que venho escrevendo artigos para Internet, passei por diversas ferramentas, a primeira delas foi o Notepad++, depois o Word, depois comecei a usar diretamente o editor do Medium e usei este editor um bom tempo, porém o grande problema do Medium é que, além de ter uma série de conteúdos pagos inacessíveis, ele também não suporta Markdown.

Por que Markdown?

O Markdown é uma das invenções mais interessantes dos últimos anos. Ele permite que você edite textos de forma rápida e simples, somente colocando marcações para formatar o texto, e como isso nos ajuda? Simplesmente porque podemos fazer Markdown em QUALQUER editor de texto.

Isso abre portas para que não precisemos de um editor complexo como o Word para criar nossos artigos e isso é muito útil porque podemos escrever sempre que tivermos uma ideia, por exemplo, em um transporte público ou qualquer coisa do tipo, usando somente o editor do celular ou tablet, o sistema de notas que vem instalado em todos os celulares ou, se estivermos em um computador que não seja nosso, podemos usar até os editores de texto padrões como o Notepad no Windows ou o TextEdit no Mac e vamos ter o mesmo texto enriquecido com links, formatação e tudo mais.

Simplificando as ideias

Depois de descobrir o Markdown em meados de 2012 eu me apaixonei pela simplicidade e resolvi procurar editores mais simples que pudessem me ajudar. Cheguei a usar alguns editores até que descobri o VS Code em 2015. Porém, na época, ele ainda não tinha muitas extensões e o ele não suportava exportação para outros tipos de arquivo, por exemplo, PDF ou Doc (nenhum suportava).

Até que, no início do ano passado, descobri uma extensão para o VS Code que me fez mudar completamente de ideia. Essa extensão é o Markdown Preview Enhanced.

Desde então não uso nenhuma outra ferramenta para poder editar meus artigos, somente o VS Code com a extensão do Markdown Preview Enhanced.

Markdown Preview Enhanced

O MPE possui uma série de vantagens quando estamos editando um markdown, vamos passar pelas principais aqui neste artigo e vamos entender o porquê desta ferramenta ser tão boa, veja alguns exemplos:

Preview em editor lateral com sincronização do scroll
Importação de arquivos externos
Execução de código direto no Markdown com Code Blocks
Exportação para vários tipos de arquivo com Pandoc
Permite transformar seu texto em slides de uma apresentação
Suporta LaTeX
Gera flowcharts e outros tipos de gráficos como texto
Suporte a Front Matter
etc...

Mas antes, vamos aprender como inicializar com ela.

Instalação e primeiros passos

Primeiramente, se você não tem ainda o VS Code, baixe e instale o cliente para o seu sistema operacional preferido.

Após instalar o VS Code, vá até a lateral e selecione o painel de extensões, que é representado por um ícone com 4 quadrados:

Pesquise Markdown Preview Enhanced na caixa de pesquisa:

Clique no botão Install que deve aparecer no local aonde, na foto anterior, está o ícone da engrenagem.

No meu editor a extensão já está instalada, portanto não temos o botão install aparecendo abaixo

Pronto! Não precisamos fazer mais nada :D

Você também pode ir diretamente ao site do marketplace da extensão e instalar pelo seu browser

Escrevendo Arquivos Markdown

Para começar basta criar um novo arquivo no VS Code, quando o arquivo se abrir, podemos apertar a sequência CMD + SHIFT + P (se você estiver usando Windows, então será CTRL + SHIFT + P) e digitar language:

Isso fará com que uma janela se abra, basta digitar markdown ou md e pronto!

Se você já abriu um arquivo em Markdown (no formato .md) o VS Code já vai identificar a linguagem diretamente :)

Para podermos ativar a extensão basta trazer o diálogo CTRL/CMD + SHIFT + P novamente e digitar "Open Preview to the Side", então apertar Enter, isto deverá abrir uma prévia do Markdown Preview Enhanced lateralmente:

É importante que façamos isso, caso contrário a extensão não será ativada!

A partir daqui, vou assumir que todos já sabem o que é o Markdown, portando vamos focar diretamente nas funcionalidades do Markdown Preview Enhanced.

Se você ainda não sabe o que é Markdown, sugiro que dê uma olhada na documentação para entender melhor antes de continuar!

Funcionalidades do MPE

Vamos passar pela lista de funcionalidades do Markdown Preview Enhanced mostrando como podemos utilizar cada uma, lembrando que o site oficial tem mais informações sobre o uso da extensão!

Importando arquivos externos

Uma das maiores dificuldades que temos quando criamos um texto em Markdown é importar imagens e outras coisas externas aos nossos arquivos, por exemplo, uma tabela CSV. Com o MPE fica fácil importarmos todo o tipo de arquivo já que podemos utilizar a sintaxe @import "nome do arquivo"

Os formatos suportados são:

Imagens (jpg, png, gif, apng, svg e bmp)
CSV (vai ser convertido em uma tabela em markdown)
.mermaid
.dot
.plantuml ou .puml
.html
.js (vai ser incluido em um bloco <script>)
.less ou .css (será incluído como style na página)
.pdf
.md

Temos algumas opções bacanas como, por exemplo:

Escolher o tamanho das nossas imagens com: @import "image.png" {width="300px" height="200px" alt="my image"}
Importar arquivos online com @import "https://url.com", o que abre espaço para que possamos puxar um gist ou um código terceiro diretamente
Renderizar um código como um code block com `@import "test.json" {code_block=true class="line-numbers"}

Conversão on save

Uma das maiores dificuldades que tive foi que, por escrever para outros portais diferentes do Dev.to, as pessoas não aceitavam o formato Markdown, então eu tinha que converter o arquivo em um formado do Word ou então em PDF para poder enviar para o editorial. Antigamente eu fazia esta tarefa através do Pandoc, que é um conversor multi-propósito, porém com o tempo isso começou a ficar cansativo e esgotante, então comecei a procurar alternativas em editores que possuissem diretamente essa funcionalidade.

Novamente o Markdown Preview Enhanced me salvou, pois ele já possuía isso direto da instalação! Basta que coloquemos um Front Matter no arquivo e está tudo certo:

Basta que adicionemos as seguintes linhas antes de qualquer coisa no arquivo precedidas por --- e sucedidas por ---:

---
title: "VS Code is Awesome!"
author: "Lucas Santos"
export_on_save:
  pandoc: true
output:
  pdf_document:
    path: ./file/path.pdf
---

Não é necessário colocar a instrução path, se ela for omitida o Markdown Preview Enhanced irá exportar o arquivo PDF diretamente no local atual.

---
title: "VS Code is Awesome!"
author: "Lucas Santos"
export_on_save:
  pandoc: true
output: pdf_document
---

Por padrão o Markdown Preview Enhanced vem com suporte out-of-the-box do Pandoc à exportação de arquivos PDF, Word, RTF e Beamer. Porém o Pandoc em si tem suportes a muitos outros arquivos e você pode configurar a extensão para exportar para outros formatos

LaTeX

Quem já precisou escrever um artigo científico ou então um artigo que envolvia muita matemática deve estar muito familiarizado com este tipo de formato de arquivo. O LaTeX é uma outra linguagem de marcação que permite que escrevamos conteúdos matemáticos de forma muito mais simples e direta, ficando com um resultado muito mais bonito.

O Markdown já foi integrado com o LaTeX em várias outras extensões, porém somente o Markdown Preview Enhanced faz tudo em uma só.

Para podermos escrever o formato inline basta colocar a notação entre $$, enquanto para escrever em formato de bloco podemos optar por colocar tudo dentro de uma sintaxe `math ou então de
{% raw %}
ntro de blocos $$.

Veja as demais opções na documentação

ToC - Table of Contents e Footnotes

Muitos dos meus artigos possuem um sumário, esses sumários são gerados por outra funcionalidade chamada ToC, que é bem simples de ser utilizada, basta utilizar o mesmo atalho CTRL/CMD + SHIFT + P e digitar TOC que o Markdown Preview Enhanced vai buscar todos os seus títulos com # até 6 níveis (configurável) e vai criar um bonito sumário:

É necessário realizar um salvamento do arquivo para o ToC aparecer pela primeira vez

Além disso é possível adicionar notas de rodapé para facilitar a busca de referências:

Codeblocks

Uma outra funcionalidade muito legal é a funcionalidade que chamamos de code blocks, que é a capacidade de criarmos código executável dentro do próprio Markdown. Isso é muito útil quando estamos querendo fazer uma aula ou então um tutorial, porque podemos fazer com que o código seja executado e seu resultado seja exibido logo abaixo:

Podemos executar código de qualquer tipo desde que, em sua máquina, haja o executável correto.

Por padrão a execução de scripts fica desativada por padrão e precisa ser ativada através da opção enableScriptExecution dentro das configurações do seu VSCode. Veja a documentação para mais detalhes.

Além de executar código que dá um output de texto podemos também desenhar gráficos, usando o Python, por exemplo, conforme as imagens abaixo (presentes na documentação):

Com Python

Com JavaScript usando Plotly

Diagramas

O recurso de code blocks também permite que o Markdown Preview Enhanced crie diagramas de vários tipos! Os diagramas suportados são:

Flowcharts
Diagramas de sequência
Diagramas do Mermaid (múltiplos)
PlantUML
WaveDrom
Graphviz
Vega
Ditaa

Para manter o artigo curto, vou mostrar apenas como podemos criar um diagrama de grafos de forma bastante simples, para todos os demais diagramas você pode consultar a documentação oficial:

Slides

Agora chegamos a parte mais legal de todas. Além de escrever artigos, eu costumo ir em alguns eventos para fazer palestras, e o Markdown Preview Enhanced permite que eu escreva meus slides diretamente como um conteúdo em Markdown!

Além disso todas as apresentações são diretamente feitas utilizando o reveal.js que é uma biblioteca sensacional para apresentações em JavaScript e HTML.

Podemos simplesmente adicionar a notação  antes de qualquer slide novo ou então utilizar o comando CTRL/CMD + SHIFT + P e procurar por "insert new slide", isso fará a inserção automáticamente!

No reveal.js podemos adicionar slides para baixo de forma vertical, basta incluir a tag .

Podemos mudar o tema através da tag theme no front matter, e também podemos adicionar notas de apresentador através da tag enableSpeakerNotes:

`

presentation:
enableSpeakerNotes: true

theme: league.css

A documentação possui uma lista de todos os temas e opções disponíveis para esta funcionalidade. Você também pode acessar esta demo para ver as opções específicas dessa funcionalidade.

Bônus: Trabalhando com imagens

Um dos maiores problemas que temos quando estamos escrevendo Markdown é que as imagens precisam ser colocadas de forma que apontem para um arquivo ou uma URL. Eu, particularmente, não gosto de ficar salvando um monte de imagens no meu computador, geralmente eu uso a própria ferramenta de clip do sistema operacional para tirar uma foto da tela e manter na memória, mas aí eu não posso colar no meu texto... Como fazemos?

Felizmente existe uma outra extensão chamada Paste Image que faz um par incrível com o Markdown Preview Enhanced, ela permite que você cole as imagens copiadas para a memória direto em um formato Markdown já salvando as mesmas na pasta do arquivo automaticamente.

Veja como ela funciona com este gif direto da página da extensão:

Juntando várias extensões podemos conquistar o mundo!

Conclusão

O Markdown Preview Enhanced sem dúvida foi um salvador de vidas para mim neste último ano e eu considero uma das melhores extensões para o VS Code de todos os tempos.

Você tem outras sugestões de extensão? Usa outras ferramentas? Conta nos comentários! Ou então me chama nas minhas redes sociais :D

Não deixe de acompanhar mais do meu conteúdo no meu blog e se inscreva na newsletter para receber notícias semanais!

Website	GitHub	Facebook	LinkedIn	Twitter

Top comments (6)

Gabriel Machado • Apr 10 '20

Excelente dica Lucas! Eu gosto de usar também um corretor de ortografia. O Code Spell Checker funciona bem e é possível adicionar outras línguas (como português).