Sintaxe Básica do Markdown

Visão geral

Apesar de algumas variações, a maioria dos aplicativos fornecem suporte aos elementos básicos do Markdown. Esses elementos são essenciais para que você consiga formatar um documento. Mas não se engane, usando apenas o básico do Markdown é possível criar sites bem elaborados para a Web.

NOTA: Sempre que possível, quando houver variações de sintaxe de um processador Markdown para outro, essas, serão notadas no artigo.

Títulos

Todo documento tem ou deveria ter um título, correto? Então, vamos começar por ele.

O símbolo usado para formatar um título em Markdown é a cequilha #. Na construção do título formate o código colocando uma cerquilha no inicio da linha, demarcando o cabeçalho.

Por exemplo:

# Título de nível 1

Será convertido para a tag h1 do HTML.

<h1>Título de nível 1</h1>.

NOTA: A tag h1 representa o título mais importante do HTML, normalmente o título do artigo.

A quantidade de cerquilhas que você utiliza no inicio da linha indica o nível do título, sendo assim, a formatação ### Meu título cria um cabeçalho de nível 3.

NOTA: Quando falamos de nível, falamos dos títulos convertidos para HTML. No HTML os níveis de títulos vão de 1 à 6, denotados pelas tags h1, h2, h3, h4, h5 e h6

EXEMPLOS

# Título de nível 1

<h1>Título de nível 1</h1>

## Título de nível 2

<h2>Título de nível 2</h2>

### Título de nível 3

<h3>Título de nível 3</h3>

#### Título de nível 4

<h4>Título de nível 4</h4>

##### Título de nível 5

<h5>Título de nível 5</h5>

###### Título de nível 6

<h6>Título de nível 6</h6>

Sintaxe alternativa

O Markdown oferece uma sintaxe diferente para construir títulos de níveis 1 e 2. Ao invés de usar a cerquilha no início da linha, adicione abaixo do título sinais de igual == para cabeçalhos de nível 1 e sinais de menos -- para cabeçalhos de nível 2.

EXEMPLOS

Título de nível 1
===============

<h1>Título de nível 1</h1>

Título de nível 2
---------------

<h2>Título de nível 2</h2>

Alguns editores Markdown permitem que você use somente um sinal de igual = ou um traço - embaixo do texto, mas isso pode gerar problemas de formatação em outros editores que não são compatíveis com essa sintaxe.

Títulos: melhores práticas

Você pode se deparar com problemas de compatibilidade quando falamos do espaço entre a cerquilha # no inicio da linha e o texto do título.

É recomendado sempre adicionar pelo menos um espaço entre eles, além de prover uma melhor leitura do seu documento, você ainda terá mais suporte de edição entre os aplicativos Markdown.

A Tabela 1.3 exemplifica a construção correta do título.

Parágrafos

A formatação mais simples do Markdown é a do parágrafo. Para criar um, basta separar um pedaço do texto com uma linha em branco, criando fragmentações que o processador Markdown interpretará como parágrafos.

EXEMPLOS

O Markdown é importante para todo programador.

Aprender o Markdown é essencial para uma carreira de sucesso.

<p>O Markdown é importante para todo programador.</p>

<p>Aprender o Markdown é essencial para uma carreira de sucesso.<p>

Parágrafos: melhores práticas

Normalmente o parágrafo fica grudado no começo da linha, isso é, evite recuá-lo usando espaços de qualquer tipo, nem espaços em branco nem tabulações.

NOTA: O parágrafo deve ser recuado quando estiver dentro de uma lista.

A Tabela 1.5 exemplifica o uso correto para construção de um parágrafo.

Quebras de linha

Em HTML uma quebra de linha é representada pela tag br.

Para gerar uma quebra de linha no Markdown, insira dois ou mais espaços em branco no final da linha e pressione a tecla Enter.

EXEMPLOS

Primeira linha do documento.  
Segunda linha do documento.

<p>Primeira linha do documento.<br>

Segunda linha do documento.</p>

Quebra de linha: melhores práticas

O uso do espaço em branco para criar quebra de linhas, apesar de compatível com a maioria dos aplicativos, pode gerar problemas de formatação.

Seguem alguns pontos:

• Espaços em branco depois da linha são difíceis de notar.
• Pessoas podem adicionar espaços em branco, no fim da linha, por força do hábito ou descuido.
• Alguns editores de texto, como o Sublime Text, têm configurações que removem os espaços em branco, antes e depois, da linha ao salvar o documento.

Uma alternativa viável para evitar qualquer problema com quebra de linhas, basta usar a tag HTML <br> diretamente nos seus documentos.

NOTA: É interessante lembrar que os aplicativos Markdown, em sua maioria, também são compatíveis com as tags em HTML, ou seja, você pode mesclar formatação Markdown com formatação HTML no mesmo documento.

NOTA: Em alguns aplicativos somente o pressionamento da tecla Enter já é suficiente para criar uma quebra de linha

NOTA: Variações do Markdown, como o CommonMark, interpretam o uso de uma barra invertida \ como indicador de uma nova linha.

O pressionamento da tecla Enter ou o uso da barra invertida \, apesar de válidos, não são recomendados pois a compatibilidade depende do programa Markdown.

A Tabela 1.7 mostra a sintaxe correta para criar uma nova linha.

Ênfase

Semelhante a um editor WYSIWYG, como o Microsoft Word, o Markdown também oferece formatações para enfatizar o texto.

Dentre as formatações de ênfase mais populares, estão o negrito e o itálico, que também podem ser aplicados usando a sintaxe do Markdown.

Negrito em Markdown

Para formatar um texto em negrito no Markdown, coloque dois asteriscos ** antes do conteúdo e dois asteriscos ** depois do conteúdo.

EXEMPLOS

**This part of the text** will be bold.

<strong>This part of the text</strong> will be bold.

__This part of the text__ will be bold.

<strong>This part of the text</strong> will be bold.

Markdown**Is**Easy**To**Learn

Markdown<strong>Is</strong>Easy<strong>To</strong>Learn

NOTA: Como mostrado nos exemplos acima, você pode substituir os asteriscos por sublinhados, usando dois sublinhados __ antes e depois do conteúdo também formata o texto em negrito no Markdown.

Negrito: melhores práticas

Tanto o uso de dois asteriscos como o de dois sublinhados podem aplicar a formatação em negrito à um conteúdo.

Porém, a utilização dos sublinhados em meio a uma palavra pode gerar problemas de formatação dependendo do processador Markdown, por isso, de preferência ao uso de asteriscos.

A Tabela 1.9 demonstra o uso recomendado para formatar em negrito.

Itálico em Markdown

Semelhante ao negrito, a formatação em itálico no Markdown também utiliza asterisco * ou sublinhado _, mas, no caso do itálico, use somente um asterisco * antes do conteúdo e um asterisco * depois do conteúdo.

EXEMPLOS

*This part of the text* will be in italics.

<em>This part of the text</em> will be in italics.

_This part of the text_ will be in italics.

<em>This part of the text</em> will be in italics.

Markdown*Is*Easy*To*Learn

Markdown<em>Is</em>Easy<em>To</em>Learn

Para aplicar itálico ao meio de uma palavra em Markdown, use um asterisco antes e depois do conteúdo.

Exemplo:

Mar*kdo*wn

Itálico: melhores práticas

Utilize sempre um asterisco * ao aplicar itálico ao meio de uma palavra, isso evitará problemas de compatibilidade com processadores Markdown.

A Tabela 1.11 demonstra a marcação recomendada para enfatizar um conteúdo em itálico.

Negrito e Itálico

Somente negrito ou somente itálico? Caso queira, você pode combinar as duas formatações para destacar qualquer conteúdo.

Para aplicar o negrito e o itálico simultaneamente adicione três asteriscos *** ou três sublinhados ___ ao redor do texto a destacar.

Se for enfatizar o meio de uma palavra com as duas formatações dê preferência ao uso de asteriscos, no caso, três asteriscos ***.

EXEMPLOS

***This part of the text*** will be bold and italicized.

<strong><em>This part of the text</em></strong> will be bold and italicized.

This is really ___important___.

This is really <strong><em>important</em></strong>.

This is really __*important*__.

This is really <strong><em>important</em></strong>.

This is really **_important_**.

This is really <strong><em>important</em></strong>.

This text is ***really*** important.

This text is <strong><em>really</em></strong> important.

Negrito e Itálico: melhores práticas

Para evitar problemas de compatibilidade com aplicativos Markdown, ao destacar o meio de uma palavra, combinando negrito e itálico, dê preferência ao uso de três asteriscos.

A Tabela 1.13 demonstra o uso indicado para combinar ambas formatações.

Blockquote

Para marcar um conteúdo como blockquote no Markdown, use o sinal de maior que > no começo do parágrafo.

Por exemplo, essa marcação Markdown:

> Conteúdo do blockquote.

Resultaria nessa saída HTML:

Conteúdo do blockquote.

Blockquote com vários parágrafos

Se você precisa de um blockquote contendo diversos parágrafos dentro dele, utilize o sinal de maior que > a frente de cada um desses parágrafos e os separe por uma linha contendo apenas o sinal de maior que.

NOTA: O sinal de maior que > deve ser colocado na linha que separa os parágrafos para que o processador Markdown consiga interpretar da maneira correta a sua marcação.

Vejamos um exemplos:

> Primeiro parágrafo do blockquote.
>
> Segundo parágrafo do blockquote.

A saída em HTML:

Primeiro parágrafo do blockquote.

Segundo parágrafo do blockquote.

Blockquotes aninhados

Além de inserir vários parágrafos dentro de um blockquote você também pode aninhá-los, ou seja, inserir blockquotes dentro de blockquotes, complexo? Vamos simplificar.

Para criar um bloco aninhado utilize dois sinais de maior que >> antes do parágrafo.

Exemplo:

> Conteúdo do blockquote.
>
>> Esse parágrafo será interpretado como um blockquote aninhado.

A renderização em HTML:

Conteúdo do blockquote.

Esse parágrafo será interpretado como um blockquote aninhado.

Blockquote com outros elementos

A versatilidade dos blockquotes permite a inserção de outros elementos Markdown dentro deles.

NOTA: Alguns elementos Markdown podem não ser renderizados corretamente quando colocados dentro de um blockquote, isso varia muito entre processadores Markdown.

> #### Título h4 dentro do bloco
>
> - Primeiro elemento da lista dentro do blockquote.
> - Segundo elemento da lista dentro do blockquote.
>
>  *Texto em itálico* parte do parágrafo sem formatação **texto em negrito**.

A saída em HTML:

Título h4 dentro do bloco

• Primeiro elemento da lista dentro do blockquote.
• Segundo elemento da lista dentro do blockquote.

Texto em itálico parte do parágrafo sem formatação texto em negrito.

Listas

Listas são essenciais na organização de tópicos dentro do seu documento. Uma lista facilita a visualização de elementos que possam ter relação um com o outro.

Para criar uma lista no Markdown nós usamos números para listas ordenadas, ou seja, em sequência e traços -, ou sinais de adição +, ou asteriscos * para listas não ordenadas.

Listas ordenadas

Vamos começar ordenando os elementos da nossa lista, para isso coloque um número seguido por um ponto e o texto do elemento.

Vale notar que, os números dos elementos não precisam estar em ordem numérica ascendente, porém, o primeiro elemento da lista deve iniciar com o número um 1.

NOTA: Para criar um elemento recuado insira uma tabulação antes do número que demarca o elemento. Em alguns processadores Markdown você também pode inserir 3 espaços antes da numeração, o resultado é semelhante, porém isso pode variar dependendo do aplicativo, na dúvida use o TAB.

EXEMPLOS

1. Primeiro elemento
2. Segundo elemento
3. Terceiro elemento
4. Quarto elemento

<ol>
    <li>Primeiro elemento</li>
    <li>Segundo elemento</li>
    <li>Terceiro elemento</li>
    <li>Quarto elemento</li>
</ol>

1. Primeiro elemento
1. Segundo elemento
1. Terceiro elemento
1. Quarto elemento

<ol>
    <li>Primeiro elemento</li>
    <li>Segundo elemento</li>
    <li>Terceiro elemento</li>
    <li>Quarto elemento</li>
</ol>

1. Primeiro elemento
8. Segundo elemento
3. Terceiro elemento
5. Quarto elemento

<ol>
    <li>Primeiro elemento</li>
    <li>Segundo elemento</li>
    <li>Terceiro elemento</li>
    <li>Quarto elemento</li>
</ol>

1. Primeiro elemento
2. Segundo elemento
3. Terceiro elemento
    1. Elemento recuado
    2. Elemento recuado
4. Quarto elemento

<ol>
    <li>Primeiro elemento</li>
    <li>Segundo elemento</li>
    <li>Terceiro elemento
    <ol>
        <li>Elemento recuado</li>
        <li>Elemento recuado</li>
    </ol>
    </li>
    <li>Quarto elemento</li>
</ol>

Listas não ordenadas

Uma lista não ordenada é uma sequência de elementos denotados, normalmente, por algum símbolo à esquerda do elemento, isso é, não há uma sequência numérica aqui.

A marcação do Markdown para criar listas não ordenadas é o sinal de mais +, ou o traço -, ou o asterisco *.

Coloque um desses dois sinais antes do item da lista para demarcá-lo, seguido por um espaço em branco e o conteúdo do elemento.

NOTA: Recue um elemento da lista inserindo uma tabulação antes da marcação do elemento.

EXEMPLOS

- Primeiro elemento
- Segundo elemento
- Terceiro elemento
- Quarto elemento

<ul>
    <li>Primeiro elemento</li>
    <li>Segundo elemento</li>
    <li>Terceiro elemento</li>
    <li>Quarto elemento</li>
</ul>

* Primeiro elemento
* Segundo elemento
* Terceiro elemento
* Quarto elemento

<ul>

    <li>Primeiro elemento</li>

    <li>Segundo elemento</li>

    <li>Terceiro elemento</li>

    <li>Quarto elemento</li>

</ul>

+ Primeiro elemento
* Segundo elemento
- Terceiro elemento
+ Quarto elemento

<ul>

    <li>Primeiro elemento</li>

    <li>Segundo elemento</li>

    <li>Terceiro elemento</li>

    <li>Quarto elemento</li>

</ul>

- Primeiro elemento
- Segundo elemento
- Terceiro elemento
    - Elemento recuado
    - Elemento recuado
- Quarto elemento

<ul>
    <li>Primeiro elemento</li>
    <li>Segundo elemento</li>
    <li>Terceiro elemento
    <ul>
        <li>Elemento recuado</li>
        <li>Elemento recuado</li>
    </ul>
    </li>
    <li>Quarto elemento</li>
</ul>

Adicionando elementos

O Markdown permite que você insira outros elementos no meio de uma lista sem quebrar a sua continuidade.

Para preservar a formatação da lista, recue o elemento diferente em 4 espaços ou uma tabulação.

Parágrafos

* Esse é o primeiro elemento da lista.
* Esse é o segundo elemento da lista.
    Um parágrafo adicionado sem quebrar a sequência da lista.
* E finalmente o terceiro elemento da lista.

O resultado seria esse:

• Esse é o primeiro elemento da lista.
• Esse é o segundo elemento da lista.

• Um parágrafo adicionado sem quebrar a sequência da lista.

• E finalmente o terceiro elemento da lista.

Blockquote dentro da lista

* Esse é o primeiro elemento da lista.
* Esse é o segundo elemento da lista.

    > Blockquote no meio da lista.

* E finalmente o terceiro elemento da lista.

O resultado ficaria assim:

• Esse é o primeiro elemento da lista.

• Esse é o segundo elemento da lista.

  Blockquote no meio da lista.

• E aqui está o terceiro item da lista.

Bloco de código

Ao inserir um bloco de código dentro de uma lista recue-o oito espaços ou duas tabulações.

Abaixo segue um exemplo de uma lista com um bloco de código dentro dela.

1. Vamos primeiro abrir nosso arquivo index.html.
2. Localize o bloco de código mostrado abaixo:

        <html>
            <head>
            <title>Título do meu site</title>
        </head>

3. Altere o título da página.

O Resultado fica assim:

1. Vamos primeiro abrir nosso arquivo index.html.

2. Localize o bloco de código mostrado abaixo:

   <html>
       <head>
       <title>Título do meu site</title>
   </head>

3. Altere o título da página.

Perceba que a sequência numérica da lista não foi alterada mesmo com a inserção do bloco de código entre os elementos.

Imagens

1. Primeiro abra o arquivo do logo do Markdown.
2. Veja o logo do Markdown na tela.

    ![Logo do Markdown](https://markdown.net.br/assets/img/basic-syntax/markdown-logo-small.png)

3. Já pode fechar o arquivo.

A renderização em HTML ficaria assim:

1. Primeiro abra o arquivo do logo do Markdown.

2. Veja o logo do Markdown na tela.

   
3. Já pode fechar o arquivo.

Código

Usando o Markdown nós podemos demarcar uma parte do conteúdo como código usando crases `. Coloque uma crase antes e depois do texto que será interpretado pelo processador Markdown como código.

EXEMPLO:

`código`.

<code>código.</code>

Escapando crases

Você pode se deparar com a seguinte situação.

O conteúdo ao qual você pretende aplicar a formatação de código já contém uma crase. Ou se você deseja usar a crase para destacar parte do texto dentro do próprio código.

Traduzindo, você precisa colocar uma crase dentro de uma demarcação de código sem que essa crase seja interpretada como marcação Markdown.

A solução é simples, duplicar a crase inicial e a crase final que cercam o pedaço de código.

EXEMPLOS

``Usando `crase` dentro da marcação de código.``

<code>Usando `crase` dentro da marcação de código.</code>

Bloco de código

O Markdown permite que criemos blocos de código recuando 4 espaços ou uma tabulação.

Veja o exemplo a seguir:

    <html>
        <head>
        </head>
    </html>

O resultado:

<html>
    <head>
    </head>
</html>

Usando a sintaxe estendida do Markdown nós podemos criar blocos de código sem recuar espaços, para isso precisamos usar a marcação de blocos de código cercado.

Linhas horizontais

Três asteriscos seguidos ***, ou três traços ---, ou três sublinhado ___ criam uma linha horizontal.

Uma linha deve conter apenas esses caracteres para que o processador Markdown interprete a linha horizontal da maneira correta.

***

---

_________________

Usando qualquer um dos caracteres o resultado será o mesmo, veja abaixo.

NOTA: Não é necessário estipular uma quantidade máxima de caracteres para criar uma linha, desde que, você utilize no mínimo 3 e a linha só possua esses caracteres, você pode inserir a quantidade que quiser.

Linhas horizontais: melhores práticas

Sempre adicione uma linha em branco antes e depois da marcação de linha horizontal. Isso é necessário devido a sintaxe alternativa para criação de títulos, se você colocar três traços --- diretamente abaixo de uma linha com conteúdo, essa, será interpretada como um título de nível 2.

A Tabela 1.18 exemplifica a criação de linhas horizontais da forma correta.

Links

Links são utilizados para criar ligações entre partes do seu documento. Quando falamos em criar página para a Web ou até mesmo arquivos PDF, ser capaz de inserir links é uma das características indispensáveis para editar esses tipos de documentos.

A sintaxe básica de criação de links no Markdown é a seguinte:

• Coloque o texto que irá representar o link entre colchetes, exemplo:
  [O Melhor Site de Markdown do Mundo].
• Em seguida, o endereço do link, também conhecido como URL, deve ser colocado entre parenteses, exemplo:
  (https://markdown.net.br)

Juntando tudo.

Visite [O Melhor Site de Markdown do mundo](https://markdown.net.br).

E a saída em HTML.

Visite O Melhor Site de Markdown do Mundo

Adicionando títulos

Se você tiver um pouco de experiência com o HTML sabe que, quando o usuário coloca o mouse sobre um link da página, geralmente um pequeno rótulo descrevendo o propósito do link é apresentado para o usuário.

Esse rótulo é o título do link e para criá-lo usando Markdown basta adicionar dentro dos parenteses um texto entre aspas depois da URL.

Exemplo:

Visite [O Melhor Site de Markdown do Mundo](https://markdown.net.br "A referência definitiva do Markdown.").

Saída em HTML, coloque o mouse sobre o link e veja o título aparecer.

Visite O Melhor Site de Markdown do Mundo

URLs e endereços de email

Você também pode transformar uma URL em link automaticamente colocando-a entre os sinais de menor que < e maior que >.

<https://markdown.net.br>
<email@host.com>

O Resultado fica assim:

https://markdown.net.br
email@host.com

Enfatizando links

Ao adicionar asteriscos ao redor da formatação de link, ou seja, antes dos colchetes e depois dos parenteses, você indica para o processador Markdown que aquele link deve ser enfatizado.

Por exemplo:

Visite o site: *[Referência do Markdown](https://markdown.net.br)*.
Eu recomendo o mecanismo de pesquisa: **[Duck Duck GO](https://duckduckgo.com/)**.

A saída em HTML ficaria assim:

Visite o site: Referência do Markdown
Eu recomendo o mecanismo de pesquisa: Duck Duck GO.

Você também pode destacar um link usando a formatação de código.

Exemplo:

Reveja a seção: [`código`](#code).

Resultado:

Reveja a seção: código

Links de estilo de referência

O Markdown oferece uma sintaxe alternativa para a criação de links que permite uma visualização mais limpa do seu documento.

Com essa sintaxe você pode colocar o texto que será transformado em link no meio do parágrafo com apenas uma referência, no final do documento adicione todos os links usando as mesmas referências anteriores.

NOTA: Você pode colocar a referência do link em qualquer parte do seu documento, eu recomendo no final por questão de organização.

Como a criação desse link de referência se divide em duas partes, vamos analisar cada uma delas.

Primeira parte do link

Primeiro vamos criar dois conjuntos de colchetes, dentro do primeiro coloque o texto do link, ou seja o texto que irá aparecer na página, no segundo coloque um rótulo que servirá de referência para o endereço do link:

[Markdown - Wikipedia][1]

NOTA: O rótulo do link de referência, localizado dentro do segundo par de colchetes, pode ser qualquer coisa, números, palavras, frases, pode incluir até pontuação, fica ao seu critério, desde que a referência para o link no final do documento seja igual.

Exemplos:

[Markdown - Wikipedia][wiki_markdown.1]
[Site Oficial do John Gruber][JOHN GRUBER]

NOTA: O rótulo de referência também não diferencia maiúsculas e minúsculas, ou seja, wiki_markdown é o mesmo que WIKI_MARKDOWN.

Segunda parte do link

A segunda parte indica para onde aquele link aponta, ou seja, a URL do link.

Para montar a segunda parte do link nós temos que ter o seguinte:

1. Um rótulo de referência válido de link que você criou anteriormente no seu documento, coloque ele entre colchetes, seguido por dois pontos e pelo menos um espaço em branco (por exemplo, [rótulo]: ).
2. O endereço do link, opcionalmente essa URL pode estar entre os sinais de menor que < e maior que >.
3. O título do link entre aspas "", aspas simples '' ou parenteses (), claro, o título é opcional.

Todos os exemplos abaixo são válidos para formatar a segunda parte:

[1]: https://en.wikipedia.org/wiki/Markdown
[1]: https://en.wikipedia.org/wiki/Markdown "Markdown - Wikipedia"
[1]: https://en.wikipedia.org/wiki/Markdown 'Markdown - Wikipedia'
[1]: https://en.wikipedia.org/wiki/Markdown (Markdown - Wikipedia)
[1]: <https://en.wikipedia.org/wiki/Markdown> "Markdown - Wikipedia"
[1]: <https://en.wikipedia.org/wiki/Markdown> 'Markdown - Wikipedia'
[1]: <https://en.wikipedia.org/wiki/Markdown> (Markdown - Wikipedia)

Vou ressaltar novamente que você pode colocar essa segunda parte do link em qualquer lugar do seu documento, eu adiciono no final do arquivo por questão de organização

Juntando todas as peças

Aqui eu vou apresentar para você uma situação onde o uso de links de referência pode manter o seu documento Markdown mais fácil de ler.

Digamos que você precise adicionar um ou mais links para algum site com mais informações sobre o conteúdo abordado naquele parágrafo.

Em Markdown ficaria assim:

Para saber mais você pode consultar esse artigo do Markdown: [Wikipedia](https://en.wikipedia.org/wiki/Markdown "Markdown - Wikipedia"). Ou a documentação da linguagem: [John Gruber](https://daringfireball.net/projects/markdown/ "Documentação Original do Markdown.").

Veja que, a adição dos links dentro do próprio parágrafo pode gerar um texto mais difícil de ser lido, especialmente se a pessoa que estiver lendo não conhecer o Markdown.

Como os links são importantes para o contexto do parágrafo, nós não podemos removê-los, porém há uma forma mais eficaz de limpar esse parágrafo, usando links de referência.

Para saber mais você pode consultar esse artigo do Markdown: [Wikipedia][1]. Ou a documentação da linguagem: [John Gruber][2].

[1]: <https://en.wikipedia.org/wiki/Markdown> "Markdown - Wikipedia"
[2]: https://daringfireball.net/projects/markdown/ "Documentação Original do Markdown."

NOTA: A colocação do sinal de menor que < e de maior que > ao redor do link é opcional.

As duas formatações acima terão resultados idênticos em HTML:

Para saber mais você pode consultar esse artigo do Markdown: Wikipedia. Ou a documentação da linguagem: John Gruber.

Links de referência: melhores práticas

Em alguns casos, você pode se deparar com espaços em branco em URLs, isso pode se tornar um problema dependo do aplicativo Markdown.

Para evitar anomalias na formatação, use o espaço em branco codificado: %20.

A Tabela 1.19 apresenta a formatação de espaço em branco em URL usando codificação.

Imagens

A sintaxe do Markdown para adicionar uma imagem é a seguinte:

1. Um ponto de exclamação: !.
2. O texto alternativo da imagem entre colchetes: []
3. O endereço completo da imagem dentro de parênteses: ()
4. Título opcional entre aspas, ainda dentro do parênteses: ( "")

Exemplo:

![Markdown é a linguagem de marcação mais simples do mundo!](https://markdown.net.br/assets/img/markdown.jpg "Logo do Markdown")

A conversão em HTML fica assim:

Imagem e Link

Para usar uma imagem como link:

1. Crie uma formatação de link normal.
2. No primeiro par de colchetes na formatação do link, que faz referência ao seu texto, use a formatação Markdown de imagem que você aprendeu logo acima.

Exemplo:

[![Uma pedra antiga no deserto](https://markdown.net.br/assets/img/shiprock.jpg "Shiprock, New Mexico By Beau Rogers")](https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFCiD-zsJWT-nNfsgB-dPDwZJ-bn9JGn-5HtSXY-6CUhAL-a4UTXB-ugPum-KUPSo-fBLNm-6CUmpy-4WMsc9-8a7D3T-83KJev-6CQ2bK-nNusHJ-a78rQH-nw3NvT-7aq2qf-8wwBso-3nNceh-ugSKP-4mh4kh-bbeeqH-a7biME-q3PtTf-brFpgb-cg38zw-bXMZc-nJPELD-f58Lmo-bXMYG-bz8AAi-bxNtNT-bXMYi-bXMY6-bXMYv)

O resultado:

Escapando caracteres

Para escapar um caractere no Markdown, ou seja, representá-lo de forma literal no documento, insira uma barra invertida antes dele.

Exemplo:

\* A barra invertida antes do asterisco faz com que o processador Markdown interprete essa linha como um parágrafo e não um elemento de uma lista.

O Resultado fica assim:

* A barra invertida antes do asterisco faz com que o processador Markdown interprete essa linha como um parágrafo e não um elemento de uma lista.

Caracteres que você pode escapar

A Tabela 1.20 mostra quais são o caracteres que você pode escapar no Markdown usando a barra invertida: \.

HTML e Markdown

Programadores que já possuem experiência em HTML, as vezes mesclam as duas sintaxes no mesmo documento, ou seja, HTML e Markdown.

O HTML pode ser útil em tarefas como mudar atributos dos elementos do seu documento como, cores, localização, tamanho e etc.

Coloque as tags HTML diretamente no seu documento.

**negrito** <em>itálico</em>

O Resultado fica assim:

negrito itálico

HTML e Markdown: melhores práticas

É importante ressaltar que nem todos os processadores Markdown são compatíveis com as tags HTML, em alguns casos, eles oferecem suporte somente a um subconjunto dessas tags.

Tentativa e erro pode ser uma estratégia. Tente formatar um conteúdo usando tags e verifique se a saída em HTML é a esperada, ou claro, consulte a documentação do aplicativo.

Não recue a linha das tags em HTML, nem com espaços em branco, nem com tabulações, isso pode interferir na formatação do elemento quando convertido.

Insira uma linha em branco antes e depois de elementos de bloco, exemplo: <div>, <table>, <pre>, <p>.

Evite colocar elementos Markdown dentro do conteúdo das tags HTML.

O código abaixo, apesar de funcionar em alguns editores, tem um mistura de sintaxe que pode gerar problemas de formatação.

<p>itálico **negrito**</p>