Guia do Markdown

O que é Markdown?

Markdown é uma linguagem de marcação leve que você pode usar para adicionar elementos de formatação a documentos de texto simples. Ela permite criar texto formatado usando uma sintaxe simples e fácil de ler que pode ser convertida para HTML e outros formatos.

Pense no Markdown como uma forma de escrever documentos formatados sem precisar de processadores de texto complexos. Você simplesmente adiciona caracteres especiais ao texto simples para indicar formatação como negrito, itálico, ou código.

Por que usar Markdown?

O Markdown é incrivelmente simples e fácil de aprender. Você pode dominar o básico em apenas 10 minutos. Os símbolos de formatação são intuitivos - asteriscos para ênfase, cerquilhas para cabeçalhos. Você apenas digita e adiciona símbolos simples para formatar seu texto.

O Markdown funciona em qualquer plataforma e qualquer editor de texto. Como os arquivos são texto simples, eles sempre serão legíveis, mesmo décadas depois. Os arquivos são leves e carregam rapidamente.

O Markdown tem amplo suporte entre plataformas. GitHub, Reddit, Discord e Slack usam Markdown. Aplicativos populares como Obsidian, Notion e VS Code o suportam nativamente. Isso o torna perfeito para documentação, anotações e conteúdo web.

O Markdown funciona perfeitamente com sistemas de controle de versão como Git. Você pode focar no conteúdo sem distrações de formatação. A colaboração em equipe é mais fácil porque todos podem editar arquivos sem software especial.

História de Desenvolvimento do Markdown

O Início: Markdown Básico (2004)

O Markdown foi originalmente criado por John Gruber em 2004, com contribuições significativas de Aaron Swartz. Gruber o projetou para ser uma forma simples de escrever usando um formato de texto simples fácil de ler e escrever que pudesse ser convertido para HTML estruturalmente válido. Este é o "núcleo" que John Gruber inicialmente projetou e implementou, contendo a sintaxe de formatação mais básica - o que chamamos de "sabor básico vanilla".

Sintaxe Básica (Markdown Vanilla inclui):

  • •
    Cabeçalhos: Use o símbolo # (# Cabeçalho)

  • •
    Ênfase:

  • •
    Itálico: Use * ou _ para envolver texto (*itálico* ou _itálico_)
  • •
    Negrito: Use ** ou __ para envolver texto (**negrito** ou __negrito__)

  • •
    Listas:

  • •
    Listas não ordenadas: Use *, -, ou + (- item)
  • •
    Listas ordenadas: Use números com pontos (1. item)
  • •
    Links: Use [texto do link](endereço do link)
  • •
    Imagens: Use ![descrição da imagem](endereço da imagem)

  • •
    Blocos de código: Indente com espaços (geralmente 4 espaços ou 1 Tab)

  • •
    Citações em bloco: Use o símbolo > (> Esta é uma citação)
  • •
    Linhas horizontais: Use --- ou ***

O Problema: Implementações Inconsistentes

No entanto, o Markdown Básico carecia de uma especificação estrita e formal. Isso levou a comportamentos inconsistentes entre diferentes analisadores de Markdown ao lidar com casos extremos.

Manipulação de espaço em branco: Por exemplo, em itens de lista, quantos espaços de indentação contam como sub-lista? São 2 espaços, 3 espaços, ou 4 espaços? Diferentes analisadores podem ter julgamentos diferentes.

Processamento de quebra de linha: Em certas situações, uma quebra de linha regular(\n) deve ser analisada como uma tag <br> (quebra de linha), ou deve simplesmente ser tratada como um espaço no texto? Isso também pode variar dependendo do analisador.

Uso misto de HTML: O Markdown permite HTML incorporado. No entanto, em algumas estruturas HTML complexas, como os analisadores de Markdown lidam com a sintaxe de Markdown dentro delas também apresenta áreas ambíguas.

A Solução: CommonMark (2014)

Em setembro de 2014, o CommonMark foi introduzido para resolver esses problemas de inconsistência. Liderado por John MacFarlane, fornece uma especificação rigorosa para o Markdown.

O CommonMark fornece uma especificação precisa onde cada caso extremo é claramente definido. Inclui um conjunto abrangente de testes com mais de 600 casos de teste para garantir consistência entre implementações. A especificação fornece uma implementação de referência que serve como padrão para outros analisadores seguirem. Mantém compatibilidade retroativa com a maioria dos documentos Markdown existentes, garantindo análise não ambígua onde a mesma entrada sempre produz a mesma saída em todos os analisadores compatíveis.

Variações Estendidas e Recursos Adicionais

Como os usuários tinham necessidades diferentes, várias variações estendidas de Markdown surgiram para atender requisitos específicos.

Sintaxe Adicional do GitHub Flavored Markdown (GFM):

  • •
    Tabelas: Use sintaxe de pipe para criar tabelas
  | Cabeçalho 1 | Cabeçalho 2 | Cabeçalho 3 |
  |----------|----------|----------|
  | Célula 1   | Célula 2   | Célula 3   |
  | Célula 4   | Célula 5   | Célula 6   |
  • •
    Tachado: Use ~~ para envolver texto (~~texto deletado~~)

  • •
    Listas de Tarefas: Crie caixas de seleção interativas

  - [x] Tarefa concluída
  - [ ] Tarefa incompleta
  • •
    Blocos de Código Cercados: Use três crases com especificação de linguagem
  ```javascript
  function hello() {
    console.log("Hello World!");
  }
  ```
  • •
    Vinculação Automática: URLs e endereços de email tornam-se clicáveis automaticamente

Outras Extensões Populares:

  • •
    Notas de Rodapé: Use sintaxe [^1] para escrita acadêmica
  Esta é uma frase com uma nota de rodapé[^1].
  [^1]: Este é o conteúdo da nota de rodapé.

Resultado: Esta é uma frase com uma nota de rodapé¹.

  • •
    Expressões Matemáticas: Use $E=mc^2$ para documentos científicos
  • •
    Atalhos de Emoji: Use :smile: vira 😊

  • •
    Listas de Definição: Para glossários e documentação técnica

  Termo 1
  : Definição para termo 1
  
  Termo 2
  : Definição para termo 2
  : Outra definição para termo 2

Resultado: Cria listas formatadas com termos destacados e definições indentadas

Como Funciona?

O Markdown segue um fluxo de trabalho simples de três etapas:

Etapa 1: Criar um Arquivo Markdown

Primeiro, você cria um arquivo de texto simples com extensão .md ou .markdown usando qualquer editor de texto. Você escreve seu conteúdo usando símbolos de formatação simples:

Etapa 2: Processar com Ferramentas Markdown

Seu arquivo .md é então processado por ferramentas de conversão Markdown ou processadores. Essas ferramentas leem seu arquivo Markdown e o convertem para o formato de saída desejado.

Etapa 3: Saída para Vários Formatos

O processador Markdown pode converter seu arquivo para múltiplos formatos:

Para Exibição na Web:

  • •
    Converte para HTML para sites, blogs e aplicações web

  • •
    Exibe conteúdo formatado em navegadores com estilo adequado

Para Documentos:

  • •
    Converte para PDF para documentos e relatórios imprimíveis

  • •
    Gera documentos Word (.docx) para uso em escritório
  • •
    Cria LaTeX para artigos acadêmicos e publicações

Para Publicação:

  • •
    Gera eBooks (formato EPUB)

  • •
    Cria slides de apresentação
  • •
    Produz sites de documentação

Este fluxo de trabalho significa que você escreve uma vez em Markdown, depois usa diferentes ferramentas para converter seu conteúdo para qualquer formato necessário - seja exibindo em um site, imprimindo como PDF, ou compartilhando como documento.

Recursos Adicionais

Documentação Essencial

  • •
    Documentação do Markdown do John Gruber :O guia original escrito pelo criador do Markdown. Leitura essencial para entender a filosofia e sintaxe básica.

  • •
    Wikipedia - Markdown :Visão geral abrangente da história, variações e detalhes técnicos do Markdown.

  • •
    Guia do Markdown :Um guia abrangente e amigável ao iniciante com exemplos e melhores práticas para todos os níveis de habilidade.