Aprenda Markdown
Markdown uma ferramenta de converso de text-to-HTML. Com ele possvel voc marcar
ttulos, listas, tabelas, etc., de forma muito mais limpa, legvel e precisa, do que se fosse fazer com
HTML.
Ainda no sabe tudo o que possvel fazer com Markdown? Ento esse post pra voc! Vem
comigo que eu te mostro :)
Onde usar Markdown
Existem vrios lugares que voc pode usar Markdown: No Github mesmo, voc pode usar no
README.md, que um arquivo que fica na raiz do seu projeto, e renderizado pelo Github abaixo
da lista de arquivos. Aquele texto que voc l quando acessa um repositrio um arquivo
README.md, escrito em Markdown.
Ainda no Github, voc pode usar Markdown no texto das issues, no texto de um pull request e na
wiki.
Tambm a maior parte dos geradores de estticos (Hexo, Jekyll, HarpJS, Docpad, etc.), permitem
escrever em Markdown! uma tima oportunidade pra voc que queria comear o seu blog, mas
estava com preguia de usar um CMS ou ficar fazendo HTML na mo xD
Porque eu devo aprender e usar Markdown
Porque HTML muito verboso! Markdown mais legvel, mais fcil de ler e interpretar.
Devo parar de escrever HTML para sites e fazer tudo em
Markdown?
No! Markdown serve basicamente para escrever textos. Como toda ferramenta, ele tem algumas
desvantagens com relao escrever em HTML:
Voc no consegue colocar atributos nos elementos (class, id, title, etc.), alm dos poucos
que ele permite por padro;
Voc no tem muito controle para fazer aninhamento de tags.
Por isso importante frisar que o uso do Markdown deve ser especificamente para a escrita de
textos, artigos de blog, etc. No para simplesmente us-lo no lugar do HTML!
Como eu comeo a escrever em Markdown
Se voc j tiver um parser, voc s precisa criar um arquivo com uma dessas extenses: mark,
markdown, md, mdml, mdown, text, mdtext, mdtxt, mdwn, mkd, mkdn.
Entre essas, a mais utilizada a md. Crie um arquivo com uma dessas extenses e voc j estar
apto para comear a escrever em Markdown!
Agora, se voc no tiver um parser, pode usar uma ferramenta online. Existem muitas ferramentas
de parse de Markdown para HTML. Vou recomendar uma para que voc possa acompanhar esse
post, mas buscando por Markdown Editor no Google, voc vai encontrar muitas outras!
Gosto bastante do Stack Edit. Ele converte Markdown para HTML enquanto voc digita.
bastante simples para ver o resultado :)
Vamos aprender ento como escrever em Markdown!
Ttulos (<h1> a <h6>)
Para marcar um ttulo, voc vai usar # a quantidade de vezes que ir representar o nvel do ttulo.
Exemplo:
1 # Ttulo nvel 1
2 ## Ttulo nvel 2
3 ### Ttulo nvel 3
4 #### Ttulo nvel 4
5 ##### Ttulo nvel 5
6 ###### Ttulo nvel 6
Parseia para:
1 <h1>Ttulo nvel 1</h1>
2 <h2>Ttulo nvel 2</h2>
3 <h3>Ttulo nvel 3</h3>
4 <h4>Ttulo nvel 4</h4>
5 <h5>Ttulo nvel 5</h5>
6 <h6>Ttulo nvel 6</h6>
Bastante simples, no? O h1 e o h2 ainda podem ser escritos da seguinte forma:
1 Ttulo de nvel 1
2 ==================
3
4 Ttulo de nvel 2
5 ------------------
Pargrafos e quebras de linha (<p> e <br />)
Para gerar pargrafos, basta voc escrever o texto em uma linha:
1 Este um pargrafo.
2
3 Este outro pargrafo.
Isso gera:
1 <p>Este um pargrafo.</p>
2 <p>Este outro pargrafo.</p>
Note que eu pulei uma linha entre os pargrafos. Se eu no fizesse isso, o cdigo gerado seria:
1 <p>Este um pargrafo. Este outro pargrafo.</p>
Mas ele no deveria usar um `
para quebrar linha?
Isso muito particular de cada parser. Alguns quebram linha quando voc d enter. Mas a
documentao do Markdown diz que, para quebras de linha, voc precisa deixar dois espaos no
final da linha:
1 Primeira linha do pargrafo.
2 Segunda linha do pargrafo.
Coloquei o no final da primeira linha somente para facilitar a visualizao. Voc deve substituir
esse smbolo por dois espaos em branco. Isso deve gerar:
1 <p>
2 Primeira linha do pargrafo.<br />
3 Segunda linha do pargrafo.
4 </p>
Por isso, se voc estiver usando o .editorconfig no seu projeto, deixe a opo
trim_trailing_whitespace como false para arquivos Markdown. Assim, os espaos
adicionais no sero removidos :)
nfase (<strong> e <em>)
Para enfatizar uma palavras (<em>), usamos um * ou _:
1 Javascript _cool_!
ou:
1 Javascript *cool*!
Que ir gerar:
1 <p>
2 Javascript <em>cool</em>!
3 </p>
O mais utilizado para nfase (<em>) o underline.
Para dar forte nfase em palavras (<strong>), voc usa dois ** ou __:
1 **Da2k** a pronncia para **Daciuk**: DA-TWO-K!
ou
1 __Da2k__ a pronncia para __Daciuk__: DA-TWO-K!
Que ir gerar:
1 <p>
2 <strong>Da2k</strong> a pronncia para <strong>Daciuk:</strong> DA-TWO-K!
3 </p>
O mais utilizado para forte nfase (<strong>) so dois asteriscos.
Links (<a>)
Para gerar links, voc usa [](). Dentro dos colchetes voc coloca o texto do link, e dentro dos
parnteses, voc coloca a URL:
1 [Blog do Da2k](https://blog.da2k.com.br)
Que ir gerar:
1 <a href="https://blog.da2k.com.br">Blog do Da2k</a>
Passando um texto aps a URL, separando o link do texto por um espao em branco, esse texto ser
usado como title:
1 [Blog do Da2k](https://blog.da2k.com.br "Clique e acesse agora!")
Vai gerar:
1 <a href="https://blog.da2k.com.br" title="Clique e acesse agora!">Blog do Da2k</a>
Links automticos
Se o texto do seu link o prprio link, voc pode envolv-lo entre < e >, que o link ser gerado
automaticamente:
1 <https://www.google.com.br>
Ir gerar:
1 <a href="https://www.google.com.br">https://www.google.com.br</a>
E isso funciona tambm para e-mails:
1 <meu@email.com>
Vai gerar:
1 <a href="mailto:meu@email.com">meu@email.com</a>
Da hora, no? ;)
Referncias
Expliquei sobre referncias nesse post.
Blocos de citao (<blockquote>)
Para criar blocos de citao, voc usa o sinal de >:
1 > Esse um bloco de citao.
2 > Ele pode ter vrias linhas por pargrafo.
3 >
4 > Inclusive, dando um espao, voc tem um novo pargrafo.
Que gera o seguinte:
1 <blockquote>
2 <p>
3 Esse um bloco de citao.
4 Ele pode ter vrias linhas.
5 </p>
6 <p>Inclusive, uma quebra de linha.</p>
7 </blockquote>
Listas (<ul> e <ol>)
Para listas no ordenadas (<ul>), voc pode usar *, + ou -. Veja:
1 * Item 1
2 * Item 2
3 * Item 3
4
5 + Item 1
6 + Item 2
7 + Item 3
8
9 - Item 1
10 - Item 2
11 - Item 3
Os trs formatos acima geram a mesma marcao:
1 <ul>
2 <li>Item 1</li>
3 <li>Item 2</li>
4 <li>Item 3</li>
5 </ul>
E para listas ordenadas, voc usa o nmero, seguido de ponto:
1 1. Item 1
2 2. Item 2
3 3. Item 3
Que ir gerar:
1 <ol>
2 <li>Item 1</li>
3 <li>Item 2</li>
4 <li>Item 3</li>
5 </ol>
Alguns parsers renderizam automaticamente os prximos nmeros, aps o 1. Voc s precisa usar *
para os itens do 2 em diante:
1 1. Item 1
2 * Item 2
3 * Item 3
Mas no so todos que renderizam dessa forma, ento bom ficar ligado ;)
Imagens (<img />)
Gerao de imagens bem parecido com a gerao de links: voc s precisa adicionar uma ! no
incio. E o texto que voc coloca entre os colchetes, usado como alt na imagem:
1 
Esse cdigo vai gerar:
1 <img src="http://cdn.osxdaily.com/wp-content/uploads/2013/07/dancing-banana.gif" alt="Ba
O title tambm funciona como no link:
1 ![Banana](http://cdn.osxdaily.com/wp-content/uploads/2013/07/dancing-banana.gif "Olha a
Que gera:
1 <img src="http://cdn.osxdaily.com/wp-content/uploads/2013/07/dancing-banana.gif" alt="Ba
Tabelas (<table>)
J falei sobre tabelas em um post anterior. Nesse post eu falo tambm sobre as task lists, mas
elas so especficas do Github, no funcionam com qualquer parser ;)
Cdigo inline e bloco (<code> e <pre>)
Voc ainda pode adicionar trechos de cdigo via Markdown. Para adicionar cdigo a nvel inline,
voc usa ```:
1 O `<blockquote>` uma tag HTML.
Isso ir gerar:
1 <p>
2 O <code><blockquote></code> uma tag HTML!
3 </p>
E para gerar blocos de cdigo, voc simplesmente indenta o cdigo 4 espaos (ou 1 tab) frente do
pargrafo:
1 Essa a funo sayHello():
2 function sayHello() {
3 return 'hi!';
4 }
Que ir gerar:
1 <p>
2 Essa a funo sayHello():
3 <pre><code>function sayHello() {
4 return 'hi!';
5 }</code></pre>
6 </p>
Isso como est na documentao. Mas a maior parte dos parses que eu conheo no funcionam
dessa forma. Eles geram blocos de cdigo usando trs crases no incio da primeira e ltima linha,
para marcar o incio e o fim do bloco:
PS.: Tive que colocar como imagem, pois o meu parser no consegue escapar as 3 crases
O Github inclusive recomenda que se use as 3 crases, pois mais fcil de visualizar e dar
manuteno no cdigo.
No Github, voc ainda consegue definir qual a linguagem que est sendo utilizada, para que seja
feito code highlight no seu cdigo. S passe a linguagem aps as 3 crases, dessa forma:
Que seu cdigo ser mostrado bonitinho assim:
:D
Backslash scapes
Para escapar caracteres que so parseados pelo Markdown, voc pode usar a barra invertida \
(backslash), seguida do caractere, para imprim-lo literalmente. O escape funciona para os
caracteres listados abaixo:
1 \ backslash (barra invertida)
2 ` backtick (crase)
3 * asterisk (asterisco)
4 _ underscore
5 {} curly braces (chaves)
6 [] square brackets (colchetes)
7 () parentheses (parnteses)
8 # hash mark (sustenido / hash / jogo da velha)
9 + plus sign (sinal de "mais" ou somar)
10 - minus sign (hyphen) (sinal de menos ou hfen)
11 . dot (ponto)
12 ! exclamation mark (ponto de exclamao)
Alm de tudo isso, importante saber tambm, que possvel usar HTML junto com Markdown!
Isso mesmo! Se voc precisar adicionar uma classe em uma imagem para alinhar, ou colocar uma
cor especfica em alguma palavra, voc pode usar tags HTML normalmente :D
