Guia de Markdown - big-data-estacio/data GitHub Wiki

O Markdown é uma linguagem de marcação simples que permite escrever documentos formatados sem precisar aprender HTML ou outras linguagens mais complexas. É amplamente utilizado em plataformas de blogging, wikis, fóruns e outros tipos de conteúdo online.
Com a popularização do GitHub, e também da grande quantidade de novos programadores ultimamente, a demanda para aprender Markdown aumentou bastante. Markdown é uma linguagem de marcação, parecido com a sua companheira HTML.
A maior utilidade dela atualmente certamente é para criar os famosos READMEs para seus repositórios no GitHub, e deixar o seu projeto mais 'apresentável'. E é por isso que hoje trago aqui um guia simples porém definitivo para aprender a tão famosa Markdown e a importancia de um bom README em seu projeto para iniciantes.
Todo projeto seu no GitHub terá seus códigos, seus arquivos, suas pastas todas jogadas lá. Um projeto digno e bem estruturado precisa passar para o leitor o sentido do seu projeto, para que ele serve, como funciona, quais linguagens, sistemas, funcionalidades, ferramentas você utilizou para criar seu programa, como contribuir, e dezenas de outras informações necessárias tem que ficar bem explicitas ao leitor quando o mesmo se deparar com seu repositório.
E para isso existe um arquivinho bem simples chamado 'README.md' ou 'readme.md' em todo repositório no mínimo organizado no GitHub. Perceba que o arquivo possui o sufixo '.md', essa é a terminologia de arquivos Markdown. Ao criar o README.md em seu repositório, ao rolar um pouco para baixo a página inicial, todo o conteúdo formatado em Markdown irá aparecer, contendo todas as informações necessárias para o projeto. Para ver o conteúdo sem formatação, procure um ícone de um lápis, ou até clique no arquivo em si README.md, assim você será encaminhado para a edição do arquivo.
Fica claro aqui, que são todas opicionais, cabe a você desenvolvedor a analisar e escolher quais colocar em seu repositório, lembrando que nem todos pontos a seguir cabem em todos os repositórios, depende do que se trata ele, se é um jogo, um programa, um código-fonte de um site, saiba escolher o que colocar.
- Introdução
Uma breve apresentação sobre o que é o seu projeto, o que ele faz, e algumas informações úteis para serem ditas inicialmente.
- Índice
Assim como nesse readme.md também tem, é interessante ter um índice com os links para os tópicos que vão ser abordados em seu texto.
- Habilidaes adiquiridas ou requisitadas para o projeto
Se tens posse de um projeto que visa a aprendizagem, o seu próprio estudo ou até base para estudos de outras pessoas, é interessante colocar quais habilidades são requeridas para estudar/rodar o seu código, ou habilidades que vão ser adiquiridas se seguirem os seus estudos.
- Como executar
Se tens um programa que faz alguma coisa, um jogo, um código em determinada linguagem, é interessante adicionar a informação de como executar seus códigos, quais programas precisa no computador do usuário, comando para executar os códigos, algumas informaçãoes de quais arquivos precisa ter, entre diversos outros.
- Contribuindo
Se teu projeto é OpenSource, é natural que outros progamadores irão querer melhorar seu projeto, adicionando novos recursos, corrigindo algum bug, implementando alguma tecnologia, entre diversos outros, para isso ele deverá fazer pulls requests em seu código, seria muito interessante implementar algumas informações de como contribuir com o projeto, como fazer um Fork, como fazer o pull request, e até algumas preferências pessoais suas de como queres o pull request
- Créditos e Licença
É interessante também em alguns casos concluir com os créditos do repositório ou até mesmo da licença utilizada nele.
Note que não são todos os pontos a colocar, tão pouco são obrigatórios, pensei apenas em ajudar os iniciantes que estão criando teus repositórios no momento, e alguns pontos que são muito importantes para projetos simples. Claro que projetos mais avançados requerem muito mais pontos a ser colocados, e depende muito de um para outro. O foco destas dicas é pensando nos projetos mais básicos e iniciantes.
- Títulos
- Ênfase
- Linha Horizontal
- Citações
- Listas
- Códigos
- Links
- Imagens
- Links em imagens
- Tabelas
- HTML Embutido
- Créditos
Inicialmente temos os 'Headings', ou Títulos, que é semelhante à linguagem de marcação HTML. Existe uma herança de títulos, em que diferem não só o tamanho da fonte, como também semânticamente. Ou seja, o título número 1 é mais importante que o título número 2, que por sua vez é mais importante que o número 3, e assim por diante.
Existem 6 títulos, que vai do título 1 (mais importante e por conseguinte maior e mais destacado) até o título 6 (menos importante e por conseguinte menor e menos destacado).
A sintaxe é simples:
# Título 1
## Título 2
### Título 3
#### Título 4
##### Título 5
###### Título 6
Vai de acordo com a quantidade de '#'. Exemplos:
Você pode adicionar ênfase ao seu texto, como por exemplo o negrito, o itálico, ou até mesmo negrito e itálico. Lembre-se que além da aparência do seu texto, existe a semântica para ser seguida. Textos em negrito devem ser lidos com força, intensidade, e o itálico significa uma ênfase maior.
Sintaxe do negrito:
Este é **negrito**
This is __strong__
Sintaxe do itálico:
Este é *itálico*
This is _italic_
Sintaxe do negrito e itálico:
**_strong and em_**
Sintaxe do texto riscado:
~~riscado~~
Você pode adicionar linhas horizontais para deixar o texto mais organizado e apresentável. Usando três hífens, três asteriscos ou três underscore:
Hífens
---
Asteriscos
***
Underscore
___
Learning Center:
Hífens
Asteriscos
Underscore
Para criar uma citação em bloco, adicione um '>' na frente de um parágrafo.
As citações em bloco podem conter vários parágrafos. Adicione um '>' nas linhas em branco entre os parágrafos
Sintaxe:
Para citações em uma linha:
> Esta é uma citação
Em várias linhas:
> Citação 1
>
> Citação 2
Resultado:
Para citações em uma linha:
Esta é uma citação
Em várias linhas:
Citação 1
Citação 2
As cotações em bloco podem ser aninhadas. Adicione um '>>' na frente do parágrafo que você deseja aninhar. Por exemplo:
> Citação 1
>
>> Citação 2
E assim temos:
Citação 1
Citação 2
As citações de bloco podem conter outros elementos no formato Markdown. Nem todos os elementos podem ser usados, você precisará experimentar para ver quais funcionam. Exemplo:
> ##### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
> *Everything* is going **well**.
Resultado:
- Revenue was off the chart.
- Profits were higher than ever.
Everything is going well.
Você pode organizar listas, podendo ser ordenadas ou não.
Listas Ordenadas
Usando (número)(ponto) você pode ordenar as listas numericamente, como por exemplo:
1. Primeiro
2. Segundo
3. Terceiro
4. Quarto
Vai gerar o seguinte resultado:
- Primeiro
- Segundo
- Terceiro
- Quarto
Itens da lista de aninhamento
Para aninhar itens de linha em uma lista ordenada, recue os itens quatro espaços ou uma guia.
1. Primeiro item
2. Segundo item
3. Terceiro item
1. Indentado item
2. Indentado item
4. Quarto item
Irá gerar:
- Primeiro item
- Segundo item
- Terceiro item
- Indentado item
- Indentado item
- Quarto item
Listas não Ordenadas
Para criar uma lista não ordenada, adicione traços (-), asteriscos (*) ou sinais de adição (+) na frente de itens de linha.
- Exemplo 1
* Exemplo 2
+ Exemplo 3
Vai gerar:
- Exemplo 1
- Exemplo 2
- Exemplo 3
Lista de tarefas
Podemos criar também uma lista de tarefas, com a CheckBox preenchida ou não. Vejamos o exemplo:
- [ ] Esta é uma CheckBox não marcada
- [x] Esta é uma CheckBox marcada
Learning Center:
- Esta é uma CheckBox não marcada
- Esta é uma CheckBox marcada
Para colocar algum código sem que ele esteja formatado, então poderá colocar algum código em Markdown dentro dos trechos de códigos e ele não será formatado, será mostrado exatamento como escreveu, é desse jeito que eu consigo mostrar para vocês os códigos como são originalmente antes de serem formatados em .md.
Temos o trecho simples, sendo de apenas uma linha, usando uma crase para abrir e outra para fechar:
` este é um exemplo `
Resultado:
este é um exemplo
E também temos a mais completa, que podemos colocar quantas linhas de códigos nós quisermos. Use três crases ( ´´´ ) ou três tils ( ~~~ ) para abrir e três para fechar, desse jeito:
```
Este é nosso
Querido Exemplo
**Teste**
Nota que não irá formatar o negrito!
```
Vai gerar:
Este é nosso
Querido Exemplo
**Teste**
Nota que não irá formatar o negrito!
Para especificar qual lingugem seu código é feito, isso ajuda tanto semânticamente como também na coloração do código, basta adicionar o nome da lingugem logo após os três primeiros tils ou crases. Por exemplo:
~~~python
s = "Sintaxe do Pythong"
print s
~~~
s = "Sintaxe do Python"
print sPara saber quais lingugens são suportadas por este mecanismo, clique aqui e veja a listagem do Pygments.
Nota: Para interligar um código dentro do outro, assim como eu fiz de exemplo para vocês: Abra o primeiro trecho de código com as três crases, e feche de imediato. Dentro desse código use a indentação de 4 espaços, e assim poderá abrir outro código sem formatar.
É possível colocar algum link em seu 'Readme', e ainda colocá-lo por debaixo de uma palavra, é o chamado link-âncora, acessando-o ao clicar na palavra. Entre colchetes [ ] a palava que deseja por debaixo dos panos. E entre parentêses ( ) o link para acesso. Vejamos o exemplo do código:
Clique [aqui](https://github.com) para acessar à página do GitHub.
Resultado: Clique aqui para acessar à página do GitHub.
Lembre-se que pode criar links para outros repositórios seus no GitHub, também é possível acessar outro arquivo no mesmo repositório, e até mesmo a posição da página do leitor no mesmo arquivo. Por exemplo, clique aqui para acessar o título 'Sintaxe' neste mesmo arquivo. Tais possibilidades deixam seu README bem mais apresentável, e com uma interatividade maior, demonstrando que o escritor do código entende bem de MarkDown.
Para links sem uma palavra por cima do link, use '< >' para envolver o link desejado, assim o link aparecerá por inteiro ao leitor. Exemplo: https://google.com.br
Semelhante ao mecanismo de adicionar links-âncora, podemos adicionar imagens para nosso aquivos.md também, mas tome cuidado com a resolução da imagem, imagens grandes podem estar em linhas individuais, para serem exibidas em maior tamanho.
A sintaxe é parecida, apenas adicione uma exclamação (!) no início.

Você pode fazer com que uma imagem carregue um link por debaixo dos panos, e ao clicar nela, acesse o link. É uma mescla tanto semânticamente quanto na sintaxe. Vejamos:
Clique na imagem para acessar o Google.
[
Clique na imagem para acessar o Google.
Escolha os títulos das colunas e use | para delimitar as colunas. Depois, utilize hífen - na segunda linha para indicar que acima estão os títulos das colunas, usando novamente o | para delimitar colunas. Veja um exemplo abaixo:
Teste | Exemplo
------- | ------
Teste 1 | Exemplo 1
Teste 2 | Exemplo 2
Teste 3 | Exemplo 3
Teste 4 | Exemplo 4
No Learning Center irá aparecer:
| Teste | Exemplo |
|---|---|
| Teste 1 | Exemplo 1 |
| Teste 2 | Exemplo 2 |
| Teste 3 | Exemplo 3 |
| Teste 4 | Exemplo 4 |
Para especificar o tipo de alinhamento que deseja ter nas tabelas, utilize dois pontos : ao lado do campo horizontal de hífens ---, na segunda linha da sua tabela. Veja abaixo:
- Alinhado a esquerda: usar
:no lado esquerdo (alinhamento padrão) - Alinhado a direita: usar
:no lado direito - Centralizado: usar
:dos dois lados
Exemplo:
Alinhado a esquerda | Centralizado | Alinhado a direita
:--------- | :------: | -------:
Exemplo | Exemplo | Exemplo
Learning Center:
| Alinhado a esquerda | Centralizado | Alinhado a direita |
|---|---|---|
| Exemplo | Exemplo | Exemplo |
Você também pode usar HTML bruto no seu Markdown, e geralmente funcionará muito bem.
Vejamos:
<dl>
<dt>Lista definitiva</dt>
<dd>É algo que as pessoas usam às vezes.</dd>
<dt>Markdown no HTML</dt>
<dd>*Não* funciona **muito bem**. Use as <em>tags</em> do HTML</dd>
</dl>
- Lista definitiva
- É algo que as pessoas usam às vezes.
- Markdown no HTML
- *Não* funciona **muito bem**. Use as tags do HTML
O MarkDown também permite colocar alguns emojis em seus textos, não abuse deles para não parecer um circo de diversões, só em alguns casos bem específicos.
:nome_do_emoji:
Alguns exemplos:
:smile: :fire: :file_folder: :space_invader: :computer: :tada:
😄 🔥 📁 👾 💻 🎉
Para conferir uma lista com os emojis e suas sintaxes, clique aqui: EMOJIS
-
As notas de rodapé permitem adicionar notas e referências sem sobrecarregar o corpo do documento. Quando você cria uma nota de rodapé, um número sobrescrito com um link aparece onde você adicionou a referência da nota de rodapé. Os leitores podem clicar no link para pular para o conteúdo da nota de rodapé na parte inferior da página.
-
Para criar uma referência de nota de rodapé, adicione um cursor e um identificador entre colchetes ([^1]). Os identificadores podem ser números ou palavras, mas não podem conter espaços ou tabulações. Os identificadores apenas correlacionam a referência da nota de rodapé com a própria nota de rodapé — na saída, as notas de rodapé são numeradas sequencialmente.
-
Adicione a nota de rodapé usando outro cursor e número entre colchetes com dois pontos e texto ([^1]: Minha nota de rodapé.). Você não precisa colocar notas de rodapé no final do documento. Você pode colocá-los em qualquer lugar, exceto dentro de outros elementos, como listas, citações de bloco e tabelas.
Here's a simple footnote,[^1] and here's a longer one.[^bignote]
[^1]: This is the first footnote.
[^bignote]: Here's one with multiple paragraphs and code.
Indent paragraphs to include them in the footnote.
`{ my code }`
Add as many paragraphs as you like.Muitos processadores Markdown oferecem suporte a IDs personalizados para cabeçalhos - alguns processadores Markdown os adicionam automaticamente. Adicionar IDs personalizados permite vincular diretamente aos cabeçalhos e modificá-los com CSS. Para adicionar um ID de título personalizado, coloque o ID personalizado entre chaves na mesma linha do título.
### My Great Heading {#custom-id}O HTML fica assim:
<h3 id="custom-id">My Great Heading</h3>Alguns processadores Markdown permitem que você crie listas de definição de termos e suas definições correspondentes. Para criar uma lista de definições, digite o termo na primeira linha. Na próxima linha, digite dois pontos seguidos por um espaço e a definição.
First Term
: This is the definition of the first term.
Second Term
: This is one definition of the second term.
: This is another definition of the second term.O HTML fica assim:
<dl>
<dt>First Term</dt>
<dd>This is the definition of the first term.</dd>
<dt>Second Term</dt>
<dd>This is one definition of the second term. </dd>
<dd>This is another definition of the second term.</dd>
</dl>Você pode riscar palavras colocando uma linha horizontal no centro delas. O resultado se parece com isso. Este recurso permite que você indique que certas palavras são um erro que não deve ser incluído no documento. Para tachar palavras, use dois símbolos de til (~~) antes e depois das palavras.
~~The world is flat.~~ We now know that the world is round.A saída renderizada fica assim:
~~The world is flat.~ We now know that the world is round.
Isso não é comum, mas alguns processadores Markdown permitem que você use o subscrito para posicionar um ou mais caracteres um pouco abaixo da linha normal do tipo. Para criar um subscrito, use um símbolo de til (~) antes e depois dos caracteres.
H~2~OA saída renderizada fica assim:
H2O
Isso não é comum, mas alguns processadores Markdown permitem que você use o sobrescrito para posicionar um ou mais caracteres um pouco acima da linha normal do tipo. Para criar um sobrescrito, use um símbolo de circunflexo (^) antes e depois dos caracteres.
X^2^A saída renderizada fica assim:
X2
Muitos processadores Markdown transformam URLs em links automaticamente. Isso significa que, se você digitar
http://www.example.com, seu processador Markdown o transformará automaticamente em um link, mesmo que você não tenha usado colchetes.
http://www.example.comA saída renderizada fica assim:
Se você não deseja que um URL seja vinculado automaticamente, pode remover o link denotando o URL como código com backticks.
http://www.example.com`A saída renderizada fica assim:
-
Um bloco HTML é um grupo de linhas que é tratado como HTML bruto (e não terá escape na saída HTML).
-
Existem sete tipos de bloco HTML, que podem ser definidos por suas condições iniciais e finais. O bloco começa com uma linha que atende a uma condição inicial (após até três espaços recuo opcional). Ele termina com a primeira linha subseqüente que atende a uma condição final correspondente, ou a última linha do documento, ou a última linha do bloco contêiner contendo o bloco HTML atual, se nenhuma linha for encontrada que atenda à condição final. Se a primeira linha atender tanto à condição inicial quanto à condição final, o bloco conterá apenas essa linha.
-
Condição inicial: a linha começa com a string <script, <pre ou <estilo (sem distinção entre maiúsculas e minúsculas), seguida por um espaço em branco, a string > ou o final da linha. Condição final: a linha contém uma tag final </script>, ou </style> (não diferencia maiúsculas de minúsculas; não precisa corresponder à tag inicial).
-
Condição inicial: a linha começa com a string .
-
Condição inicial: a linha começa com a string . Condição final: a linha contém a string ?>.
-
Condição inicial: a linha começa com a string <! seguido por uma letra ASCII maiúscula. Condição final: a linha contém o caractere >.
-
Condição inicial: a linha começa com a string .
-
Condição inicial: a linha começa a string < ou </ seguida por uma das strings (sem distinção entre maiúsculas e minúsculas) endereço, artigo, lado, base, fonte base, citação, corpo, legenda, centro, col, colgroup, dd, detalhes, diálogo, dir, div, dl, dt, fieldset, figcaption, figura, rodapé, formulário, quadro, conjunto de quadros, h1, h2, h3, h4, h5, h6, cabeça, cabeçalho, hr, html, iframe, legenda, li, link, main, menu, menuitem, nav, noframes, ol, optgroup, option, p, param, section, source, summary, table, tbody, td, tfoot, th, thead, title, tr, track, ul, seguido por espaço em branco, o final da linha, a string > ou a string />. Condição final: a linha é seguida por uma linha em branco.
-
Condição inicial: a linha começa com uma tag de abertura completa (com qualquer nome de tag diferente de script, style ou pre) ou uma tag de fechamento completa, seguida apenas por um espaço em branco ou no final da linha. Condição final: a linha é seguida por uma linha em branco.
Os blocos HTML continuam até serem fechados por sua condição final apropriada ou até a última linha do documento ou outro bloco de contêiner. Isso significa que qualquer HTML dentro de um bloco HTML que possa ser reconhecido como uma condição inicial será ignorado pelo analisador e transmitido como está, sem alterar o estado do analisador.
Por exemplo, <pre> dentro de um bloco HTML iniciado por <table> não afetará o estado do analisador; como o bloco HTML foi iniciado pela condição inicial 6, ele terminará em qualquer linha em branco. Isso pode ser surpreendente:
<table><tr><td>
<pre>
**Hello**,
_world_.
</pre>
</td></tr></table>
**Hello**, |
<table>
<tr>
<td>
hi
</td>
</tr>
</table>
okay.| hi |
okay.
Marcas HTML projetadas para conter conteúdo literal (script, estilo, pré), comentários, instruções de processamento e declarações são tratadas de maneira um pouco diferente. Em vez de terminar na primeira linha em branco, esses blocos terminam na primeira linha que contém uma marca final correspondente. Como resultado, esses blocos podem conter linhas em branco:
Uma etiqueta pré (tipo 1):
<pre language="haskell"><code>
import Text.HTML.TagSoup
main :: IO ()
main = print $ parseTags tags
</code></pre>
okay
import Text.HTML.TagSoup
main :: IO ()
main = print $ parseTags tags
okay
<script type="text/javascript"> // JavaScript example document.getElementById("demo").innerHTML = "Hello JavaScript!"; </script>okay
Uma tag de estilo (tipo 1):
<style
type="text/css">
h1 {color:red;}
p {color:blue;}
</style>
okay-
Uma definição de referência de link consiste em um rótulo de link, recuado até três espaços, seguido por dois pontos (:), espaço em branco opcional (incluindo até um final de linha), um destino de link, espaço em branco opcional (incluindo até um final de linha), e um título de link opcional, que se estiver presente deve ser separado do destino do link por um espaço em branco. Nenhum outro caractere que não seja espaço em branco pode ocorrer na linha.
-
Uma definição de referência de link não corresponde a um elemento estrutural de um documento. Em vez disso, ele define um rótulo que pode ser usado em links de referência e imagens de estilo de referência em outras partes do documento. As definições de referência de link podem vir antes ou depois dos links que as utilizam.
[Mais sobre Markdown]:
<https://github.github.com/gfm/#container-blocks>
'title'
[Mais sobre Markdown]Mais de um Link
[foo]: /foo-url "foo"
[bar]: /bar-url
"bar"
[baz]: /baz-url
[foo],
[bar],
[baz]Equações podem ser escritas em LaTeX usando o símbolo de duplo dólar ($$) e o ambiente de equação. Por exemplo:
$$
x^2 + 2x + 1 = 0
$$resultará em:
Frações podem ser escritas em LaTeX usando o comando frac. Por exemplo:
$$
\frac{a}{b}
$$resultará em:
Radicais podem ser escritos em LaTeX usando o comando sqrt. Por exemplo:
$$
\sqrt{x^2 + y^2}
$$resultará em:
Derivadas podem ser escritas em LaTeX usando o comando frac e o operador \frac{d}{dx}. Por exemplo:
$$
\frac{d}{dx} x^2 = 2x
$$resultará em:
Integrais podem ser escritas em LaTeX usando o comando \int. Por exemplo:
$$
\int_{0}^{\infty} e^{-x^2} dx
$$resultará em:
A média pode ser escrita em LaTeX usando o comando \bar. Por exemplo:
$$
\bar{x} = \frac{\sum_{i=1}^{n} x_i}{n}
$$resultará em:
O desvio padrão pode ser escrito em LaTeX usando o comando \sigma. Por exemplo:
$$
\sigma = \sqrt{\frac{\sum_{i=1}^{n} (x_i - \bar{x})^2}{n-1}}
$$resultará em:
O teorema de Pitágoras pode ser escrito em LaTeX usando o comando sqrt. Por exemplo:
$$
c = \sqrt{a^2 + b^2}
$$resultará e
A área de um círculo pode ser escrita em LaTeX usando o comando \pi. Por exemplo:
$$
A = \pi r^2
$$resultará em:
Para incluir cálculos matemáticos em markdown, você pode usar o formato LaTeX, que é amplamente utilizado na escrita científica e matemática. O LaTeX permite que você escreva expressões matemáticas complexas em um formato legível para humanos, que pode ser convertido em representações gráficas de alta qualidade.
Para utilizar o LaTeX em markdown, você precisa colocar a expressão matemática entre símbolos de dólar ($)
ou dois pares de dólares ($$). Aqui estão alguns exemplos:
Para uma expressão em linha: Coloque a expressão matemática entre um par de símbolos de dólar ($).
Por exemplo, $a^2 + b^2 = c^2$ seria exibido como
Para uma expressão em destaque: Coloque a expressão matemática entre dois pares de símbolos de dólar ($$). Por exemplo,
$$\frac{\mathrm{d}}{\mathrm{d}x} \int_{a}^{x} f(t)\,\mathrm{d}t = f(x)$$seria exibido como
Para criar uma equação numerada, use o seguinte formato:
$$
\begin{equation}
f(x) = \frac{1}{\sqrt{2\pi}\sigma} e^{-\frac{(x-\mu)^2}{2\sigma^2}}
\end{equation}
$$Isso resultará em uma equação numerada, como mostrado abaixo.
Ao utilizar o LaTeX em markdown, é importante lembrar que ele pode ser um pouco complicado de aprender no início. Mas, com a prática, você será capaz de escrever expressões matemáticas complexas de forma eficiente e profissional.
Com o uso adequado do LaTeX, é possível incluir cálculos matemáticos em Markdown de forma clara e profissional. Cada categoria de exemplo apresentado acima pode ser adaptada para
Copyright (C) 2020 by Gustavo Mendel
