III Semana de História do campus dos Malês, IHLM/UNILAB

Uma introdução ao Markdown e suas possibilidades no ensino e divulgação científica

Prof. Eric Brasil

Markdown é uma sintaxe baseada em texto simples para formatação de documentos. Possui muitas opções interessantes para produção de materiais didáticos, apresentações entre outros.

Índice

Ementa

O que é a sintaxe Markdown. Estrutura básica: cabeçalhos, parágrafos, tabelas, imagens, gifs, links, códigos, listas, html. Editores de markdown. "Sabores" e temas. Exportando e colocando online.

Esse minicurso é inspirado e utiliza como base a lição Introdução ao Markdown, de Sarah Simpkin, publicada no ProgrammingHistorian e traduzida para o português por João Gilberto Saraiva

Vamos começar!

A Sintaxe

A sintaxe Markdown foi criada em 2004 e é um modo de formatar arquivos de textos simples, utilizando algumas marcações com símbolos como #, *, []() etc.

Esses arquivos são salvos com a extensão .md e podem ser abertos com editores de texto simples, como Gedit, Notepad, etc. Assim, podem ser abertos em diferentes sistemas operacionais.

Além disso, muitas plataformas de publicação e sites aceitam arquivos arquivos .md, muitas vezes renderizando o arquivo automaticamente para HTML.

Atualmente, existem inúmeros programas gratuitos e de código aberto para edição de Markdown, possibiltando a configuração de muitos recursos, temas (ou "flavours") e opções de exportação (seja em html, pdf, doc, etc).

Pq usar Markdown para suas aulas e apresentações?

• A pandemia e o ensino remoto;
• Como transpor a aula presencial para o virtual? Oi? 😰
• A maldição dos pdfs e ppts. 👻

• Versatilidade, adaptabilidade, leveza, compartilhável 📡

Estrutura báscia

Vamos agora entender a estrutura básica de um arquivo em .md.

Cabeçalhos

# Primeiro nível de cabeçalho
## Segundo nível de cabeçalho
### Terceiro nível de cabeçalho
#### Quarto nível de cabeçalho

Renderiza como:

Primeiro nível de cabeçalho

Segundo nível de cabeçalho

Terceiro nível de cabeçalho

Quarto nível de cabeçalho

Parágrafos e Quebras de linha

Os parágrafos devem ser separados por uma linha vazia.

Por exemplo:

​x
Vamos aprender markdown?

Para separar parágrafos precisamos inserir um linha em branco para criar um parágrafo.

Isso renderiza assim:

Vamos aprender markdown?

Para separar parágrafos precisamos inserir um linha em branco para criar um parágrafo.

Ênfases

Para colocar um texto em itálico é só colocá-lo entre * ou _ e em negrito entre ** ou __.

xxxxxxxxxx
A _III Semana de História_ do campus dos Malês será um **sucesso**.

A III Semana de História do campus dos Malês será um sucesso.

Blocos de citação

Para inserir um bloco de destaque para uma citação é só incluir > no início do parágrafo:

xxxxxxxxxx
>Eu sou uma citação bonita de um texto qualquer.

Eu sou uma citação bonita de um texto qualquer.

Tabelas

É possível inserir tabelas separando as colunas com | e hífens para demarcar a linha de títulos.

Por exemplo:

xxxxxxxxxx
| Coluna 1 | Coluna 2 | Coluna 3 |
| -------- | --------- | -------- |
| Linha 1, coluna 1 | Linha 1, coluna 2 | Linha 1, coluna 3|
| Linha 2, coluna 1 | Linha 2, coluna 2 | Linha 2, coluna 3|
| Linha 3, coluna 1 | Linha 3, coluna 2 | Linha 3, coluna 3|

Isso é renderizado como:

É possível definir o alinhamento da coluna incluíndo : na linha do cabeçalho:

xxxxxxxxxx
| Alinhado à esquerda | Centralizado | Alinhado à direita |
| :-------- | :-------: | --------: |
| Maçãs | Vermelho | 5000 |
| Bananas | Amarelo| 75 |

Linhas horizontais

Para separar seu documento e criar quebra de sessões, é possível inserir linhas horizontais utilizando --- ou ***

Imagens e gifs

Para inserir imagen basta escrever o seguinte:

xxxxxxxxxx
![título da imagem](caminho para a imagem em seu computador ou link para a imagem online)

Imagem com caminho em meu computador:

xxxxxxxxxx
![unilab](imgs/unilab.png)

Imagem com url:

xxxxxxxxxx
![logo hist](https://cclhm0057.netlify.app/favicon/logohist.png)

OBS: Se vc pretende configurar mais elementos de sua imagem, como tamanho, alinhamento, legenda, será preciso utilizar html. Veremos algumas dicas assim abaixo.

Links

Acrescentar links no documento é bem simples e segue padrão similar à inserção de imagens. Basta colocar o texto entre colchetes e o link entre parênteses na sequência []():

[Introdução ao Markdown](https://programminghistorian.org/pt/licoes/introducao-ao-markdown)

Isso renderiza assim:

Introdução ao Markdown

Códigos

É possível escrever blocos de código utilizando três acentos graves para abrir e fechar bloco:

xxxxxxxxxx
python
print('Olá, mundo!')

Ou ainda, escrever o código em linha usando um acento grave abrindo e fechando

sudo apt install pandoc

Listas

É possível incluir listas ordenadas e não ordenadas

A lista ordenada é criada inserindo - ou * no início de cada linha.

xxxxxxxxxx
 Lista não ordenada
    - ul
        - ul
    - ul
    - ul

Renderiza como:

• ul

  • ul

• ul

• ul

Listas ordenadas são criadas numerando cada linha e colocando um . após cada número:

xxxxxxxxxx
Lista ordenada

1. od
2. od
    1. od
3. od
4. od

Renderiza como:

Lista ordenada

1. od

2. od

   1. od

3. od

4. od

HTML

O Markdown possui limitações e ainda não é um formato amplamente aceito no meio acadêmico. Muitos recursos de editores de texto como Word, LibreOffice não estão disponíveis em Markdown.

Entretanto, é possível inserir mais opções utilizando um pouco de html em seu documento.

Ex 1: Tamanho de uma imagem

xxxxxxxxxx
<img src="https://media.giphy.com/media/nVTa8D8zJUc2A/source.gif" alt="seriously" style="zoom:100%;" />

Ex 2: Alinhamento da imagem

Editores de markdown

Escrever o texto direto num editor de texto simples, sem visualizar o resultado final instantaneamente, pode ser um desafio no início.

Entretanto, exixtem vários editores de markdown que facilitam muito sua vida e ainda possuem vários "sabores" [flavours] ou temas para trabalhar.

Apps

• Typora
• Mark Text
• Apostrophe

On-line

• Notion
• HackMd

Avançado

Exportando e colocando online.

• HTML e suas vantagens para aulas online

Slides, blogs e livros

• RMarkdow e variações:

  • RMarkdown, material de Beatriz Milz
  • Xaringan, material de Beatriz Milz
  • Bookdown e Blogdown

• Reveal.js

PDF e artigos científicos

• Pandoc, tutorial para criação de artigo científico usando Markdown e Pandoc de Renato Perim Colistete

Deploy

• Netlify: Exportar como HTML para uma pasta e renomear como index.html. A pasta deve conter tb os demais elementos.
• Github: criar uma conta, criar repositório com o arquivo .md e outros elmentos (imagens, gifs, etc). Publicar com GitHub Pages. Se vc publicar o site com o README.md o flavour que será renderizado é o do GitHub. Se vc pretende publicar a página com algum tema específico, vc deve exportar o seu arquivo md para html (usando o Typora, por exemplo). Esse arquivo deve ser nomeado como index.html seguindo o mesmo padrão usado no Netlify.

Contatos

1. E-mails

   • profericbrasil@unilab.edu.br
   • ericbrasiln@protonmail.com

2. Twitter: @ericbrasiln

3. Instagram: ericbrasiln

4. Site pessoal: ericbrasiln.github.io

5. Github: ericbrasiln

6. Lattes

7. Orcid

8. ResearchGate

9. Academia.edu

10. YouTube

Agradecimentos

Obrigado pela paciência e participação.

Viva o Sus!