Escrita Eficiente de Artigos com VSCode
Tags: markdown, vscode, latex, writing
Published: 2020-03-25 20:56:55

_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](https://dev.to/khaosdoctor). 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](https://www.microsoft.com/download/office.aspx?WT.mc_id=devto-blog-ludossan), 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](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan).

## Por que Markdown?

O [Markdown](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan) é 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](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan) em __QUALQUER__ editor de texto.

Isso abre portas para que não precisemos de um editor complexo como o [Word](https://www.microsoft.com/download/office.aspx?WT.mc_id=devto-blog-ludossan) 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](https://microsoft.com/windows/?WT.mc_id=devto-blog-ludossan) 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](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan) 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](https://marketplace.visualstudio.com/?WT.mc_id=blog-devto-ludossan) para o [VS Code](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan) que me fez mudar completamente de ideia. Essa extensão é o [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan).

![](https://dev-to-uploads.s3.amazonaws.com/i/7w5nsb4xigxzk1tlrr30.png)

Desde então não uso nenhuma outra ferramenta para poder editar meus artigos, somente o [VS Code](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan) com a extensão do [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan).

# Markdown Preview Enhanced

O [MPE](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) 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](https://docs.microsoft.com/quantum/supported-macros?WT.mc_id=blog-devto-ludossan)
- 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](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan), baixe e instale o cliente para o seu sistema operacional preferido.

Após instalar o [VS Code](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan), vá até a lateral e selecione o painel de extensões, que é representado por um ícone com 4 quadrados:

![Icone de extensões](https://dev-to-uploads.s3.amazonaws.com/i/x52m61xgvxjwvgkgdgyu.png)

Pesquise [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) na caixa de pesquisa:

![](https://dev-to-uploads.s3.amazonaws.com/i/s0drs66hvr193hinghom.png)

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](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) e instalar pelo seu browser

## Escrevendo Arquivos Markdown

Para começar basta [criar um novo arquivo](https://code.visualstudio.com/docs/getstarted/tips-and-tricks?WT.mc_id=blog-devto-ludossan) no [VS Code](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan), quando o arquivo se abrir, podemos apertar a sequência `CMD + SHIFT + P` (se você estiver usando [Windows](https://microsoft.com/windows/?WT.mc_id=devto-blog-ludossan), então será `CTRL + SHIFT + P`) e digitar `language`:

![](https://dev-to-uploads.s3.amazonaws.com/i/5vsvwmctyj5ugthni9dy.png)

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

![](https://dev-to-uploads.s3.amazonaws.com/i/sp4vased4iyopwvdp3f1.png)

> Se você já abriu um arquivo em Markdown (no formato `.md`) o [VS Code](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan) 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](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) lateralmente:

![](https://dev-to-uploads.s3.amazonaws.com/i/rsugx3tocfb6et3ssuxt.png)

> É 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](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan), portando vamos focar diretamente nas funcionalidades do [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan).

> Se você ainda não sabe o que é Markdown, sugiro que dê uma olhada [na documentação](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan) para entender melhor antes de continuar!

# Funcionalidades do MPE

Vamos passar pela lista de funcionalidades do [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) mostrando como podemos utilizar cada uma, lembrando que [o site oficial](https://shd101wyy.github.io/markdown-preview-enhanced) 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](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan) é importar imagens e outras coisas externas aos nossos arquivos, por exemplo, uma tabela [CSV](https://docs.microsoft.com/sharepointmigration/how-to-format-your-csv-file-for-data-content-migration?WT.mc_id=blog-devto-ludossan). Com o MPE fica fácil importarmos todo o tipo de arquivo já que podemos utilizar a sintaxe `@import "nome do arquivo"`

![](https://dev-to-uploads.s3.amazonaws.com/i/gyalqr3d2exfwteq165w.gif)

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](https://gist.github.com/?WT.mc_id=blog-devto-ludossan) 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](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan), então eu tinha que converter o arquivo em um formado do [Word](https://www.microsoft.com/download/office.aspx?WT.mc_id=devto-blog-ludossan) ou então em PDF para poder enviar para o editorial. Antigamente eu fazia esta tarefa através do [Pandoc](https://pandoc.org/), 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](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) me salvou, pois ele já possuía isso direto da instalação! Basta que coloquemos um Front Matter no arquivo e está tudo certo:

![](https://dev-to-uploads.s3.amazonaws.com/i/8kkndtnuhfa57u2eutsq.gif)

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](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) 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](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) 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](https://shd101wyy.github.io/markdown-preview-enhanced/#/pandoc) 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](https://marketplace.visualstudio.com/search?term=latex%20markdown&target=VSCode&category=All%20categories&sortBy=Relevance&WT.mc_id=blog-devto-ludossan), porém somente o [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) faz tudo em uma só.

![](https://dev-to-uploads.s3.amazonaws.com/i/s7n1ocfsf280jgnehoaq.gif)

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 dentro de blocos `$$`.

> Veja as demais opções na [documentação](https://shd101wyy.github.io/markdown-preview-enhanced/#/math)

## ToC - Table of Contents e Footnotes

Muitos dos meus artigos possuem um [sumário](https://dev.to/khaosdoctor/o-guia-definitivo-da-organizacao-pessoal-parte-1-44ea#sumario), 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](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) vai buscar todos os seus títulos com `#` até 6 níveis (configurável) e vai criar um bonito sumário:

![](https://dev-to-uploads.s3.amazonaws.com/i/96r1f6sxh6mkmvm76qrk.gif)

> É 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:

![](https://dev-to-uploads.s3.amazonaws.com/i/882rp4iql5pupshn5ldc.gif)

## 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](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan). 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:

![](https://dev-to-uploads.s3.amazonaws.com/i/1vq0xop8e3evt9xiufqc.gif)

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](https://shd101wyy.github.io/markdown-preview-enhanced/#/code-chunk) 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__

![](https://user-images.githubusercontent.com/1908863/28716704-4009d43a-7364-11e7-9e46-889f961e5afd.png)

__Com JavaScript usando Plotly__

![](https://user-images.githubusercontent.com/1908863/31829580-526a0c06-b583-11e7-82f2-09ea7a0b9672.png)

## Diagramas

O recurso de code blocks também permite que o [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) 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](https://shd101wyy.github.io/markdown-preview-enhanced/#/diagrams):

![](https://dev-to-uploads.s3.amazonaws.com/i/puzhdsmb1555td0p1pjb.gif)

## 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](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) permite que eu escreva meus slides diretamente como um conteúdo em [Markdown](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan)!

Além disso todas as apresentações são diretamente feitas utilizando o [reveal.js](https://github.com/hakimel/reveal.js) que é uma biblioteca sensacional para apresentações em [JavaScript](https://docs.microsoft.com/visualstudio/javascript/tutorial-nodejs?view=vs-2019&WT.mc_id=blog-devto-ludossan) e HTML.

![](https://dev-to-uploads.s3.amazonaws.com/i/qx86wwa3vks70mqhlw5p.gif)

Podemos simplesmente adicionar a notação `<!-- slide -->` 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 `<!-- slide vertical=true -->`.

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](https://dev.to/khaosdoctor/o-guia-definitivo-da-organizacao-pessoal-parte-1-44ea) possui uma lista de todos os temas e opções disponíveis para esta funcionalidade. Você também pode acessar [esta demo](https://rawgit.com/shd101wyy/markdown-preview-enhanced/master/docs/presentation-intro.html) para ver as opções específicas dessa funcionalidade.

# Bônus: Trabalhando com imagens

Um dos maiores problemas que temos quando estamos escrevendo [Markdown](https://docs.microsoft.com/azure/devops/project/wiki/markdown-guidance?WT.mc_id=blog-devto-ludossan) é 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](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image&WT.mc_id=devto-blog-ludossan) que faz um par incrível com o [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan), 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](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image&WT.mc_id=devto-blog-ludossan):

![](https://raw.githubusercontent.com/mushanshitiancai/vscode-paste-image/master/res/vscode-paste-image.gif)

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

# Conclusão

O [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced&WT.mc_id=blog-devto-ludossan) 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](https://code.visualstudio.com/?WT.mc_id=blog-devto-ludossan) 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](https://blog.lsantos.dev/?utm_source=devto&utm_medium=article&utm_campaign=markdown_vscode) e se [inscreva na newsletter](https://blog.lsantos.dev/signup?utm_source=devto&utm_medium=article&utm_campaign=markdown_vscode) para receber notícias semanais!

| [Website](https://lsantos.dev) | [GitHub](https://github.com/khaosdoctor) | [Facebook](https://fb.com/lsantos.dev) | [LinkedIn](https://linkedin.com/in/lhs-santos) | [Twitter](https://twitter.com/_staticvoid)
|---|---|---|---|---