Markdown¶

Como vimos anteriormente, Markdown é a principal forma de se agregar valor a um notebook. Nesta seção veremos com detalhes como utilizar Markdown em notebooks Jupyter. Markdown, no entanto, tem diversas aplicações além de criar notebooks - por exemplo, páginas iniciais de repositórios Github são criados em .md (a extensão de Markdown). Este livro é outro exemplo, já que foi criado com um misto de notebooks Jupyter (.ipynb) e Markdown (.md).

Nota

Markdown é uma linguagem de marcação (markup language) leve que adiciona elementos de formatação a textos. Além disto, Markdown permite de forma simples o acréscimo de elementos visuais ao texto (figuras, tabelas, vídeos, etc.).

Com certeza você tem contato diário com linguagens de marcação - mesmo sem saber. A maioria das páginas de internet é construída com HTML (hypertext markup language), a linguagem de marcação nais conhecida atualmente. Vamos comparar HTML com Markdown para a criação de um parágrafo simples:

   <h1>Título</h1>
    <p>
      <a href="https://fellipemartins.github.io/python_nao_programadores/intro.html">Neste link</a> você encontra a página inicial deste livro.
    </p>

Este bloco de código cria um título (o texto entre os marcadores <h1> e </h1>), um parágrafo (de <p> a </p>) e um link (<a href="...."> a </a>)

Agora, vamos fazer o mesmo em Markdown:

# Título

[Neste link](https://fellipemartins.github.io/python_nao_programadores/intro.html) você encontra a página inicial deste livro.

Como você pôde observar, o mesmo objetivo pôde ser cumprido tanto com HTML quanto com Markdown. Contudo, com Markdown é bastante mais simples, já que Markdown tem o propósito de facilitar o desenvolvimento de formatação e adição de elementos em uma página de forma mais intuitiva. O motivo para compararmos com HTML é que, na verdade, Markdown é um superconjunto de HTML. Veja a figura abaixo:

Fig. 7 Funcionamento do Markdown (simplificado) - Adaptado de markdownguide.org¶

De forma simples, a formatação em Markdown é levada a um aplicativo que converte a formatação para HTML, cujo resultado final é mostrado (a página como vemos). Assim, com Markdown é possível desviar de ter que criar códigos com todo o detalhamento requerido pelos protocolos HTML. Por outro lado, Markdown é limitado e, em muitas situações, você terá que utilizar HTML padrão para obter os resultados desejados. No fim, você pode utilizar somente código em Markdown, em HTML ou uma mistura de ambos - que é o cenário mais provável caso você queria fazer um notebook mais bonito sem ter que se tornar um designer HTML pleno.

Veja também

Para ver mais usos e aplicações de Markdown, esta página contém muitas informações úteis.

Dica

Para usar Markdown em uma célula em um notebook Jupyter, basta clicar na célula e mudar no menu de Code para Markdown. Alternativamente, você pode navegar até a célula desejada usando esc e setas e apertar M. Na seção Notebooks Jupyter, você encontra mais atalhos úteis.

Criando títulos¶

Para adicionar títulos a uma célula, você utilizará o marcador cerquilha (#), equivalente ao H em HTML.

Dica

A lógica de tamanho dos títulos é do maior para o menor, tanto em Markdown quanto HTML. A diferença é que em Markdown para cada nível menor, você acrescenta um asterisco (# = H1, ## = H2, etc.).

`Markdown`	`HTML`
`#` Título	`<H1>` Título `</H1>`
`##` Título	`<H2>` Título `</H2>`
`###` Título	`<H3>` Título `</H3>`
`####` Título	`<H4>` Título `</H4>`

Formatando texto¶

O texto em Markdown é geralmente feito em Unicode. Unicode é um padrão internacional de codificação de texto que inclui praticamente todos as formas de escrita em línguas modernas, muitas línguas antigas e arcaicas (incluindo centenas de alfabetos e sistemas não alfabéticos) bem como emoji.

Veja também

Para conhecer mais sobre o padrão Unicode, veja a página oficial.

Para texto normal, basta escrever normalmente - isto inclui o uso de emoji.

Exemplo:

Este emoji representa alguém ao computador: 👨🏻‍💻.

Resultado: Este emoji representa alguém ao computador: 👨🏻‍💻.

Veja também

Qualquer emoji em formato Unicode será aceito pelo Markdown. Há diversos sites onde você pode encontrá-los (basta buscar por emoji unicode). Uma sugestão é este site, que nós já usamos frequentemente.

Formatação específica de `Markdown`¶

Para adicionar formatação ao texto, veja a tabela abaixo e os exemplos em seguida. Perceba que necessariamente os marcadores (*, _, ` ou ~~) tem que estar diretamente ligados ao início e fim do trecho formatado, mesmo que haja espaços em branco no meio.

Formatação	`Markdown`
Itálico	`palavra` ou `_palavra_`
Negrito	`palavra` ou `__palavra__`
Itálico + negrito	`*palavra*` ou `___palavra___`
Linha	`***`, `---` ou `___`

Exemplos:

O artigo encontrado **nesta página** pode ser útil.
O termo em inglês *feature* é tradicionalmente traduzido por variável.
A variável ano recebe um valor ***numérico discreto*** (números inteiros).
***

Resultado:
O artigo encontrado nesta página pode ser útil.
O termo em inglês feature é tradicionalmente traduzido por variável.
A variável ano recebe um valor numérico discreto (números inteiros).

Você pode criar blocos separados de texto (para citações, ênfase, etc.) usando >:

Exemplos:

> **"Capacidade não serve de nada sem oportunidade"** (Napoleão Bonaparte)

Resultado:

“Capacidade não serve de nada sem oportunidade” (Napoleão Bonaparte)

Formatação específica em `HTML`¶

Para outras formatações, você terá que usar HTML:

Formatação	`HTML`
Cor	`<font color=#000000> palavra </font>`
Sublinhado	`<u> palavra </u>`
Taxado*	`<s> palavra </s>`
Quebra de linha	`<br>`

*Taxado em Markdown é tradicionalmente escrito ~~palavra~~, mas alguns navegadores / IDEs não reconhecem.

Exemplos:

O resultado deste ano foi <font color="#DC143C">-67%</font> em comparação à <u>década inteira anterior</u>.  <br>
A <s>feature</s> variável tem efeito significante no modelo.

Resultado:
O resultado deste ano foi -67% em comparação à década inteira anterior.
A ~~feature~~ variável tem efeito significante no modelo.

Veja também

Para por uma cor específica em uma fonte, em HTML você pode usar nomes em inglês (Red) ou números hexadecimais (#FF0000). Veja uma tabela com opções de cores por nomes ou número hexadecimais, organizado por cores, neste site .

Formatando código¶

Um notebook Jupyter permite alternar entre células contendo código e conteúdo em Markdown. No entanto, há situações em que pode ser necessário escrever código dentro de células Markdown (por motivos pedagógicos, instrucionais ou de reprodutibilidade, por exemplo).

Formatação	`Markdwon` ou `HTML`
Código	`palavra` ou `<code> palavra </code>`

Exemplo:

A variável `ID` recebe um número inteiro enquanto a variável `Name` recebe texto.

Resultado:
A variável ID recebe um número inteiro enquanto a variável Name recebe texto.

Estas formas acima são úteis para pequenos trechos de código, mas sem marcação de sintaxe por cores. Para trechos mais longos de código, você pode usar ambos, mas em Markdown há duas formas - com ou sem marcação de sintaxe. Em ambas as formas você deverá incluir o código entre ``` … ``` . No entanto, caso queira marcação de sintaxe por cor, adicione a linguagem diretamente ligado ao primeiro ``` (em letras minúsculas; html, markdown, python, etc.).

Exemplos:

Sem marcação de sintaxe:
```
a = 2
if a > 1.5 :
    print(" it is > 1.5 " )
```

Com marcação de sintaxe:
```python
a = 2
if a > 1.5 :
    print(" it is > 1.5 " )
```

Resultado:
Sem marcação de sintaxe

a = 2
if a > 1.5 :
    print(" it is > 1.5 " )

Com marcação de sintaxe:

a = 2
if a > 1.5 :
    print(" it is > 1.5 " )

Criando listas¶

Para criar listas, você pode usar os marcadores * e -.

Atenção

Para criar listas, deve haver um espaço em branco entre o marcador (*/-) e a palavra seguinte. No caso do marcador *, quando diretamente ligado à palavra seguinte, impõe formatação itálica à palavra (veja mais no tópico Formatando texto).

* Carne
* Queijo
* Calabresa

Para criar subníveis em uma lista, use espaçamento (tab):

* Esfirras:
  * Carne
  * Queijo
  * Calabresa
    * pura
    * com queijo

Resultado:

Esfirras:
- Carne
- Queijo
- Calabresa
  - pura
  - com queijo

Perceba que a formatação de níveis é feita de forma automática.

Você também pode criar listas numéricas (use o número seguido de ponto, por exemplo, 1., 2., etc):

Exemplo:

Abertura
Desenvolvimento
Argumentos
Contra-argumentos
Fechamento

Resultado:

Abertura
Desenvolvimento
1. Argumentos
2. Contra-argumentos
Fechamento

Você também pode criar listas de tarefas usando - [ ] ou -[x]:

Exemplo:

- [x] Desenvolvimento
- [ ] Teste
- [ ] Relatório 

Resultado:

Desenvolvimento
Teste
Relatório

Criando tabelas¶

A criacão de tabelas em Markdown é relativamente simples. As colunas são criadas separando-se por |. Separa-se a linha dos títulos do conteúdo da tabela por -- (pelo menos dois - mas você pode adicionar mais, para organização do seu código).

Exemplo:

| Estado | Capital | Pop. (mi.)|
| -- | -- | -- |
| SP | São Paulo | 11.3 |
| MG | Belo Horizonte | 4.5 |

Resultado:

Estado	Capital	Pop. (mi.)
SP	São Paulo	11.3
MG	Belo Horizonte	4.5

Para adicionar alinhamento às células da sua tabela, use :-- para alinhar à esquerda, :--: para centralizar e --: para alinhar à direita:

Exemplo:

| Estado | Capital | Pop. (mi.)|
| --: | :--: | :-- |
| SP | São Paulo | 11.3 |
| MG | Belo Horizonte | 4.5 |

Resultado:

Estado	Capital	Pop. (mi.)
SP	São Paulo	11.3
MG	Belo Horizonte	4.5

Erro

Nem todos os IDEs / navegadores renderizam alinhamento de tabelas em Markdown corretamente. Por exemplo, a biblioteca Jupyter boook (que usamos para criar este livro), não alinha corretamente. No entanto, em um notebook Jupyter (incluindo Jupyter Lab) e IDEs como VSCode, funciona normalmente.

Inserindo expressões matemáticas com `Latex`¶

Markdown não tem suporte proóprio para expressões matemáticas, mas permite que você utilize outra linguagem de marcação para isto - a Latex. Latex é uma linguagem de marcação muito utilizada na academia, particularmente adotada em ciências exatas e engenharias. Neste tópico vamos ver uma introdução à escrita de expressões matemáticas com Latex.

Para inserir uma expressão matemática, use o marcador $ no início e fim da expressão.

Exemplo:

$a = 10$

Resultado:
$a = 10$

Abaixo se encontram os símbolos matemáticos mais comuns (além dos já encontrados no teclado):

Símbolo	`Latex`
multiplicação	`\times` ($x$)
divisão	`\div` ($\div$)
diferente de	`\neq` ($\neq$)
menor ou igual a	`\leq` ($\leq$)
maior ou igual a	`\geq` ($\geq$)
aproximado a	`\simeq` ($\simeq$)

Para inserir letras gregas, use o nome delas em inglês:

Símbolo	`Latex`
alfa	`\alpha` ($\alpha$)
beta	`\beta` ($\beta$)
gama	`\gamma` ($\gamma$)
…	$...$
ômega	`\omega` ($\omega$)

Subscritos e sobrescritos:

Símbolo	`Latex`
sobrescrito	`a^{b^{4+c}}` ($a^{b^{4+c}}$)
subscrito	`a_{b_{4+c}}` ($a_{b_{4+c}}$)
somatório	`\sum_{i=1}^{n+4}\alpha` ($\sum_{i=1}^{n+4}\alpha$) `\sum\limits_{i=1}^{n+4}\alpha` ($\sum\limits_{i=1}^{n+4}\alpha$)
produtório	`\prod_{i=1}^{n+4}\alpha` ($\prod_{i=1}^{n+4}\alpha$) `\prod\limits_{i=1}^{n+4}\alpha` ($\prod\limits_{i=1}^{n+4}\alpha$)

Frações, raízes, chaves, etc.

Símbolo	`Latex`
fração	`\frac{4}{n}` ($\frac{4}{n}$)
chaves	`\{5 - 4 - ... - n \}` ($\{5 - 4 - ... - n \}$)
raiz	`\sqrt{4}` ($\sqrt{4}$) `\sqrt[3]{x + 1}` ($\sqrt[3]{x + 1}$)

Veja também

Você pode aprender mais sobre a linguagem Latex por meio do tutorial do Overleaf (um software para escrever código em Latex e gerar documentos a partir do código). Dica: o nome Latex vem do grego e se pronuncia “látec” e não “látecs”.

Criando links¶

Um link é uma ligação entre a um local (uma página ou parte de uma página) e outro (outra página ou outra parte de uma página, por exemplo). Por este motivo, um link precisa ter uma âncora (onde clicar) e uma referência de hipertexto (o alvo onde você quer chegar). Por este motivo, um link em HTML se escreve da seguinte maneira:

<p>Ao clicar em <a href="www.google.com">Google</a>, você irá para o site do Google.</p>

Resultado: Ao clicar em Google, você irá para o site do Google.

Neste caso, a âncora ( <a> … </a>) indica qual parte do texto será clicável. A referência (href="...") indica o endereço aonde você quer chegar.

Em Markdown este processo é simplificado em que a âncora (texto clicável) é um par de colchetes [...] ligado a um par de parênteses (...) que faz a referência (endereço):

Ao clicar em [Google](http://www.google.com), você irá para o site do Google.

Resultado: Ao clicar em Google, você irá para o site do Google.

Apesar de ser mais simples fazer links em Markdown que em HTML, há situações em que pode ser importante saber como fazer links em HTML. Um exemplo é criar um link que seja aberto numa nova aba / página separada. Veja que adicionamos um marcador target="..." à âncora <a>:

<p>Ao clicar em <a href="http://www.google.com" target="_blank">Google</a>, você irá para o site do Google.</p>

Resultado: Ao clicar em Google, você irá para o site do Google.

Inserindo imagens¶

Inserir imagens é muito semelhante à lógica de inserção de links do item anterior. Você pode fazer tanto nativamente em Markdown como usando HTML.

`Markdown`	`HTML`
`![texto](localização)`	`<img src="localização"> texto </img>`

O texto, nesse caso, é opcional.

Exemplo:

![](img/logo.png)

Resultado:

O uso do HTML para imagens se justifica porque, ao contrário do Markdown, com HTML você consegue delimitar tamanho (width=), entre outros aspectos:

Exemplo:

<img src="img/logo.png" width=100></img>

Resultado:

Análise de dados e estatística com Python para não programadores

Markdown

Contents

Markdown¶

Criando títulos¶

Formatando texto¶

Formatação específica de `Markdown`¶

Formatação específica em `HTML`¶

Formatando código¶

Criando listas¶

Criando tabelas¶

Inserindo expressões matemáticas com `Latex`¶

Criando links¶

Inserindo imagens¶

Exercícios¶

Para saber mais¶

Símbolo	`Latex`
multiplicação	`\times` (\(x\))
divisão	`\div` (\(\div\))
diferente de	`\neq` (\(\neq\))
menor ou igual a	`\leq` (\(\leq\))
maior ou igual a	`\geq` (\(\geq\))
aproximado a	`\simeq` (\(\simeq\))

Símbolo	`Latex`
alfa	`\alpha` (\(\alpha\))
beta	`\beta` (\(\beta\))
gama	`\gamma` (\(\gamma\))
…	\(...\)
ômega	`\omega` (\(\omega\))

Símbolo	`Latex`
sobrescrito	`a^{b^{4+c}}` (\(a^{b^{4+c}}\))
subscrito	`a_{b_{4+c}}` (\(a_{b_{4+c}}\))
somatório	`\sum_{i=1}^{n+4}\alpha` (\(\sum_{i=1}^{n+4}\alpha\)) `\sum\limits_{i=1}^{n+4}\alpha` (\(\sum\limits_{i=1}^{n+4}\alpha\))
produtório	`\prod_{i=1}^{n+4}\alpha` (\(\prod_{i=1}^{n+4}\alpha\)) `\prod\limits_{i=1}^{n+4}\alpha` (\(\prod\limits_{i=1}^{n+4}\alpha\))

Símbolo	`Latex`
fração	`\frac{4}{n}` (\(\frac{4}{n}\))
chaves	`\{5 - 4 - ... - n \}` (\(\{5 - 4 - ... - n \}\))
raiz	`\sqrt{4}` (\(\sqrt{4}\)) `\sqrt[3]{x + 1}` (\(\sqrt[3]{x + 1}\))

Análise de dados e estatística com Python para não programadores

Markdown

Contents

Markdown¶

Criando títulos¶

Formatando texto¶

Formatação específica de Markdown¶

Formatação específica em HTML¶

Formatando código¶

Criando listas¶

Criando tabelas¶

Inserindo expressões matemáticas com Latex¶

Criando links¶

Inserindo imagens¶

Exercícios¶

Para saber mais¶

Formatação específica de `Markdown`¶

Formatação específica em `HTML`¶

Inserindo expressões matemáticas com `Latex`¶