Markdown

O Markdown se tornou tão onipresente para os desenvolvedores que muitas vezes é dado como certo e assumido que quase qualquer pessoa que cria conteúdo está familiarizado com ele. No entanto, quando você sai dos círculos de desenvolvedores, torna-se muito menos comum que alguém já tenha ouvido falar dele, muito menos o tenha usado. O principal meio de criação de conteúdo para o não desenvolvedor comum ainda é o Word ou uma ferramenta com uma experiência de criação semelhante (por exemplo, Pages ou Google Docs).

Se você não conhece o Markdown, mas acaba escrevendo ou editando conteúdo para sites Jamstack, você pode estar se perguntando do que se trata toda essa formatação estranha. Neste post, espero oferecer alguns antecedentes sobre o que é Markdown e o papel que ele normalmente desempenha no Jamstack.

História do Markdown

O Markdown foi originalmente lançado em 2004 por John Gruber, que já era muito conhecido por seu blog focado na Apple. Ele criou a sintaxe em colaboração com Aaron Swartz, co-fundador do Reddit.

Markdown tem duas partes:

• Uma sintaxe para marcar documentos de texto simples.
• Uma ferramenta (originalmente escrita em Perl) para converter essa marcação em HTML válido.

A ideia era que o Markdown não só seria fácil de escrever, com uma sintaxe relativamente limitada e simples, mas mais importante, seria fácil de ler. Isso contrastou com a escrita em HTML puro, que tem uma marcação baseada em tag que pode ser prolixa e dificultar a legibilidade, especialmente se você não estiver familiarizado com os significados de cada tag.

Embora outras linguagens de marcação como BBCode, Textile, AsciiDoc e ReStructuredText já existissem, o Markdown se popularizou e foi adotado por sites como GitHub, Reddit e StackOverflow para formatar conteúdo. Como outras linguagens de marcação, Markdown não tinha nenhuma especificação oficial, o que levou a um dos aspectos mais duradouros e confusos do Markdown.

Os "Sabores" de Markdown

O script Markdown original em Perl que ainda está disponível no site do John Gruber para download foi atualizado pela última vez no final de 2004. O Markdown teve alguns problemas que nunca foram resolvidos pelo Markdown "oficial", isso levou a melhorias sendo feitas em cada implementação individual do Markdown. Cada uma dessas variantes do Markdown costumam ser chamadas de sabores.

A lista mais completa que encontrei identifica 36 sabores de Markdown, cada um com suas próprias variações de sintaxe. Quem possui alguma experiência em Markdown provavelmente encontrará essas diferenças. Embora sutis, essas diferenças de renderização se tornam visíveis ao copiar o Markdown de um programa para outro.

Esses problemas levaram à criação da especificação CommonMark, que visava criar um padrão claro e em evolução para a sintaxe Markdown. Embora isso tenha levado a alguns programas e implementações de Markdown a adotar o padrão, a adoção está longe de ser universal. Felizmente, na maioria dos casos, as diferenças de renderização tendem a ser pequenas.

Geradores de Sites Estáticos e Markdown

Jekyll foi um dos primeiros geradores de sites estáticos que ganhou ampla adoção, em parte porque ser uma ferramenta com suporte nas páginas do GitHub. O Jekyll mudou seu padrão de marcação Textile para Markdown em 2008 com o lançamento da versão 0.1.3. A maioria dos geradores de sites estáticos populares que vieram em seguida também suportavam Markdown por padrão.

Os desenvolvedores ficaram cada vez mais confortáveis com o Markdown por causa de sua adoção em sites que eram populares entre eles. Assim, um dos primeiros atrativos dos geradores de sites estáticos - especialmente blogs - foi a capacidade de criar conteúdo usando Markdown. Eventualmente, o Markdown tornou-se tão incorporado no ecossistema de geradores de sites estáticos que com a introdução do termo JAMstack (agora Jamstack), muitas pessoas ainda confundem o M no acrônimo JAM para Markdown.

Frontmatter

Um dos benefícios do Markdown era que ele era flexível o suficiente para atender a quase todas as tarefas relacionadas ao conteúdo, pois, na maioria dos casos, era implementado para permitir qualquer HTML arbitrário. No entanto, isso não atendeu completamente às necessidades dos geradores de sites estáticos. Postagens e páginas frequentemente precisavam de alguma forma de propriedades ou metadados que continham dados associados ao conteúdo. Isso introduziu o conceito de frontmatter.

O bloco inicial de um arquivo Markdown contém todos os metadados associados a esse arquivo, geralmente em formato de dados YAML, TOML ou JSON. Ele pode incluir coisas como os atributos de SEO de uma postagem, qual template usar para renderizar uma página ou estruturas complexas de navegação ou taxonomias. Praticamente não há limites para o que é permitido fazer com essas informações.

Aqui está um exemplo muito simples de frontmatter YAML que você pode encontrar em uma postagem do Jekyll:

---
title: O que é Markdown?
published: "2020-07-27T21:36:59.459Z"
author: Renato Ricco
layout: blog
draft: false
category: "blog"
tags:
  - dev
  - tecnologia

---

Olar Mundo.

Em alguns casos, esse assunto inicial pode conter a maior parte do conteúdo de uma página. Por exemplo, a página inicial de um site pode muitas vezes ter uma capa longa e complexa que define o conteúdo para as várias seções e subseções do design.

Markdown no Jamstack

O papel central do Markdown nos geradores de sites estáticos significa que ele continua sendo um elemento chave nos aplicativos Jamstack modernos. Isso praticamente não diminuiu, pois os aplicativos Jamstack passaram a usar também CMS do tipo Headless para gerenciar conteúdo em markdown.

Markdown nos Headless CMS

Existem dois tipos principais de Headless CMS: baseado em git e baseado em API. (Não tem certeza de quais são as diferenças? Eu as explico aqui .) Independentemente do tipo que você escolher, em algum ponto você acabará trabalhando com Markdown.

Uma vez que um CMS baseado em git adiciona uma camada de gerenciamento de conteúdo sobre seu conteúdo baseado em arquivos existentes, um componente chave de qualquer CMS baseado em git é um editor Markdown. Por exemplo, aqui está o editor Markdown integrado ao Netlify CMS:

Em vez de exigir que todos os redatores e editores de conteúdo conheçam o Markdown, o CMS baseado em git fornece um editor de estilo WYSIWYG para gerenciar o conteúdo baseado em Markdown. Isso imita a experiência dos editores de HTML WYSIWYG comuns no CMS tradicional, com a diferença, é claro, de que a fonte resultante é a sintaxe Markdown escrita.

Da mesma forma, o CMS baseado em API geralmente fornecerá um editor Markdown no estilo WYSIWYG para conteúdo de texto longo. Por exemplo, aqui está o editor Markdown dentro de Contentful:

Uma diferença importante é que a maioria dos CMS baseados em API também fornece alguma forma de conteúdo de formato longo estruturado. Por exemplo, em Contentful é denominado Rich Text ou em Sanity é denominado Block Content. Embora os editores WYSIWYG geralmente se pareçam com o editor Markdown, o código gerado é muito diferente e depende de alguma forma de especificação de rich text que no caso de um site, precisaria ser convertida para HTML.

Por que a diferença? Por que não usar Markdown para rich text? O principal aqui é que o Markdown foi projetado para ser convertido em HTML. Os Headless CMS baseados em API são projetados para criar conteúdo que pode conduzir mais do que apenas páginas da web. Isso significa que o resultado final do texto estruturado nem sempre pode ser HTML. Além disso, essas especificações de rich text geralmente têm suporte para coisas que o Markdown não oferece, como vincular objetos no CMS por exemplo.

MDX

A incapacidade do Markdown de incorporar facilmente elementos complexos da interface do usuário levou a uma maior expansão do ecossistema Markdown com a criação do MDX. Embora o Markdown possa geralmente aceitar qualquer HTML arbitrário em casos de uso que a sintaxe do Markdown não cobre, isso ainda representa um problema para sites baseados em React que requerem componentes React em vez de HTML padrão.

O padrão MDX visa resolver esse problema permitindo que o autor incorpore JSX, que são efetivamente uma representação JavaScript de HTML, no texto Markdown. Com o uso de geradores de sites estáticos baseados em React, como Next.js e Gatsby, o uso de MDX aumentou. No entanto, continua sendo uma solução centrada no desenvolvedor e dificilmente seria esperado que um autor ou editor de conteúdo não-desenvolvedor esteja familiarizado.

Para onde ir a partir daqui

Se você já conhece o Markdown, então esperançosamente esta foi uma boa olhada no ecossistema que depende dele. Se você é novo no Markdown, então esperançosamente isso ofereceu algumas boas informações sobre o que é e como usá-lo. Independentemente disso, gostaria de deixar alguns recursos e ferramentas relacionados ao uso dele.

• Mastering Markdown - uma visão geral abrangente do Markdown e do uso da sintaxe Markdown com sabor do GitHub.
• Tutorial CommonMark Markdown - uma boa referência para um tipo comum de sintaxe Markdown. Ele vai te ensinar o básico que cruza as várias implementações e tem um bom tutorial interativo para aprender a sintaxe do Markdown.
• Typora - um editor minimalista para escrever e ler Markdown (MacOS, Windows e Linux).
• Zettlr - um editor para Power Users, pode ser usado como gerenciador Zettelkasten.
• Colar como Markdown - para quando você precisar converter rapidamente rich text copiado (por exemplo, do navegador) para Markdown.
• Conversor de Word para Markdown - embora longe de ser perfeito, esta ferramenta pode ajudar na conversão de documentos do Word.