O Pandoc é um conversor de documentos capaz de converter entre diversos formatos e linguagens, inclusive Markdown.

Este é o segundo artigo da série sobre produção de documentos com Markdown, uma linguagem de marcação simples bastante útil para qualquer um que precise produzir praticamente qualquer tipo de documento técnico, acadêmico, para a Web, etc.

No artigo anterior da série fizemos uma pequena introdução sobre linguagens de marcação, apresentamos as características principais do Markdown e sua sintaxe básica.

Neste texto vamos apresentar o Pandoc, que é um software gratuito e open-source conversor entre diversos tipos de linguagens de marcação e arquivos de texto, e que também possui a sua própria implementação Markdown, com sintaxe estendida, chamada Pandoc’s Markdown.

Este texto se concentrará em apresentar o Pandoc, sua instalação, seu funcionamento e a sintaxe estendida Pandoc’s Markdown.

Pandoc img

Sumário do artigo

Introdução

O Pandoc é uma suíte gratuita e open source de analisadores e conversores de documento entre diferentes formatos de arquivos de texto e linguagens de marcação.

Devido à sua versatilidade o Pandoc apresenta-se como um canivete suíço da documentação e é capaz de realizar conversões entre dezenas de formatos, tais como HTML, LaTeX, Docx, diferentes dialetos de Markdown, além de também ser capaz de gerar arquivos PDF.

O Pandoc também possui seu próprio dialeto estendido de Markdown, uma sintaxe aprimorada normalmente conhecida como Pandoc’s Markdown, com uma série de funcionalidades adicionais bastante úteis.

Com o Pandoc, equações e macros LaTeX também podem ser usadas dentro de documentos Markdown, e o Pandoc inclui um sistema automático poderoso para citações e bibliografia.

Com o Pandoc é possível, por exemplo, escrever documentos técnicos, científicos e acadêmicos em Markdown, que como vimos no artigo anterior possui um sintaxe bastante simples e intuitiva, muito menos verbosa e complexa que outras linguagens como HTML e LaTeX, e ao final converter o texto em HTML (o objetivo original do Markdown), ou LaTeX, ou XML, RTF, ePUB, ou gerar um documento PDF, ou Docx (word), Odt, etc, inclusive incorporando outras linguagens, tais como LaTeX por exemplo, se for o caso e se for necessário, sem ter de pagar todo o preço da complexidade ou enfrentar uma curva de aprendizado maior e sem abrir mão de nenhuma funcionalidade que diferentes formatos e linguagens possam oferecer.

Instalação do Pandoc

A forma mais simples de instalar o Pandoc é através de seu instalador automático, disponível no site oficial. O próprio site irá identificar a partir de qual sistema operacional está sendo acessado e ajustar o link de download para o instalador correto. Basta fazer o download e instalar como qualquer outro software.

Após a instalação não surgirá nenhum ícone na barra de tarefas ou área de trabalho. Aparecerá, no máximo, a depender de configurações de seu computador, uma pasta chamada Pandoc na parte de programas do menu iniciar com um arquivo HTML chamado Pandoc User’s Guide, que é um manual de instruções do Pandoc, que também pode ser acessado nesta seção do site oficial do Pandoc.

O Pandoc não possui interface, é um programa de linha de comando, as instruções para o conversor serão feitas através de um interpretador de linha de comando, que no Windows pode ser o tradicional Prompt de Comando ou o mais moderno Windows PowerShell. Mesmo para aqueles que não estejam acostumados a trabalhar com linha de comando, demonstraremos como a lógica é bastante simples.

Instalações adicionais

Com o instalador automático já vem tudo o que é necessário para que o Pandoc funcione. Todavia, existem uma série de outros softwares que se integram ao Pandoc e aumentam as suas funcionalidades.

Para que o Pandoc seja capaz de gerar arquivos PDF a partir de arquivos Markdown, por exemplo, é necessário ter instalado o TeX/LaTeX no computador, uma vez que o Pandoc gera o PDF a partir do Markdown via LaTeX. Ironicamente, para converter o documento Markdown em LaTeX isto não é necessário.

LaTeX,como já mencionamos no artigo anterior desta série, é uma linguagem de marcação de texto, um sistema de composição tipográfica que inclui recursos destinados à produção de documentação técnica e científica. É um dos padrões mais utilizados para comunicação e publicação de documentos científicos.

O que precisamos instalar é uma “implementação” - ou “distribuição” - TeX/LaTeX. Existe mais de uma opção, o próprio site do Pandoc nos sugere o MikTeX, que é uma distribuição TeX/LaTeX gratuita e open source com um gerenciador de pacotes integrado que instala todos os componentes necessários.

Basta fazer o download do instalador adequado conforme o sistema operacional no site oficial do MikTeX e instalar como qualquer outro software. Há uma página no mesmo site oficial com um tutorial para instalação do MikTeX, caso considere necessário, embora o processo seja bastante simples, e há uma outra página com um tutorial para atualização do MikTeX, o que é recomendado que seja feito logo após a instalação.

Embora seja um conhecimento útil, não será necessário entender ou sequer utilizar a linguagem LaTeX para utilizar o Pandoc, basta que esta implementação da linguagem esteja instalada que o Pandoc a utilizará “por baixo dos panos” para, por exemplo, converter seu documento Markdown em PDF, dentre outras coisas.

O Pandoc oferece um universo de possibilidades, diversas extensões, complementos, softwares e linguagens que atuam em conjunto podem ser instalados mas, para os objetivos deste artigo, apenas o MikTeX já é suficiente.

Filosofia

O Markdown foi projetado para ser fácil de escrever e, principalmente, de ler:

Um documento formatado em Markdown deve ser publicável como está, como texto simples, sem parecer que foi marcado com tags ou instruções de formatação. - John Gruber

Todavia, existe um aspecto com relação ao qual os objetivos de Pandoc são diferentes dos objetivos originais do Markdown. Enquanto o Markdown foi originalmente projetado para ser convertido em HTML especificamente, o Pandoc foi projetado para gerar diferentes formatos.

Neste sentido, embora o Pandoc permita a incorporação de HTML “cru”, ele o desencoraja e fornece outras maneiras de representar elementos importantes do documento, como listas de definições, tabelas, expressões matemáticas e notas de rodapé.

Dialetos Markdown

Como mencionamos no artigo anterior desta série, existem dialetos - ou sabores - Markdown, que são variantes com sintaxe ligeiramente diferente da sintaxe básica de John Gruber, em geral estendidas.

O Pandoc implementa sua própria sintaxe estendida e ligeiramente revisada chamada de Pandoc’s Markdown, que o conversor toma como “padrão” (e chama simplesmente de markdown), mas também consegue utilizar a sintaxe básica (chamado pelo Pandoc de markdown_strict) e outros dialetos Markdown conhecidos:

  • CommonMark Markdown (commonmark);
  • CommonMark Markdown com estensões (commonmark_x);
  • Github-Flavored Markdown (gfm);
  • MultiMarkdown (markdown_mmd);
  • PHP Markdown Extra (markdown_phpextra).

Sintaxe estendida Pandoc’s Markdown

A seguir apresentamos os principais elementos estendidos e aprimorados da sintaxe Pandoc’s Markdown. A sintaxe básica já foi apresentada no artigo anterior desta série, que é importante que seja lido antes.

Existem muitas grandes ou pequenas variações sintáticas que existem por padrão ou podem ser adicionadas ao Pandoc’s Markdown via extensões, que em geral não entram em conflito com a sintaxe básica em sua versão mais estrita, conforme apresentada no artigo anterior. Neste texto nos concentramos nos elementos que adicionam funcionalidades mais relevantes para produção de textos técnicos, acadêmicos e para Web. Existe um guia completo da sintaxe do Pandoc’s Markdown, em inglês, no site oficial.

Metadados

Bloco de títulos Pandoc

Uma forma simples de inserir metadados referentes ao título do documento, autores e data, é através da inserção do “bloco de título” no início do documento.

O título, o autor ou autores e a data devem ser inseridos, nesta ordem, cada um em uma linha, precedidos por um caractere % (porcdentagem). Múltiplos autores podem ser separados por ; (ponto e vírgula). Da seguinte forma:

% Título do documento
% Autor 1; Autor 2
% 31/12/2020

Estas informações serão analisadas como informação bibliográfica, não como texto normal. Serão usadas, por exemplo, no título da saída de um arquivo LaTeX ou como título de uma página HTML.

O bloco pode conter todos os três elementos ou apenas o título, título e autor, apenas autor, título e data, etc.

A primeira linha sempre deve receber o título, a segunda linha o autor ou autores e a terceira linha a data. De modo que para colocar apenas parte das informações devemos deixar parte das linhas em branco:

% Título do documento
%
% 31/12/2020


% Título do documento
% Autor


%
% Autor 1; Autor 2

Bloco de metadados YAML

Uma outra forma de adicionar metadados ao documento é através da linguagem de marcação/configuração YAML, que tem uma sintaxe também extremamente simples.

Um bloco de metadados YAML é um objeto YAML válido, delimitado por uma linha de três --- (hífens) na parte superior e uma linha de três --- (hifens) ou três ... (pontos) na parte inferior. Um bloco de metadados YAML pode ocorrer em qualquer parte do documento, mas se não estiver no início, deve ser precedido por uma linha em branco.

Através de um bloco de metadados YAML podem ser inseridos virtualmente quaisquer metadados, e a forma como eles serão ou não interpretados e aproveitados dependerá dos formatos, do mecanismo de conversão ou do template utilizado.

A sintaxe de um bloco YAML consiste em um conjunto de chaves e valores, cada conjunto em uma linha, no formato mais simples possível: chave: valor. Caso o valor possua carecteres especiais que precisem ser “escapados” este valor pode vir entre "..."(aspas). O caractere | (pipe / barra vertical) pode ser usado para iniciar um bloco recuado que será interpretado literalmente, sem necessidade de “escape”.

O valor pode consistir em uma lista, como no caso de mais de um autor por exemplo, neste caso cada item da lista deve vir em uma linha, e precedidos por um - (hifen) e um espaço. Conjuntos de chave e valor poder ser hierarquicamente estruturados através de indentação (aninhando-se um objeto YAML dentro de outro, ou dentro de uma lista, arbitrariamente).

As possibilidades são praticamente infinitas e crescem em complexidade e em funcionalidade a medida que a exploramos. No trecho a seguir temos alguns exemplos de blocos de metadados YAML que demonstram o funcionamento básico da sintaxe:

---
titulo: Título do Documento
data: 31/12/2020
autor: Autor do Documento
...

---
titulo: Título do Documento
data: 31/12/2020
autor:
- Autor 1
- Autor 2
...

---
autor:
  nome: Autor do Documento
  afiliação: Universidade do autor

Resumo: |
   Este é um resumo.

   Este é o segundo parágrafo do resumo.
...

Atributos em Títulos

Particularmente útil para a produção de textos para a Web, é possível associar atributos aos títulos, tais como identificadores, classes e quaisquer pares de chave e valor. Identificadores e classes podem ser atribuídos através dos caracteres # e ., respectivamente, que já são utilizandos no CSS para este fim. Os atributos devem estar entre chaves após o título e separados deste por pelo menos um espaço.

Desta forma, o seguinte trecho em Markdown:

# Título 1 com atributos {#cidade .inteligencia onclick=doit}

## Título 2 com atributos {#bairro .urbana onclick=dothat}

Será convertido no seguinte HTML:

<h1 id="cidade" class="inteligencia" onclick="doit">Título 1 com atributos</h1>

<h2 id="bairro" class="urbana" onclick="dothat">Título 2 com atributos</h2>

O resultado final não será diferente apenas por conta dos atributos, que a princípio não são renderizados, a menos que a formatação seja manipulada via CSS através das classes ou atributos, o que é justamente uma das possibilidades adicionadas.

Da mesma forma que acontece com os títulos, com o Pandoc´s Markdowm também é possível associar atributos a links e imagens, tais como identificadores, classes e quaisquer pares de chave e valor. Particularmente útil para atribuir dimensões às imagens, por exemplo.

Identificadores e classes podem ser atribuídos através dos caracteres # e ., respectivamente, que já são utilizandos no CSS para este fim. Funciona tanto para links e imagens marcados em linha como para aqueles inseridos via identificadores de referência.

Os atributos devem estar entre chaves e após as marcações de qualquer link e imagem. Se forem links ou imagens marcados em linha os atributos devem vir logo em seguida, sem espaço, se forem inseridos via identificadores de referência devem estar separados destes por pelo menos um espaço.

Desta forma, o seguinte trecho em Markdown:

Imagem 01 inserida diretamente:

![imagem 01](https://1.bp.blogspot.com/-_Pt10SpvllA/YAiDIo7cF5I/AAAAAAAAAyI/NUo0OsunsPIK-CaIUhBIUfP0zylr05MmgCLcBGAsYHQ/s0/Inteligencia-urbana-imagem-1.jpg "logotipo branco"){#iddaimg2 .imagem1 width=200px}

Imagem 02 inserida via identificador de referência:

![imagem 02][idimg2]

[idimg2]: https://1.bp.blogspot.com/-DR0mDeycVoE/YAiDIl_NBZI/AAAAAAAAAyE/KL05izDqTKkaWPRUN1grl7GQXI3zRGqlACLcBGAsYHQ/s0/Inteligencia-urbana-imagem-2.jpg "logotipo branco" {#iddaimg2 .imagem2 width=50%}

Que irá produzir o seguinte HTML:

<p>Imagem 01 inserida diretamente:</p>
<p><img id="iddaimg1" class="imagem1" style="width:200px;" src="https://1.bp.blogspot.com/-_Pt10SpvllA/YAiDIo7cF5I/AAAAAAAAAyI/NUo0OsunsPIK-CaIUhBIUfP0zylr05MmgCLcBGAsYHQ/s0/Inteligencia-urbana-imagem-1.jpg" alt="imagem 01" title="logotipo branco"/></p>
<p>Imagem 02 inserida via identificador de referência:</p>
<p><img id="iddaimg2" class="imagem2" style="width:50%;" src="https://1.bp.blogspot.com/-DR0mDeycVoE/YAiDIl_NBZI/AAAAAAAAAyE/KL05izDqTKkaWPRUN1grl7GQXI3zRGqlACLcBGAsYHQ/s0/Inteligencia-urbana-imagem-2.jpg" alt="imagem 02" title="logotipo preto"/></p>

E gerará um resultado semelhante a este:

Imagem 01 inserida diretamente:

imagem 01

Imagem 02 inserida via identificador de referência:

imagem 02

Tabelas

O Pandoc permite a marcação de tabelas de quatro formas diferentes. Todas as formas produzem apenas tabelas simples (o que significa que linhas e colunas não podem ser mescladas).

A forma de marcação de tabelas que, em minha opinião, melhor combina simplicidade e funcionalidade é a que o Pandoc chama de Pipe Tables. Nesta sintaxe as colunas são separadas pelo caractere | (pipe / barra vertical), e entre as linhas de cabeçalho e as linhas comuns deve ser acrescentada uma linha com pelo menos três caracteres --- (hífens) e caracteres : (dois pontos), cuja distribuição indica o alinhamento de texto da respectiva coluna(:--- para alinhamento à esquerda, :---: para centralizado e ---: para alinhamento à direita). Uma legenda pode ser adicionada à tabela, antes ou depois da mesma, iniciando-se a linha com : (dois pontos). Conforme exemplo abaixo:

| São Paulo   | Rio de Janeiro | Belo Horizonte |
|:----------  |:--------------:|---------------:|
| Sé          | Lapa           | Savassi        |
| República   | Glória         | Lourdes        |
| Pinheiros   | Flamengo       | Pampulha       |
| Barra Funda | Botafogo       | Barreiro       |
: Bairos de capitais brasileiras

Que produzirá o seguinte HTML:

<table>
  <caption>Bairos de capitais brasileiras</caption>
  <thead>
    <tr class="header">
      <th style="text-align: left;">São Paulo</th>
      <th style="text-align: center;">Rio de Janeiro</th>
      <th style="text-align: right;">Belo Horizonte</th>
    </tr>
  </thead>
  <tbody>
    <tr class="odd">
      <td style="text-align: left;">Sé</td>
      <td style="text-align: center;">Lapa</td>
      <td style="text-align: right;">Savassi</td>
    </tr>
    <tr class="even">
      <td style="text-align: left;">República</td>
      <td style="text-align: center;">Glória</td>
      <td style="text-align: right;">Lourdes</td>
    </tr>
    <tr class="odd">
      <td style="text-align: left;">Pinheiros</td>
      <td style="text-align: center;">Flamengo</td>
      <td style="text-align: right;">Pampulha</td>
    </tr>
    <tr class="even">
      <td style="text-align: left;">Barra Funda</td>
      <td style="text-align: center;">Botafogo</td>
      <td style="text-align: right;">Barreiro</td>
    </tr>
  </tbody>
</table>

Que se converterá num resultado semelhante a este:

Bairos de capitais brasileiras
São Paulo Rio de Janeiro Belo Horizonte
Lapa Savassi
República Glória Lourdes
Pinheiros Flamengo Pampulha
Barra Funda Botafogo Barreiro

O cabeçalho não pode ser omitido. Para simular uma tabela sem cabeçalho, deve ser incluído um cabeçalho com células em branco.

Os caracteres | (barra vertical) inicial e final são opcionais, mas são obrigatórios entre todas as colunas.

Uma vez que as | (barras verticais) indicam os limites das colunas e os : (dois pontos) indicam seu alinhamento, as colunas e a tabela como um todo não precisam necessariamente ser alinhadas no texto em Markdown, como no exemplo acima.

Deste modo que o exemplo a seguir, embora seja menos legível enquanto Markdown “cru”, produzirá exatamente o mesmo HTML e o mesmo resultado final do exemplo anterior:

São Paulo|Rio de Janeiro|Belo Horizonte
:---|:---:|---:
Sé|Lapa|Savassi
República|Glória|Lourdes
Pinheiros|Flamengo|Pampulha
Barra Funda|Botafogo|Barreiro
: Bairos de capitais brasileiras

Blocos HTML

A sintaxe básica do Markdown permite que seja utilizado HTML em meio ao Markdown. Inclusive podem ser incluídos blocos de HTML, que são blocos de conteúdo HTML entre tags HTML separadas do texto circundante por linhas em branco que comecem e terminem na margem esquerda (sem indentação). Dentro desses blocos, tudo é interpretado como HTML, não Markdown.

O Pandoc se comporta dessa maneira quando o formato markdown_strict é usado mas, por padrão, o Pandoc’s Markdown interpreta o conteúdo entre as tags de bloco HTML como Markdown. Assim, por exemplo, este trecho:

<table>
<tr>
<td>*one*</td>
<td>[a link](https://www.inteligenciaurbana.org)</td>
</tr>
</table>

Será convertido neste HTML:

<table>
<tr>
<td><em>one</em></td>
<td><a href="https://www.inteligenciaurbana.org">a link</a></td>
</tr>
</table>

O que não aconteceria com a sintaxe básica do Markdown, ou com a utilização do markdown_strict no Pandoc. Isto é particularmente útil, por exemplo, para utilizarmos tabelas HTML em meio ao documento Markdown (que são mais completas e flexíveis que tabelas Markdown de qualquer dialeto) mas sem precisar utilizar HTML também em cada campo da tabela.

Blocos de código “cercados”

Para inserir blocos de código (trechos que são interpretadas literalmente), além de indentá-los com pelo menos quatro espaços ou um tab, como previsto na sintaxe básica, é possível marcar estes blocos “cercando-os” com uma linha de pelo menos três ~~~ (tils) antes de depois do bloco. E ao cercá-los, a indentação é dispensável.

O resultado final e em HTML é o mesmo, mas em Markdown “cru”, a utilização das “cercas” de ~~~ (tils) em vez da mera indentação ajudam na legibilidade. Neste sentido, o seguinte trecho:

Este é um parágrafo antes do bloco de código:

~~~
<h1>Título em HTML</h1>
<p>Parágrafo em HTML</p>
~~~

Este é um parágrafo depois do bloco de código.

Produz um HTML assim:

<p>Este é um parágrafo antes do bloco de código:</p>
<pre>
  <code>
    &lt;h1&gt;Título em HTML&lt;/h1&gt;
    &lt;p&gt;Parágrafo em HTML&lt;/p&gt;
  </code>
</pre>
<p>Este é um parágrafo depois do bloco de código.</p>

E gera um resultado semelhante a este:

Este é um parágrafo antes do bloco de código:

<h1>Título em HTML</h1>
<p>Parágrafo em HTML</p>

Este é um parágrafo depois do bloco de código.

Listas ordenadas (com diferentes marcadores)

Ao contrário da sintaxe básica (que só permite algarismos arábicos), o Pandoc permite que os itens de uma lista ordenada sejam marcados com letras maiúsculas e minúsculas e algarismos romanos.

Os marcadores de lista podem ser colocados entre parênteses ou seguidos por um único parênteses à direita ou ponto. Devem ser separados do texto que se segue por pelo menos um espaço e, se o marcador da lista for uma letra maiúscula com ponto, por pelo menos dois espaços. Da seguinte maneira:

Lista com letras maiúsculas:

A.  Primeiro item da Lista
A.  Segundo item da lista

Lista com letras minúsculas:

a) Primeiro item da Lista
a) Segundo item da lista
a) Terceiro item da lista

Lista com numerais romanos:

I.  Primeiro item da Lista
I.  Segundo item da lista
I.  Segundo item da lista

Este trecho produzirá o seguinte HTML (observe que é acrescentado um atributo type à tag <ol>):

<p>Lista com letras maiúsculas:</p>
<ol type="A">
  <li>Primeiro item da Lista</li>
  <li>Segundo item da lista</li>
</ol>
<p>Lista com letras maiúsculas:</p>
<ol type="a">
  <li>Primeiro item da Lista</li>
  <li>Segundo item da lista</li>
  <li>Terceiro item da lista</li>
</ol>
<p>Lista com numerais romanos:</p>
<ol type="I">
  <li>Primeiro item da Lista</li>
  <li>Segundo item da lista</li>
  <li>Segundo item da lista</li>
</ol>

E produz um resultado semelhante a este:

Lista com letras maiúsculas:

  1. Primeiro item da Lista
  2. Segundo item da lista

Lista com letras maiúsculas:

  1. Primeiro item da Lista
  2. Segundo item da lista
  3. Terceiro item da lista

Lista com numerais romanos:

  1. Primeiro item da Lista
  2. Segundo item da lista
  3. Segundo item da lista

Listas de definição

O Pandoc’s Markdown também suporta a criação de listas de definição, correspondentes Às tags HTML <dl>, <dt> e <dd>, definition-list, definition-term e definition-definition, respectivamente. É particularmente importante para a produção de textos para Web, dado que acrescenta semântica à marcação e potencializa sua indexação. Como o próprio termo sugere, uma lista de definição é uma lista de termos seguidos de suasdefinição (ou definições).

Cada termo deve vir em uma linha e deve ser seguido por uma ou mais definições na linha - ou linhas - seguintes. Uma definição começa com : (dois pontos) ou ~ (til), que pode ser recuado em um ou dois espaços.

Um termo pode ter várias definições, e cada definição pode consistir em um ou mais elementos de bloco (parágrafo, bloco de código, lista, etc.), cada um recuado (indentado) quatro espaços ou um tab.

Entre um termo e suas definições e o termo seguinte deve ser deixada uma linha em branco, da mesma forma que entre parágrafos.

Assim, a seguinte lista de definições em Markdown:

São Paulo
:   Capital do estado de São Paulo
:   Maior cidade do Brasil

Belo Horizonte
~   Capital do estado de Minas Gerais

Rio de Janeiro
~   Capital do estado do Rio de Janeiro

    Também já foi capital do estado da Guanabara e capital do Brasil (isto é um parágrafo que faz parte da definição acima)

Converte-se no seguinte HTML:

<dl>
  <dt>São Paulo</dt>
  <dd>Capital do estado de São Paulo</dd>
  <dd>Maior cidade do Brasil</dd>

  <dt>Belo Horizonte</dt>
  <dd>Capital do estado de Minas Gerais</dd>

  <dt>Rio de Janeiro</dt>
  <dd>
    <p>Capital do estado do Rio de Janeiro</p>
    <p>Também já foi capital do estado da Guanabara e capital do Brasil (isto é um parágrafo que faz parte da definição acima)</p>
  </dd>
</dl>

Que produz um resultado semelhante a este:

São Paulo

Capital do estado de São Paulo

Maior cidade do Brasil

Belo Horizonte

Capital do estado de Minas Gerais

Rio de Janeiro

Capital do estado do Rio de Janeiro

Também já foi capital do estado da Guanabara e capital do Brasil (isto é um parágrafo que faz parte da definição acima)

Listas de exemplos numerados

Outra funcionalidade extremamente útil para praticamente qualquer tipo de documento são o que o Pandoc chama de listas de exemplos numerados.

Utilizando-se o marcador @ (arroba) entre parêntesis antes de cada item pode-se criar uma lista numerada sequencialmente ao longo do documento. O primeiro item da lista com um marcador @ será numerado como ‘1’, o próximo como ‘2’ e assim por diante, em todo o documento. Mesmo que a lista seja interrompida, quando retomada, continua a partir do número seguinte.

Além do marcador @, pode ser adicionado um identificador qualquer a cada item da lista (adicionado após o @, sem espaço), de modo que o exemplo listado possa ser referenciado em qualquer parte do texto.

Funciona da seguinte forma:

(@) Este é o primeiro exemplo numerado
(@) Este é outro exemplo
(@idx) Este é mais um exemplo com identificador

Aqui temos um parágrafo interrompendo a lista.

(@idy) Outro exemplo com identificador
(@) Mais um exemplo

Então temos outro parágrafo. Neste parágrafo podemos mencionar e referenciar os exemplos (@idx) e (@idy), pois eles possuem identificadores.

(@) Último exemplo deste trecho

O Pandoc converterá o trecho acima no seguinte HTML:

<ol class="example" type="1">
  <li>Este é o primeiro exemplo numerado</li>
  <li>Este é outro exemplo</li>
  <li>Este é mais um exemplo com um identificador</li>
</ol>
<p>Aqui temos um parágrafo interrompendo a lista.</p>
<ol start="4" class="example" type="1">
  <li>Outro exemplo com identificador</li>
  <li>Mais um exemplo</li>
</ol>
<p>Então temos outro parágrafo. Neste parágrafo podemos mencionar e referenciar os exemplos (3) e (4), pois eles possuem identificadores.</p>
<ol start="6" class="example" type="1">
  <li>Último exemplo deste trecho</li>
</ol>

Que produzirá um resultado semelhante a este:

  1. Este é o primeiro exemplo numerado
  2. Este é outro exemplo
  3. Este é mais um exemplo com um identificador

Aqui temos um parágrafo interrompendo a lista.

  1. Outro exemplo com identificador
  2. Mais um exemplo

Então temos outro parágrafo. Neste parágrafo podemos mencionar e referenciar os exemplos (3) e (4), pois eles possuem identificadores.

  1. Último exemplo deste trecho

Texto rasurado (Strikeout)

O Pandoc’s Markdown possui sintaxe para texto rasurado (rabiscado, tachado, deletado), também chamado de strikeout. Para marcar o texto desta forma basta envolvê-lo entre dois ~~ (tils), da seguinte maneira:

Este é um ~~texto tachado~~.

O HTML produzido será este:

<p>Este é um <del>texto tachado</del>.</p>

E o resultado será semelhante a este:

Este é um texto tachado.

Sobrescrito e subscrito

Trechos sobrescritos podem ser marcados circundando o trecho sobrescrito por caracteres ^ (circunflexo), e os trechos subscritos podem ser marcados circundando o trecho subscrito por caracteres ~ (til). Conforme o seguinte exemplo:

H~2~O é um líquido.  2^10^ é igual a 1024.

Que produz o seguinte HTML:

<p>H<sub>2</sub>O é um líquido. 2<sup>10</sup> é igual a 1024.</p>

E gera um resultado semelhante a este:

H2O é um líquido. 210 é igual a 1024.

O texto entre ^ ... ^ ou ~ ... ~ não pode conter espaços ou novas linhas. Se o trecho sobrescrito ou subscrito contiver espaços, esses espaços devem ser precedidos (escapados) por barras invertidas. Da seguinte maneira:

Palavra~dois\ subscritos~. Palavra^dois\ sobrescritos^
Palavra<sub>dois subscritos</sub>. Palavra<sup>dois sobrescritos</sup>

Palavradois subscritos. Palavradois sobrescritos

Expressões matemáticas (LaTeX)

É possível inserir expressões matemáticas em LaTeX/TeX no meio de um documento Markdown que o Pandoc a renderizará, independente do formato de saída da conversão.

Para marcar uma expressão matemática LaTeX/TeX em linha basta envolver a expressão com caracteres $ (cifrão). O $ de abertura deve ter um caractere sem espaço imediatamente à sua direita, enquanto o $ de fechamento deve ter um caractere sem espaço imediatamente à sua esquerda e não deve ser seguido imediatamente por um dígito. Desta forma, R\$ 20.000 e US\$ 30.000, por exemplo, não serão interpretados como matemática TeX.

Para inserir uma expressão matemática em bloco basta utilizar, em um parágrafo isolado, dois $$ (cifrões) como delimitadores. Nesse caso, os delimitadores podem ser separados da expressão matemática por um espaço em branco. No entanto, não pode haver linhas em branco entre os delimitadores $$ de abertura e fechamento.

Se, por algum motivo, for necessário inserir um $ literal, basta ‘escapá-lo’ com barra invertida \$ e ele não será tratados como delimitador matemático.

Funciona assim:

Aqui temos uma expressão matemática em linha $\frac{1}{2}=0,5$, e a seguir temos um expressão matemática em bloco:

$$ \sqrt{2} \approx 1,41 $$

E o resultado final será semelhante a este

Aqui temos uma expressão matemática em linha $\frac{1}{2}=0,5$, e a seguir temos um expressão matemática em bloco:

\[\sqrt{2} \approx 1,41\]

As expresões em TeX serão ‘impressas’ em qualquer formato de saída. A forma através da qual o código será processado vai variar conforme o formato de saída. Por exemplo:

  • LaTex

    Aparecerá literalmente e rodeada por \(...\), para expressões em linha ou \[...\], para expressões em bloco.

  • Markdown

    Aparecerá literalmente e rodeada por $...$, para expressões em linha ou $$...$$, para expressões em bloco.

  • Docx

    Será renderizada utilizando a marcação matemática OMML, que é o padrão utilizado para expressões matemáticas no Microsoft Word.

  • HTML

    A maneira como expressões matemáticas serão renderizadas em HTML dependerá das opções de linha de comando selecionadas no momento da conversão. O mais eficiente tende a ser a utilização de MathJax (que é um mecanismo de exibição JavaScript para expressões matemáticas que funciona em todos os navegadores).

  • PDF

    Depende do mecanismo utilizado para produção do PDF, o padrão é o que PDF seja gerado via LaTeX, e neste caso o Pandoc utilizará a implementação LaTeX/TeX instalada no computador também para renderizar as expressões matemáticas (no início no artigo sugerimos a instalaçãoo do MikTeX para este fim).

Notas de rodapé

Outra funcionalidade trazida pelo Pandoc que é bastante útil para qualquer tipo de documento são as notas de rodapé.

Notas de rodapé podem ser referenciadas no texto com um identificador qualquer. Os identificadores nas referências das notas de rodapé não podem conter espaços, tabulações ou novas linhas. Esses identificadores são usados ​​apenas para correlacionar a referência da nota de rodapé com a própria nota, na saída. As notas de rodapé serão numeradas sequencialmente.

O mais prático é que as notas de rodapé em si não precisam ser colocadas no final do documento, elas podem ser inseridas em qualquer lugar, exceto dentro de outros elementos de bloco (listas, citações de bloco, tabelas, etc.). Cada nota de rodapé deve ser separada do conteúdo circundante (incluindo outras notas de rodapé) por linhas em branco, como qualquer parágrafo.

Na conversão o Markdown moverá as notas, sequencialmente numeradas, para o final do documento (se for um documento contínuo, como uma página da Web, por exemplo), ou para o final da página em que a nota esteja referenciada (se for um documento composto por páginas, como um PDF ou Docx).

A referência numerada das notas funcionará como um link de atalho para o nota que, por sua vez possuirá um link de retorno para o texto, no caso de documentos digitais, claro.

A sintaxe de marcação de notas de rodapé funciona conforme este exemplo:

Este é um parágrafo que contém duas referências para notas de rodapé. Aqui tem uma [^1] e aqui tem outra [^idqualquer].

[^1]: Aqui temos a primeira nota de rodapé.

[^idqualquer]: Aqui temos a segunda nota de rodapé.

    Este parágrado está indentado, portanto ele faz parte da segunda nota de rodapé

    > Aqui temos um bloco de citação, também indentado, que também faz parte da segunda nota de rodapé

Este é outro parágrafo, ele não está indentado e portanto faz parte do texto e não da nota de rodapé acima dele. No resultado final ele estará na sequência do primeiro parágrafo. Neste parágrafo vamos referenciar outra nota de rodapé [^outranota].

[^outranota]: Esta é a terceira nota de rodapé, referenciada no segundo parágrafo.

Por fim, fechamos com um terceiro parágrafo.

Este trecho produzirá o seguinte HTML:

<p>Este é um parágrafo que contém duas referências para notas de rodapé. Aqui tem uma <a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> e aqui tem outra <a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>.</p>
<p>Este é outro parágrafo, ele não está indentado e portanto faz parte do texto e não da nota de rodapé acima dele. No resultado final ele estará na sequência do primeiro parágrafo. Neste parágrafo vamos referenciar outra nota de rodapé <a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a>.</p>
<p>Por fim, fechamos com um terceiro parágrafo.</p>

<section class="footnotes" role="doc-endnotes">
<hr />
<ol>
  <li id="fn1" role="doc-endnote">
    <p>Aqui temos a primeira nota de rodapé.<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p>
  </li>
  <li id="fn2" role="doc-endnote">
    <p>Aqui temos a segunda nota de rodapé.</p>
    <p>Este parágrado esta indentado, portanto ele faz parte da segunda nota de rodapé</p>
    <blockquote>
      <p>Aqui temos um bloco de citação, também indentado, que também faz parte da segunda nota de rodapé</p>
    </blockquote>
    <a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a>
  </li>
  <li id="fn3" role="doc-endnote">
    <p>Esta é a terceira nota de rodapé, referenciada no segundo parágrafo.<a href="#fnref3" class="footnote-back" role="doc-backlink">↩︎</a></p>
  </li>
</ol>
</section>

E o resultado final será semelhante a este:

Este é um parágrafo que contém duas referências para notas de rodapé. Aqui tem uma 1 e aqui tem outra 2.

Este é outro parágrafo, ele não está indentado e portanto faz parte do texto e não da nota de rodapé acima dele. No resultado final ele estará na sequência do primeiro parágrafo. Neste parágrafo vamos referenciar outra nota de rodapé 3.

Por fim, fechamos com um terceiro parágrafo.


  1. Aqui temos a primeira nota de rodapé.↩︎

  2. Aqui temos a segunda nota de rodapé.

    Este parágrado esta indentado, portanto ele faz parte da segunda nota de rodapé

    Aqui temos um bloco de citação, também indentado, que também faz parte da segunda nota de rodapé

    ↩︎
  3. Esta é a terceira nota de rodapé, referenciada no segundo parágrafo.↩︎

Citações bibliográficas

Uma funcionalidade particularmente útil para textos acadêmicos é a possibilidade de automatizar geração de citações e referências bibliográficas.

O Pandoc possui uma sintaxe que também é bastante simples para citações bibliográficas. As citações devem ser colocadas entre colchetes [] e separadas entre si por ; (ponto-e-vírgula). Cada citação deve ter uma “chave” composta pelo caractere @(arroba) seguido do identificador daquela citação na fonte de dados bibliográficos, e pode opcionalmente ter um prefixo, um localizador e um sufixo. A chave de citação deve começar com uma letra, dígito ou _ (underline) e pode conter caracteres alfanuméricos, _ e caracteres de pontuação internos (:.#$\%\&-+\?<>\~\/). O trecho a seguir contém alguns exemplos:

Lorem ipsum dolor sit amet [veja @cit01, pp. 27-29; veja também @silva02, cap. 1].

Duis feugiat justo est [@cit02, pp. 33-35, 38-39].

Suspendisse vitae est est. [@silva02; @citX].

Um caractere - (sinal de subtração) antes do @ irá suprimir a menção do autor na citação mas mantê-la nas referencia bibliográficas geradas. Isso pode ser útil quando o autor já é mencionado no texto ou quando a citação não for explícita por alguma razão.

Silva disse alguma coisa [-@silva02]

Também é possível referenciar citações em linha, conforme este trecho:

@silva02 disse alguma coisa.

@silva02 [p. 33] disse outra coisa.

No momento da conversão o Pandoc relacionará a fonte de dados bibliográficos contendo as referência bibliográficas citadas e as respectivas citações através da chave e identificador, e então formatará as citações no texto e a lista de referências bibliográficas ao final do arquivo conforme o formato de citação configurado.

A fonte de dados bibliográficos pode ser um arquivo externo ou mesmo uma lista de referências dentro do bloco de metadados YAML no mesmo documento. Opcionalmente pode ser especificado um estilo de citação CSL.

Uma fonte externa de dados bibliográficos pode ter qualquer um destes formatos:

  • BibLaTeX (.bib);
  • BibTeX (.bibtex);
  • CSL JSON (.json);
  • CSL YAML (.yaml).

A fonte de dados bibliográficos pode ser produzida manualmente ou com a utilização de um editor e gerenciador de referências que produza os formatos de arquivo requeridos, tais como Jabref, EndnoteWeb, Zotero, Mendeley, dentre outros.

Como utilizar o Pandoc

As possibilidades de uso do Pandoc são quase infinitas, e embora a lógica seja bastante simples ela vai crescendo em complexidade a medida que exploramos suas funcionalidades.

Neste artigo vamos apresentar seu funcionamento básico com o objetivo de explicar sua lógica. Em artigos subsequentes podemos explorar funcionalidades específicas, tais como a criação de templates presonalisados, filtros, extensões, etc. Assinem nossa newsletter para serem notificados da publicação de material novo.

Existe um guia do usuário do Pandoc, em inglês, no site oficial, que aborda a maior parte das funcionalidades.

Linha de comando

Como já mencionamos, o Pandoc não possui interface, é um programa de linha de comando, as instruções para o conversor serão feitas através de um interpretador de linha de comando, que no Windows pode ser o tradicional Prompt de Comando ou o mais moderno Windows PowerShell, tanto faz.

Como demonstraremos mais adiante, será mais prático se o interpretador de linha de comando for executado na mesma pasta em que se localiza o documento a ser convertido.

No windows, para abrir o Prompt de Comando ou o PowerShell em uma pasta específica basta navegar até esta parte no Windows Explorer e, com a tecla shift pressionada, clicar com o botão direito do mouse em uma espaço em branco da pasta em questão. Será aberto um menu suspenso e, neste menu, devemos clicar na opção “abrir janela do PowerShell aqui” ou “abrir janela do Prompt de comando aqui” (pode estar disponível uma ou outra opção, conforme a versão do Windows que estiver sendo utilizada).

Então uma janela do interpretador de linha de comando será aberta já na pasta em que está nosso arquivo que será convertido. A janela aberta se parece com esta (figura 1).

Figura 1

Figura 1: Prompt de comando do Windows

A lógica consistirá em digitar os comandos no interpretador de linha de comando e pressionar enter para executá-los.

Principais comandos Pandoc

Todos os comandos Pandoc devem ser precedidos pela palavra pandoc para indicar ao interpretador que o software Pandoc é quem irá executar os comandos.

Conversão básica

Se estivermos executando o interpretador em uma pasta que contém um arquivo Markdown (Pandoc’s Markdown) cujo nome é arquivoinicial.md e quisermos converter este em um arquivo Docx (word) que tenha o nome arquivofinal.docx que seja criado nesta mesma pasta basta digitar o seguinte comando:

pandoc -f markdown -t docx arquivoinicial.md -o arquivofinal.docx

E então um arquivo com nome arquivofinal.docx surgirá naquela pasta.

Cada elemento do comando acima representa o seguinte:

  • pandoc - está chamando o software Pandoc para executar os comandos;
  • -f- significa from e especifica, no termo que o segue, qual o formato de origem do arquivo;
  • markdown - formato Pandoc´s Markdown, neste caso especificado para o documento de origem;
  • -t - significa to e especifica, no termo que o segue, para qual formato iremos converter o arquivo;
  • docx - formato docx, neste caso especificado para o formato de conversão;
  • arquivoinicial.md - local e nome do arquivo e ser convertido;
  • -o - significa output e especifica, no termo que o segue, o local e nome do arquivo resultante da conversão;
  • arquivofinal.docx - local e nome do arquivo resultante da conversão.

Como podemos observar, arquivoinicial.md e arquivofinal.docx representam local e nome dos respectivos arquivos. O local pode ser o “caminho” relativo para o arquivo em relação à pasta onde o interpretador de linha de comando está sendo executado. Como estamos executando o interpretador na mesma pasta em que o arquivo a ser convertido está localizado (e também na mesma parte em que queremos que o arquivo final seja criado) tudo o que precisamos colocar é o nome do arquivo. É por isso que é mais prático executar o interpretador de linha de comando a partir da mesma pasta em que se localiza nosso documento. Caso contrário precisaríamos digitar algo semelhante a isso: C:\Window\Documentos\Minhapasta\arquivoinicial.md.

O exemplo anterior é a versão completa de um comando de conversão simples, mas o Pandoc é um pouco mais esperto que isso e, na maioria das vezes, ele consegue determinar o formato de origem e o formato de conversão apenas pelas extensões nos nomes dos arquivos, no nosso caso .md (markdown) e .docx (word). O que significa que o seguinte comando produziria o mesmo resultado que o nosso primeiro exemplo:

pandoc arquivoinicial.md -o arquivofinal.docx

Esta versão “preguiçosa” do comando não funcionará em 100% dos casos, evidentemente. Por exemplo, o Pandoc consegue entender diferentes dialetos de Markdown, mas qualquer dialeto de Markdown possui a mesma extensão de arquivo .md. Se não especificarmos o formato o Pandoc interpretará, por padrão, que o arquivo .md é um Pandoc´s Markdown, se não for o caso, se for a sintaxe básica do Markdown, por exemplo, então precisaríamos acrescentar -f markdown_strict ao comando.

Concatenar arquivos

Também é possível indicar múltiplos arquivos de origem e o pandoc irá concatená-los (com uma linha em branco entre o conteúdo de cada um). Desta forma, se possuirmos três arquivos Pandoc´s Markdown parte1.md, parte2.md e parte3.md e quisermos convertê-los num documento final em formato pdf, o comando pode ser o seguinte (jpa em sua versão “preguiçosa”):

pandoc parte1.md parte2.md parte3.md -o documentofinal.pdf

Comandos adicionais

Além de simplesmente converter os arquivos, o Pandoc pode executar muitas outras funções que, contudo, precisam ser especificadas através de comandos adicionais na mesma linha de comando. São inúmeras as possibilidades, neste artigo vamos demonstrar a lógica de seu funcionamento apresentando dois exemplos importantes: Criação de sumário e geração de referências bibliográficas.

Sumário (Table of Contents)

O Pandoc pode gerar automaticamente um sumário no documento de saída. O sumário é gerado a partir dos títulos e subtítulos do documento. Para que ele seja gerado basta inserir o comando adicional --toc no comando de conversão.

Como vimos no artigo anterior o Markdown nos permite marcar até seis níveis de títulos e subtítulos, mas nem todos os níveis devem necessariamente aparecer no sumário. Por padrão o Pandoc inclui 3 níveis. Se quisermos anterar isso, para mais ou para menos, basta utilizarmos o comando adicional --toc-depth e em seguida o número de níveis que queremos incluir.

Assim, se quisermos converter o arquivo Pandoc´s Markdown meuarquivo.md em HTML inserindo um sumário com até 4 níveis de subtítulos podemos usar um comando semelhante a este no nosso interpretador de linha de comando:

pandoc --toc --toc-depth 4 meuarquivo.md -o meuarquivofinal.html
Referências bibliográficas

Já apresentamos a sintaxe para as citações das referências bibliográficas e já informamos quais os formatos possíveis para a fonte de dados bibliográficos, mas para que o Pandoc de fato interprete estas citações e gere automaticamente as referências bibliográficas e as citações é necessário utilizar o comando adicional --citeproc no comando de conversão.

Caso a fonte dos dados bibliográficos seja um arquivo externo precisamos utilizar o comando adicional --bibliography seguido do local e nome da fonte de dados bibliográficos.

Assim, se quisermos, por exemplo, converter o arquivo Pandoc´s Markdown meutexto.md em docx com a geração automática de citações e bibliografia, e se nossa fonte de dados bibliográficos for um arquivo chamado minhabibliografia.bib localizado na mesma pasta, podemos usar um comando semelhante a este no nosso interpretador de linha de comando:

pandoc --citeproc --bibliography minhabibliografia.bib meutexto.md -o meutextofinal.docx

Todos os comandos adicionais utilizados podem ir sendo dispostos sequencialmente, não importa a ordem. Por exemplo, se quisermos gerar sumário e bibliografia automáticos o comando pode ser semelhante a este:

pandoc --citeproc --bibliography minhabibliografia.bib --toc --toc-depth 4 meutexto.md -o meutextofinal.html

O importante é compreender a lógica, o guia do usuário do Pandoc, em inglês, no site oficial, lista uma série de outros comandos e funcionalidades adicionais.

Conclusão

Neste texto apresentamos o Pandoc, sua instalação, a sintaxe estendida Pandoc’s Markdown e a lógica de sua utilização do software.

Em artigos subsequentes apresentaremos outras funcionalidaes adicionais e mais específicas do Pandoc e também outras ferramentas e dialetos Markdown úteis para a produção de documentos de diferentes propósitos, principalmente a produção de documentos técnicos, produção de documentos acadêmicos e produção de texto para Web.

Além do blog, o site Inteligência Urbana disponibiliza páginas com referências para livros, cursos e leis e normas relacionadas aos temas que tratamos aqui. Caso você tenha interesse pode conferir nossos serviços oferecidos e entrar em contato quando quiser. Se quiser ser alertado da publicação de material novo pode assinar a nossa newsletter, e muito obrigado pela atenção até aqui!

Principais referências