Sintaxe Estendida

Introdução

A sintaxe original do Markdown, publicada por John Gruber, adicionou diversos elementos indispensáveis para a edição de documentos, porém alguns usuários não se deram por satisfeitos.

A sintaxe estendida tenta solucionar essa insatisfação adicionando novos elementos através de novas marcações.

Tabelas, blocos de código, geração automática de links e até notas de rodapé são exemplos de extensão da sintaxe básica do Markdown.

Esses elementos podem ser ativados instalando um plugin para o seu processador Markdown ou até usando uma pequena variação da sintaxe da linguagem.

NOTA: é bem possível que o seu aplicativo Markdown já tenha suporte para os elementos apresentados nesse artigo, por isso, vale a pena testar cada um deles enquanto acompanha o tutorial.

Sabores do Markdown

O Markdown conta com alguns sabores diferentes, ou seja, variações da sintaxe básica da linguagem.

Essas variações, além de fornecerem suporte a sintaxe básica, adicionam elementos que enriquecem a edição de documentos.

Os aplicativos compatíveis com o Markdown, muitas vezes, utilizam uma das linguagens mostradas abaixo:

CommonMark

GitHub-flavored Markdown (GFM)

Markdown Extra

R Markdown

MultiMarkdown

Criando tabelas em Markdown

Uma tabela em Markdown pode ser usada para apresentar comparações de dados pelo usuário.

Para criar uma tabela em Markdown nós usamos traços – e barras verticais | para separar linhas e colunas.

A primeira linha da tabela é onde construímos o cabeçalho, separando essa linha por três ou mais traços --- para que o processador Markdown entenda a formatação.

A separação das colunas é feita usando a barra vertical |, também chamada de pipe por programadores.

Abaixo segue uma tabela de exemplo:

| Título  | Título   |
| ------- | -------- |
| Texto   | Texto    |
| Texto   | Texto    |

As barras verticais | usadas nas extremidades da tabela são para efeito puramente cosmético, ou seja, você pode criar uma tabela sem as barras laterais.

Exemplo:

Título  | Título
------- | --------
Texto   | Texto
Texto   | Texto

A saída renderizada em HTML:

A largura das células, dentro de uma tabela do Markdown, pode variar.

Exemplo:

| Título | Título |
| --- | ----------- |
| Texto | Texto |
| Texto     | Texto |

Gerando tabelas no Markdown de forma automática

O Markdown veio para facilitar a edição de documentos, e a criação de tabelas pode se tornar uma tarefa um pouco mais entediante.

O uso de barras verticais e traços pode desagradar alguns usuários, por isso é interessante que a gente consiga automatizar o processo de formatação de tabelas no Markdown.

Passo 1 - Abra o nosso editor Markdown clicando aqui.

Passo 2 - Clique no ícone de geração automática de tabelas para abrir o painel de opções.

Passo 3 - No painel de opções:

1. Insira a quantidade de linhas da tabela.
2. Defina a quantidade de colunas da tabela.
3. Escolha qual a posição de alinhamento do texto dentro das colunas.
4. Clique para confirmar e gerar a estrutura da tabela.

Passo 4 - Preencha os valores de cada célula.

Alinhamento

O Markdown permite que você alinhe o conteúdo de uma coluna de uma tabela à esquerda, à direita ou ao centro.

Para alinhar um conteúdo à esquerda em uma tabela do Markdown, coloque dois pontos : antes dos traços --- que separam a linha do cabeçalho.

Exemplo:

| Frutas  | Verduras | Legumes |
| :---    | :----    | :---    |
| Caju    | Agrião   | Cenoura |
| Maçã    | Brócolis | Ervilha |

Resultado em HTML:

NOTA: O uso dos dois pontos para alinhar o texto à esquerda é opcional, pois o conteúdo da tabela já fica alinhado nessa posição por padrão.

Para alinhar o texto à direita dentro da tabela do Markdown, insira os dois pontos : depois dos traços --- que separam a linha do cabeçalho.

Exemplo:

| Frutas  | Verduras | Legumes |
|    ---: |    ----: |    ---: |
| Caju    | Agrião   | Cenoura |
| Maçã    | Brócolis | Ervilha |

Resultado em HTML:

Para alinhar o conteúdo da coluna ao centro em uma tabela do Markdown, adicione dois pontos : antes e depois dos traços que separam a linha do cabeçalho.

Exemplo:

| Frutas  | Verduras | Legumes |
|  :---:  |  :----:  |  :---:  |
| Caju    | Agrião   | Cenoura |
| Maçã    | Brócolis | Ervilha |

Resultado em HTML:

É possível mesclar a formatação de alinhamento, já que, essa, somente influencia o conteúdo de dentro da coluna.

Exemplo:

| Frutas  | Verduras | Legumes |
| :---    |  :----:  |    ---: |
| Caju    | Agrião   | Cenoura |
| Maçã    | Brócolis | Ervilha |

Resultado em HTML:

Vale a pena frisar que, o alinhamento dos traços --- da linha que separa os títulos da tabela é irrelevante para o processador Markdown, o que realmente será levado em consideração é a posição dos dois pontos :.

No exemplo a seguir os traços --- estão posicionados à esquerda da coluna e mesmo assim o alinhamento funciona.

| Frutas  | Verduras | Legumes |
| :---    | :----:   | ---:    |
| Caju    | Agrião   | Cenoura |
| Maçã    | Brócolis | Ervilha |

Resultado em HTML:

NOTA: O conteúdo do cabeçalho da tabela também será alinhado de acordo com a posição dos dois pontos.

Formatação de texto em tabelas

Você pode inserir alguns elementos básicos do Markdown dentro de uma tabela.

Algumas formatações permitidas são, criação de links, enfatizar o conteúdo com negrito ou itálico e destacar o texto como código, porém somente o código em linha é aceito, ou seja, quando criado com a abertura e o fechamento de crases `.

Títulos, blocos de código, blockquotes, listas, linhas horizontais, imagens e tags HTML não funcionam.

NOTA: Você pode até encontrar aplicativos que aceitem a inserção dos elementos citados acima dentro de uma tabela, mas isso irá prejudicar a portabilidade do seu documento, já que outros programas não dão suporte.

Escapando barras verticais em tabelas

Você já aprendeu que, para separar as colunas da tabela nós usamos a barra vertical |.

Agora, se você pretende mostrar esse mesmo caractere como conteúdo dentro de uma célula, é necessário utilizar a codificação HTML: |.

Ao converter o seu documento para um outro formato, o código | se transformará em uma barra vertical |.

Bloco de código cercado

Um bloco de código cercado permite que você crie representações de código sem precisar recuar a linha em quatro espaços ou uma tabulação, além disso, permite também, definir qual linguagem de programações o bloco representa, com isso, é possível aplicar o realce de sintaxe adequado.

Para criar um bloco de código cercado no Markdown coloque três crases ``` antes do conteúdo e três crases ``` depois do conteúdo.

Exemplo:

```
{
  "nome": "Robert",
  "sobrenome": "Salles",
  "idade": 25
}
```

A saída renderizada fica assim:

{
  "nome": "Robert",
  "sobrenome": "Salles",
  "idade": 25
}

NOTA: Alguns processadores Markdown permitem que você use tiles ~~~ no lugar das crases para formar o bloco de código.

Veja também: Como escapar crases dentro de um bloco de código.

Realce de sintaxe

Muitas bibliotecas do JavaScript são utilizadas para destacar blocos de código, como por exemplo: Prism.js & highlight.js.

Elas pegam uma tag HTML específica, normalmente a tag pre ou a tag code e aplicam o realce baseado na sintaxe da linguagem de programação do bloco de código.

A sintaxe da linguagem é usualmente definida pelo parâmetro class da tag, por exemplo:

<code class="lang-markdown"></code>

Usando a classe lang-markdown, a framework saberá que, o conteúdo entre as tags code deve receber o destaque de acordo com a linguagem Markdown.

NOTA: A aplicação do realce pode ser feita inclusive automaticamente, algumas ferramentas possuem a capacidade de detectar as linguagens de programação de forma automatizada, sem a necessidade de defini-la no parâmetro class.

Na construção do bloco de código usando o Markdown você pode especificar a linguagem de programação logo após as três primeiras crases ``` de abertura.

Exemplo:

```json
{
  "nome": "Robert",
  "sobrenome": "Salles",
  "idade": 25
}
```

Como na primeira linha do bloco, logo após as três crases de abertura, foi especificado json o código será realçado de acordo:

{
  "nome": "Robert",
  "sobrenome": "Salles",
  "idade": 25
}

NOTA: o código somente terá destaque se você utilizar uma biblioteca do JavaScript que execute esse tipo de tarefa, o HTML por si só, não realça o código.

Notas de rodapé

Uma nota de rodapé no Markdown permite que o usuário crie uma referência para algum conceito citado no documento.

Normalmente, essas notas de rodapé são colocadas no final do documento, porém no Markdown você pode defini-las em qualquer lugar do texto.

Ao criar uma nota de rodapé um número sobrescrito em forma de link será inserido no local que você o criou, quando o usuário clicar nesse link ele será levado diretamente para o local que contém a referência da nota.

A sintaxe para a criação da nota de rodapé é dividida em duas partes.

A primeira parte representa o número contendo o link e é criado usando colchetes, um acento circunflexo e um identificador, por exemplo: [^1].

O identificador pode conter números e letras, mas não aceita espaços e nem tabulações.

A segunda parte abrange o conteúdo da referência em si, para criá-la use colchetes, um acento circunflexo seguido pelo mesmo identificador (que você criou anteriormente), dois pontos, um espaço em branco e o texto, exemplo: [^1]: Minha nota de rodapé.

Aqui está uma nota de rodapé simples[^1]. Aqui está uma nota de rodapé mais elaborada[^bignote].

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

[^bignote]: Aqui está uma com vários parágrafos e código.

    Recuar parágrafos para incluí-los na nota de rodapé.

    `{ meu código }`

    Adicione quantos parágrafos desejar.

A rederização em HTML fica assim:

Aqui está uma nota de rodapé simples¹. Aqui está uma nota de rodapé mais elaborada².

NOTA: O conteúdo do rodapé pode ser colocado em qualquer lugar do documento exceto dentro de outros elementos Markdown como, tabelas, listas e blocos de código.

NOTA: As notas de rodapé serão, sempre, numeradas sequencialmente, independente dos identificadores que você criou, uma sequência de notas [^35], [^aaaa] e [^102_444], será renderizada como 1, 2 e 3.

Adicionando ID ou Classe nos elementos do Markdown

Quando criamos tags em HTML, podemos atribuir a elas uma identificação única e uma identificação genérica através dos parâmetros id e class.

Exemplo:

<h2 id="special-title"></h2> e <p class="bg-blue"></p>

Com o id nós podemos pegar uma referência específica para um determinado elemento, normalmente o id do elemento é único dentro da marcação HTML.

O parâmetro class é genérico e pode ser atribuído para vários elementos.

A função do id ou do class é permitir reconhecer esses elementos com facilidade através do JavaScript ou do CSS, usando esse id ou essa class nós podemos manipular propriedades como cor, tamanho, posicionamento e etc.

Para adicionar um id ou uma class a um elemento do Markdown abra chaves { logo após o conteúdo do elemento, coloque uma cerquilha # para indicar um id ou um . para indicar uma class, em seguida, o próprio identificador e, por fim, feche as chaves }.

Exemplos:

### Meu título {#identifier}

Meu parágrafo{.my-class}

O HTML fica assim:

<h3 id="identifier">Meu título</h3>

<p class="my-class">Meu parágrafo</p>

NOTA: Atente-se para o fato de que, nem todos os aplicativos Markdown suportam a inserção de parâmetros id ou class, é importante sempre consultar a documentação do programa.

Links para ids no Markdown

Com a mesma sintaxe padrão de criação de links [](), nós podemos vincular um referência direta para um id no próprio documento.

Dentro dos parênteses onde colocamos a URL, insira o id do elemento precedido pela cerquilha #.

Se o id estiver em um outro documento, a formatação é semelhante, porém, antes da identificação, coloque a URL da página.

Exemplo:

[IDs de cabeçalho](https://markdown.net.br/sintaxe-estendida#markdown-title-id)

Lista de definições

Uma lista de definições em HTML é representada pelas tags dl e dt. Essa lista representa termos e suas explicações de uma forma conceitual.

Para criar uma lista de definições com o Markdown digite o termo em uma linha, pressione o a tecla Enter, dois pontos, um espaço em branco e a definição do termo.

Exemplo:

Primeiro termo
: Esta é a definição do primeiro termo.

Segundo termo
: Esta é uma definição do segundo termo.
: Esta é outra definição do segundo termo.

O HTML fica assim:

<dl>
  <dt>Primeiro termo</dt>
  <dd>Esta é a definição do primeiro termo.</dd>
  <dt>Segundo termo</dt>
  <dd>Esta é uma definição do segundo termo. </dd>
  <dd>Esta é outra definição do segundo termo.</dd>
</dl>

E o resultado:

Primeiro termo

Esta é a definição do primeiro termo.

Segundo termo

Esta é uma definição do segundo termo.

Esta é outra definição do segundo termo.

Tachado em Markdown

O tachado é usado para corrigir um erro de forma comparativa, normalmente seguido pela correção na mesma linha.

O tachado nada mais é do que, uma formatação que insere uma linha horizontal no meio de um conteúdo.

Para tachar um conteúdo em Markdown use dois tiles ~~ antes e depois do texto a ser formatado.

Markdown é: ~~difícil~~ fácil de aprender.

E o resultado é esse:

Markdown é: difícil fácil de aprender.

Listas de tarefas em Markdown

Uma lista de tarefas em Markdown permite que o usuário crie uma sequência de elementos com caixas de seleção à sua esquerda usando colchetes [].

Como estamos trabalhando com lista é necessário iniciar a linha do item com um traço -.

Para marcar uma tarefa como concluída coloque um x dentro dos colchetes [x].

- [x] Lorem ipsum dolor sit amet
- [ ] Lorem consectetur adipisicing elit
- [ ] Lorem ut labore et dfolore

A saída renderizada fica assim:

Inserindo Emojis no documento Markdown

Pois é, você pode inserir os famosos emoticons diretamente na formatação Markdown do seu documento.

Existem duas formas mais utilizadas para a tarefa, copiar e colar o emoji no conteúdo ou digitar códigos de emoji.

Vamos entender melhor como funcionam os dois procedimentos, mas antes, clique aqui para abrir o nosso editor Markdown e testar os Emojis em tempo real.

Copiando e colando Emojis no Markdown

Passo 1 - Abra essa página da Emojipedia que contém um emoticon sorrindo e clique no botão Copy.

Passo 2 - Volte para o nosso editor Markdown, clique no painel à esquerda e pressione CTRL + V para colar.

NOTA: Você pode explorar a Emojipedia para encontrar seu emoji favorito, o procedimento de copiar e colar é o mesmo para todos eles.

Se o seu aplicativo Markdown for compatível, você verá a reprentação do emoticon diretamente no texto.

Durante a conversão do documento Markdown em HTML ou até em PDF, os emojis continuam representados da forma correta.

NOTA: Se o documento HTML não estiver renderizando os emojis da maneira que deveria, codifique as páginas em UTF-8.

Usando códigos de acesso Emoji

Um código emoji é formado pela identificação do emoticon cercado por dois pontos.

Fui acampar! :tent: Volto em breve.

Isso é tão engraçado! :joy:

A saída renderizada fica assim:

Fui acampar! ⛺ Volto em breve.

Isso é tão engraçado! 😂

Descobrindo o código de acesso dos Emojis

Se não souber o código de acesso do emoji use o nosso editor Markdown para descobri-lo.

Passo 1 - Clique aqui para abrir o Markeditor.

Passo 2 - Clique no botão de inserção de Emojis na barra de ferramentas.

Passo 3 - Na janela de seleção de Emoji:

1. Escolha a fonte de onde quer pegar os Emojis.
2. Clique sobre o Emoji que será inserido no documento (você pode clicar em vários Emojis na mesma janela).
3. Pressione o botão de confirmar para colocar o código de acesso das imagens no texto.

No painel à esquerda você pode visualizar os códigos dos Emojis e no painel à direita a renderização.

NOTA: As imagens dos emoticons podem variar muito de aplicativo para aplicativo, nessa lista você encontra os emojis compatíveis com o Markdown usado pelo GitHub, você pode testá-los no seu aplicativo para saber se há compatibilidade.

Link automático de URL em Markdown

Alguns processadores Markdown transformam URL em links quando encontram um endereço entre os sinais de menor que < e maior que >.

Exemplo:

<https://markdown.net.br>

Em outras ocasiões, embutir o endereço entre <> é dispensável, ou seja, basta inserir a URL no próprio documento que o aplicativo fará a conversão automaticamente.

Exemplo:

https://markdown.net.br

A saída renderizada fica assim:

https://markdown.net.br

Desativando a vinculação automática de URL

Se você quer apenas representar uma URL em um documento e evitar que o aplicativo a converta para um link de forma automática, coloque o endereço entre crases ``.

`https://markdown.net.br`

A saída renderizada fica assim:

https://markdown.net.br

NOTA: Vale lembrar que, o uso de crases para circundar um conteúdo o transforma em código.