4 min de leitura ·

Desbravando o poder do markdown

Salve, salve! Quer conhecer umas funcionalidades legais do markdown?

Este é o quarto capítulo de uma série sobre markdown, caso queira ler os capítulos anteriores

Sem mais delongas, bora pro markdown!

Lista de tarefas

Você deve conhecer as listas ordenadas e não-ordenadas, correto?

fulano
ciclano
beltrano

item
item
item

E se eu te dissesse que é possível fazer uma lista com marcações?

- [x] tarefa x
- [ ] tarefa y
- [ ] tarefa z

tarefa x
tarefa y
tarefa z

Muito útil para to-do lists de funcionalidades de um projeto.

Tabelas

Com linhas e colunas, uma tabela pode melhor a visualização e facilitar a busca de informações.

| Coluna 1 | Coluna 2 | Coluna 3 |
|----------|----------|----------|
| Item 1   | Item 1   | Item 1   |

Resultado:

Coluna 1	Coluna 2	Coluna 3
Item 1	Item 1	Item 1

Você pode escolher como os textos ficam alinhados e usar os estilos de texto dentro da tabela também.

Coloque : no início do divisor e as células vão ficar alinhadas à esquerda. No final, alinhadas à direita. E se você colocar : no início e no fim do divisor o texto vai ficar centralizado.

Um exemplo:

| Nome completo  |         Idade |
|:--------------:|--------------:|
|  João `Silva`  | <kbd>27</kbd> |
| Ana *Carvalho* |            20 |
| Beatriz Souza  |        **35** |

Nome completo	Idade
João `Silva`	`27`
Ana Carvalho	20
Beatriz Souza	35

A tag kbd serve pra mostrar entradas do teclado, veja mais na documentação da mdn sobre kbd.

Sobre tabelas é isso, bem simples, não?

A formatação das tabelas no markdown pode dificultar bastante a leitura, então tente sempre manter as tabelas bem formatadas.

Uma dica pra quem usa o Visual Studio Code: instale a extensão Markdown Table Prettifier.

Vídeos

Colocar uma demonstração visual de um conceito ou projeto pode ser poderoso, mas nem todos os processadores de markdown tem uma sintaxe pronta pra isso.

A forma mais simples e totalmente compatível é usando HTML puro.

<div align="center">
  <video width="320" height="240" controls>
    <source src="video.mp4" type="video/mp4" />
  </video>
  <p>esta é a legenda do vídeo (caption)</p>
</div>

sim, não tem um vídeo -_-

A div para centralizar e o parágrafo (p) não são necessários, você pode remover caso queira. Recomendo que dê uma olhada na documentação da tag video.

Não testei mas quero compartilhar que de acordo com uma postagem no blog do GitHub é possível apenas colocar um link que termine com a extensão mp4 ou mov e o GitHub cuida da renderização para você.

Outra forma de expor uma demonstração é usando um gif, que foi o que eu fiz no projeto Ruke (porque eu não conhecia a tag video). Você converte o vídeo para o formato gif usando uma plataforma ou ferramenta e usa a sintaxe de imagem.

![texto alternativo](demonstracao.gif)

Tenha em mente que gifs têm a qualidade reduzida e ausência de áudio.

Notas de rodapé (footnotes)

Sabe aquelas referências da Wikipédia[^1], então...

Nunca utilizei mas pode fazer sentido no seu documento ou em documentos grandes.

Aqui está meu texto falando e do nada pneumoultramicroscopicossilicovulcanoconiótico[^pneu].

[^pneu]: doença pulmonar causada ao inalar partículas finas de sílica provenientes de atividades vulcânicas.

Identificação de títulos (heading IDs)

Mesmo invisível é muito útil. Serve para você mudar a âncora daquele título/subtítulo e isso é útil quando você tem um título grande ou com emojis.

Qual link você prefere:

github.com/kauefraga/anubis#um-titulo-realmente-muito-grande-lorem-ipsum-blablabla
github.com/kauefraga/anubis#titulo-lorem

Imagino que a segunda opção, afinal, o título vai estar escrito no texto e não precisa necessariamente estar na url.

# Um título realmente muito grande lorem ipsum blablabla {#titulo-lorem}

### Um subtítulo não muito grande mas grande {#subtitulo}

O resultado do texto é o mesmo mas a âncora não, estará encurtada.

Superscript e subscript

Aquele texto em cima ou embaixo, tipo em expoentes ou quantidade de moléculas.

Também vai depender do seu processador markdown, mas a solução em HTML é a seguinte:

x<sup>2</sup> e H<sub>2</sub>O

Este texto <sup>é muito</sup> <sub>legal</sub>

x² e H₂O

Este texto ^{é muito} _legal

Diagramas mermaid

Em plataformas que usem Mermaid é possível usar markdown para fazer diagramas (e vários tipos deles). O GitHub e o GitLab, por exemplo, suportam esses diagramas.

Existem diversos tipos de diagramas e está tudo bem documentado. Infelizmente, o dev.to não suporta os diagramas mermaid então vou ficar devendo o código mas fique com essas duas imagens.

diagrama de sequência

Diagrama de classe

É isso! Te agradeço por acompanhar até aqui, espero que tenha gostado e aprendido algo novo ao longo do caminho.

Com este capítulo, eu finalizo essa série de markdown. É claro que na medida necessária irei atualizando esses 4 textos.

clacerda

4 meses atrás

Ótimo post, Kauê! Obrigado por compartilhar sobre o Markdown — é sempre útil explorar e relembrar a beleza e simplicidade dessa linguagem.

Markdown is designed to be easy to write, and, even more importantly, easy to read

O grande diferencial do Markdown é como ele é fácil de ler em texto puro, combinado com os geradores de sites estáticos, transformou a forma como a documentação de software é escrita. Editar e versionar texto puro é algo que os desenvolvedores já estão acostumados, e eles podem se beneficiar das ferramentas que já usam e adoram, como seu editor de texto favorito, git, etc. Isso levou ao surgimento da filosofia Docs as Code.

No Google, após várias pesquisas internas indicarem que a documentação (ou a falta dela) era um dos maiores problemas enfrentados pelos desenvolvedores de software, a solução encontrada foi justamente essa abordagem:

g3doc

No entanto, o principal problema do Markdown é a falta de padronização e ferramental adequadado para elaboração de documentos complexos. Por exemplo, não existe uma diretiva de inclusão (padrão) para compor documentos a partir de várias fontes. Na prática, o que temos é uma família de linguagens, cada uma com suas próprias variações e capacidades.

Existem algumas (boas) alternativas ao Markdown, como o reStructuredText (reST), muito popular na comunidade Python, combinado com o Sphinx, próprio Python é documentado dessa forma, assim como o kernel do Linux. Já o AsciiDoc tem visto grande adoção no mundo corporativo, sendo utilizado por várias empresas.

Quando se trata de ferramentas para Markdown, o grande destaque é o Pandoc, uma biblioteca escrita em Haskell, não por acaso, acontece que a semântica computacional e typed lambda calculus se complementam de forma ideal e formam uma dupla poderosa!

$pandocmeme$

marlon

4 meses atrás

Não sabia do <kbd>, fica bem bonitinho.

bonitinho

Acho que escreveu originalmente para o dev.to, mas o TabNews suporta renderizar diagramas Mermaid

graph TD
    Uau
    Diagramas
    subgraph Teste
        TabNews --> Post
        Comentário --> Post
    end

guaracy

4 meses atrás

Eu incluiria nas boas alternativas ao Markdown o org-mode.

Usando junto com o editor (Emacs), acho que é a linguagem de marcação mais versátil que tem. Repositórios como Git[hub/lab], Codeberg, etc., aceitam arquivos com a extensão org tipo README.org . Pelo menos uma parte da linguagem.

clacerda

4 meses atrás

Aí sim, mandou a braba! Eu nem falei do Org-mode porque já é para os muito iniciados... Literalmente, é viver a vida em texto plano, ou como muitos gostam de chamá-lo, god mode. Aqueles que dominaram, juram de pé junto que é a ferramenta definitiva de produtividade, não existe nada igual.

O Org-mode, quando usado com o Emacs, ganha superpoderes com o Lisp, a linguagem por trás do Emacs, que oferece uma sintaxe poderosa e extensível, similar ao que Haskell faz com o Pandoc. A gramática do Lisp, assim como a do Haskell, permite que você faça coisas incrivelmente complexas de forma relativamente simples, pois as noções de gramáticas e definições formais de linguagens podem ser facilmente mapeadas nessas linguagens de programação.

Mas, sem o Emacs, o Org-mode perde quase todo o seu brilho. Uma linguagem (seja de programação ou de marcação) não é apenas sua especificação, mas também o ferramental que a acompanha. E é exatamente aí que o Org-mode é o rei indiscutível, mas apenas para aqueles que dedicaram a vida ao Emacs.