Considerações sobre Markdown

Markdown é uma segunda natureza para muitos de nós. Olhando para trás, lembro-me de começar a digitar Markdown pouco depois de John Gruber lançar seu primeiro analisador baseado em Perl em 2004, depois de colaborar na linguagem com Aaron Swartz.

A sintaxe do Markdown destina-se a um propósito: ser usado como um formato para escrever para a web.

— John Gruber

Isso é quase 20 anos atrás - caramba! O que começou como uma sintaxe para HTML mais amigável ao escritor e ao leitor tornou-se uma queridinha de como escrever e armazenar prosa técnica para programadores e pessoas com experiência em tecnologia.

Markdown é um significante para a cultura do desenvolvedor e do text-tinkerer. Mas desde a sua introdução, o mundo do conteúdo digital também mudou. Embora o Markdown ainda seja bom para algumas coisas, não acredito que deva ser mais o conteúdo.

Há duas razões principais para isso:

1. O Markdown não foi projetado para atender às necessidades atuais de conteúdo.
2. Markdown retém a experiência editorial.

Claro, essa postura é influenciada por trabalhar para uma plataforma de conteúdo estruturado. Na Sanity.io, passamos a maior parte de nossos dias pensando em como o conteúdo como dados libera muito valor, e passamos muito tempo pensando profundamente sobre as experiências do editor e como economizar tempo das pessoas e tornar o trabalho com conteúdo digital prazeroso . Então, há skin no jogo, mas espero ser capaz de retratar isso, embora eu argumente contra o Markdown como o formato de conteúdo, ainda tenho uma profunda apreciação por seu significado, aplicação e legado.

Antes do meu trabalho atual, trabalhei como consultor de tecnologia em uma agência onde tínhamos que literalmente lutar contra CMSs que travavam o conteúdo de nossos clientes, incorporando-o em apresentações e modelos de dados complexos (sim, mesmo os de código aberto). Eu observei pessoas lutando com a sintaxe do Markdown e sendo desmotivadas em seus trabalhos como editores e criadores de conteúdo. Gastamos horas (e dinheiro do cliente) na construção de renderizadores de tags personalizados que nunca foram usados ​​porque as pessoas não têm tempo ou motivação para usar a sintaxe. Mesmo eu, quando altamente motivado, desisti de contribuir para a documentação de código aberto porque a implementação do Markdown baseada em componentes introduziu muito atrito.

Mas também vejo o outro lado da moeda. O Markdown vem com um ecossistema impressionante e, do ponto de vista de um desenvolvedor, há uma simplicidade elegante em arquivos de texto simples e uma sintaxe fácil de analisar para pessoas acostumadas a ler código. Certa vez, passei dias construindo um impressionante MultiMarkdown -> LaTeX -> real-time-PDF-preview-pipeline em Sublime Text para minha escrita acadêmica. E faz sentido que um arquivo README.md possa ser aberto e editado em um editor de código e renderizado bem no GitHub. Há pouca dúvida de que o Markdown traz conveniência para os desenvolvedores em alguns casos de uso.

É também por isso que quero construir meu conselho contra o Markdown, analisando o motivo pelo qual ele foi introduzido em primeiro lugar e analisando alguns dos principais desenvolvimentos de conteúdo na web. Para muitos de nós, suspeito que o Markdown seja algo que simplesmente consideramos uma “coisa que existe”. Mas toda tecnologia tem uma história e é produto da interação humana. Isso é importante lembrar quando você, leitor, desenvolve tecnologia para outros usarem.

Sabores e especificações

O Markdown foi projetado para tornar mais fácil para os escritores da web trabalharem com artigos em uma época em que a publicação na web exigia escrever HTML. Assim, a intenção era tornar mais simples a interface com a formatação de texto em HTML. Não foi a primeira sintaxe simplificada do planeta, mas foi a que ganhou mais força ao longo dos anos. Hoje, o uso do Markdown cresceu muito além de sua intenção de design de ser uma maneira mais simples de ler e escrever HTML, para se tornar uma abordagem de marcação de texto simples em muitos contextos diferentes. Claro, tecnologias e ideias podem evoluir além de sua intenção, mas a tensão no uso atual do Markdown pode ser atribuída a essa origem e às restrições impostas ao seu design.

Para aqueles que não estão familiarizados com a sintaxe, pegue o seguinte conteúdo HTML:

 <p>The <a href=”https://daringfireball.net/projects/markdown/syntax#philosophy”>Markdown syntax</a> is designed to be <em>easy-to-read</em> and <em>easy-to.write</em>.</p>

Com Markdown, você pode expressar a mesma formatação que:

 The [Markdown syntax](https://daringfireball.net/projects/markdown/syntax#philosophy) is designed to be _easy-to-read_ and _easy-to-write_.

É como uma lei da natureza que a adoção da tecnologia vem com a pressão para evoluir e adicionar recursos a ela. A crescente popularidade do Markdown significava que as pessoas queriam adaptá-lo para seus casos de uso. Eles queriam mais recursos como suporte para notas de rodapé e tabelas. A implementação original veio com uma postura opinativa, que na época era razoável para qual era a intenção do projeto:

Para qualquer marcação que não seja coberta pela sintaxe do Markdown, basta usar o próprio HTML. Não há necessidade de prefaciá-lo ou delimitá-lo para indicar que você está mudando de Markdown para HTML; basta usar as tags.

— John Gruber

Em outras palavras, se você quiser uma tabela, use <table></table> . Você verá que esse ainda é o caso da implementação original. Um dos sucessores espirituais do Markdown, o MDX, adotou o mesmo princípio, mas o estendeu ao JSX, uma linguagem de modelagem baseada em JS.

De Markdown para Markdown?

Pode parecer que o apelo do Markdown para muitos não era tanto sua ligação com o HTML, mas a ergonomia do texto simples e a sintaxe simples para formatação. Alguns criadores de conteúdo queriam usar o Markdown para outros casos de uso além de artigos simples na web. Implementações como o MultiMarkdown introduziram recursos para escritores acadêmicos que queriam usar arquivos de texto simples, mas precisavam de mais recursos. Em breve você teria uma gama de aplicativos de escrita que aceitavam a sintaxe Markdown, sem necessariamente transformá-la em HTML ou mesmo usar a sintaxe markdown como formato de armazenamento.

Em muitos aplicativos, você encontrará editores que oferecem um conjunto limitado de opções de formatação, e alguns deles são mais “inspirados” pela sintaxe original. Na verdade, um dos feedbacks que recebi em um rascunho deste artigo foi que agora, “Markdown” deveria estar em letras minúsculas, já que se tornou tão comum, e para torná-lo distinto da implementação original. Porque o que reconhecemos como markdown também se tornou muito diversificado.

CommonMark: uma tentativa de domar o Markdown

Como sorvete, Markdown vem em muitos sabores, alguns mais populares que outros. Quando as pessoas começaram a bifurcar a implementação original e adicionar recursos a ela, duas coisas aconteceram:

1. Tornou-se mais imprevisível o que você, como escritor, pode e não pode fazer com Markdown.
2. Os desenvolvedores de software tiveram que tomar decisões sobre qual implementação adotar para seu software. A implementação original também continha algumas inconsistências que adicionavam atrito para as pessoas que queriam usá-la programaticamente.

Isso iniciou conversas sobre a formalização do Markdown em uma especificação adequada. Algo que Gruber resistiu, e ainda resiste, curiosamente, porque ele reconheceu que as pessoas queriam usar o Markdown para diferentes propósitos e “Nenhuma sintaxe faria todos felizes”. É uma postura interessante considerando que Markdown se traduz em HTML, que é uma especificação que evolui para acomodar diferentes necessidades.

Embora a implementação original do Markdown seja coberta por uma licença “semelhante ao BSD”, também se lê “Nem o nome Markdown nem os nomes de seus contribuidores podem ser usados ​​para endossar ou promover produtos derivados deste software sem permissão prévia específica por escrito. ” Podemos presumir com segurança que a maioria dos produtos que usam “Markdown” como parte de seus materiais de marketing não obtiveram essa permissão por escrito.

A tentativa mais bem-sucedida de trazer o Markdown para uma especificação compartilhada é o que hoje é conhecido como CommonMark. Foi dirigido por Jeff Atwood (conhecido por co-fundador do Stack Overflow e Discourse) e John McFarlane (um professor de filosofia em Berkely que está por trás do Babelmark e do pandoc). Eles inicialmente o lançaram como “Standard Markdown”, mas mudaram para “CommonMark” depois de receber críticas de Gruber. Cuja postura foi consistente, a intenção do Markdown é ser uma sintaxe de autoria simples que se traduz em HTML:

@davewiner E é isso que há de errado com o CommonMark. Eles querem tornar as coisas mais fáceis para os programadores como objetivo principal. Eles perdem o ponto.

— John Gruber (@gruber) 8 de setembro de 2014

Acho que isso também marcou o ponto em que Markdown entrou no domínio público. Embora o CommonMark não seja marcado como “Markdown”, (conforme licenciamento), esta especificação é reconhecida e referida como “markdown”. Hoje, você encontrará o CommonMark como a implementação subjacente para softwares como Discourse, GitHub, GitLab, Reddit, Qt, Stack Overflow e Swift. Projetos como unified.js sintaxes traduzindo-as em Árvores de Sintaxe Abstrata, também contam com o CommonMark para seu suporte de markdown.

O CommonMark trouxe muita unificação em torno de como o markdown é implementado e, de várias maneiras, tornou mais simples para os programadores integrar o suporte ao markdown no software. Mas não trouxe a mesma unificação de como o markdown é escrito e usado. Faça o Markdown com sabor do GitHub (GFM). É baseado no CommonMark, mas o estende com mais recursos (como tabelas, listas de tarefas e tachado). O Reddit descreve seu “Reddit Flavored Markdown” como “uma variação do GFM” e apresenta recursos como sintaxe para marcar spoilers. Acho que podemos concluir com segurança que tanto o grupo por trás do CommonMark quanto o Gruber estavam certos: certamente ajuda com especificações compartilhadas, mas sim, as pessoas querem usar o Markdown para diferentes coisas específicas.

Markdown como um atalho de formatação

Gruber resistiu à formalização do Markdown em uma especificação compartilhada porque supôs que isso o tornaria menos uma ferramenta para escritores e mais uma ferramenta para programadores. Já vimos que mesmo com a ampla adoção de uma especificação, não obtemos automaticamente uma sintaxe que previsivelmente funcione da mesma forma em diferentes contextos. E especificações como CommonMark, popular como é, também têm sucesso limitado. Um exemplo óbvio é a implementação de markdown do Slack (chamada mrkdown ) que traduz *this* para forte/negrito, e não ênfase/itálico, e não suporta a sintaxe [link](https://slack.com) , mas usa <link|https://slack.com> em vez disso.

Você também descobrirá que pode usar a sintaxe do tipo Markdown para inicializar a formatação em editores de rich text em softwares como Notion, Dropbox Paper, Craft e, até certo ponto, Google Docs (por exemplo, asterisk + space em uma nova linha se transformará em um lista com marcadores). O que é suportado e o que é traduzido para o que varia. Portanto, você não pode necessariamente levar sua memória muscular com você nessas aplicações. Para algumas pessoas, isso é bom, e eles podem se adaptar. Para outros, isso é um corte de papel e os impede de usar esses recursos. O que faz a pergunta, para quem o Markdown foi projetado e quem são seus usuários hoje?

Quem são os usuários do Markdown?

Vimos que o markdown existe em uma tensão entre diferentes casos de uso, públicos e noções de quem são seus usuários. O que começou como uma linguagem de marcação especificamente para escritores da Web proficientes em HTML, tornou-se um queridinho para os tipos de desenvolvedores.

Em 2014, os escritores da web começaram a se afastar da movimentação de arquivos por meio de analisadores em Perl e FTP. Sistemas de gerenciamento de conteúdo (CMSs) como WordPress, Drupal e Moveable Type (que acredito que Gruber ainda usa) cresceram constantemente para se tornarem as ferramentas de publicação na web. Eles ofereciam recursos como editores de rich text que os escritores da web podiam usar em seus navegadores.

Esses editores de rich text ainda assumiram HTML e Markdown como a sintaxe de rich text subjacente, mas eliminaram parte da sobrecarga cognitiva adicionando botões para inserir essa sintaxe no editor. E cada vez mais, os escritores não eram e não precisavam ser versados ​​em HTML. Aposto que se você fez desenvolvimento web com CMSs na década de 2010, provavelmente teve que lidar com “lixo HTML” que vinha desses editores quando as pessoas colavam diretamente do Word.

Hoje, argumentarei que os principais usuários do Markdown são desenvolvedores e pessoas interessadas em código. Não é coincidência que o Slack tenha tornado o WYSIWYG o modo de entrada padrão, uma vez que seu software foi usado por mais pessoas fora dos departamentos técnicos. E o fato de esta ter sido uma decisão controversa, tanto que eles tiveram que trazê-la de volta como uma opção, mostra o quão profundo é o amor pela remarcação na comunidade de desenvolvedores. Não houve muita comemoração do Slack tentando torná-lo mais fácil e acessível para todos. E este é o cerne da questão.

A Ideologia do Markdown

O fato de que o markdown se tornou o estilo de escrita da língua franca, e o que a maioria dos frameworks de sites atende, também é a principal razão pela qual eu tenho sido um pouco nervoso em publicar isso. Muitas vezes é falado como um bem inerente e inegável. Markdown tornou-se uma marca registrada de ser amigável ao desenvolvedor. Pessoas inteligentes e habilidosas gastaram muitas horas coletivas em permitir remarcações em todos os tipos de contextos. Então, desafiar sua hegemonia certamente incomodará alguns. Mas espero que isso possa gerar uma discussão frutífera sobre algo que muitas vezes é dado como certo.

Minha impressão é que a simpatia do desenvolvedor que as pessoas relacionam com o Markdown tem a ver principalmente com 3 fatores:

1. A abstração confortável de um arquivo de texto simples.
2. Existe um ecossistema de ferramentas.
3. Você pode manter seu conteúdo próximo ao seu fluxo de trabalho de desenvolvimento.

Não estou dizendo que essas posições estejam erradas, mas sugiro que elas venham com trocas e algumas suposições irracionais.

O modelo mental simples de um arquivo de texto simples

Bancos de dados são coisas incríveis. Mas eles também ganharam a reputação de serem difíceis e inacessíveis para desenvolvedores de front-end. Conheço muitos grandes desenvolvedores que evitam códigos e bancos de dados de back-end, porque eles representam uma complexidade com a qual não querem gastar tempo. Mesmo com o WordPress, que faz muito para evitar que você tenha que lidar com seu banco de dados após a configuração, era uma sobrecarga de instalação e funcionamento.

Arquivos de texto simples, no entanto, são mais tangíveis e são bastante simples de raciocinar (desde que você esteja acostumado com o gerenciamento de arquivos). Especialmente em comparação com um sistema que vai quebrar seu conteúdo em várias tabelas em um banco de dados relacional com alguma estrutura proprietária. Para casos de uso limitados, como postagens de blog de rich text simples com imagens e links, o markdown fará o trabalho. Você pode copiar o arquivo e colocá-lo em uma pasta ou verificá-lo no git. O conteúdo parece seu por causa da tangibilidade dos arquivos. Mesmo que eles estejam hospedados no GitHub, que é um software como serviço com fins lucrativos de propriedade da Microsoft e, portanto, coberto por seus termos de serviço.

Na época em que você realmente tinha que criar um banco de dados local para iniciar seu desenvolvimento local e lidar com a sincronização com o controle remoto, o apelo dos arquivos de texto simples é compreensível. Mas essa era praticamente se foi com o surgimento de back-ends como serviço. Serviços e ferramentas como Fauna, Firestore, Hasura, Prisma, PlanetScale e Sanity's Content Lake, investem fortemente na experiência do desenvolvedor. Até mesmo operar bancos de dados tradicionais sobre desenvolvimento local tornou-se menos complicado em comparação com apenas 10 anos atrás.

Se você pensar sobre isso, você possui menos seu conteúdo se estiver hospedado em um banco de dados? E a experiência do desenvolvedor em lidar com bancos de dados não se tornou significativamente mais simples com o advento das ferramentas SaaS? E é justo dizer que a tecnologia proprietária de banco de dados afeta a portabilidade do seu conteúdo? Hoje você pode lançar o que é essencialmente um banco de dados Postgres sem habilidades de administrador de sistema, fazer suas tabelas e colunas, colocar seu conteúdo dentro dele e, a qualquer momento, exportá-lo como um dump .sql .

A portabilidade do conteúdo tem muito mais a ver com a forma como você estrutura esse conteúdo em primeiro lugar. Pegue o WordPress, é totalmente de código aberto, você pode hospedar seu próprio banco de dados. Ele ainda tem um formato de exportação padronizado em XML. Mas qualquer um que tenha tentado sair de uma instalação madura do WordPress sabe o quão pouco isso ajuda se você estiver tentando se afastar do WordPress.

Um vasto ecossistema… para desenvolvedores

Já tocamos no vasto ecossistema de descontos. Se você olhar para os frameworks de sites contemporâneos, a maioria deles assume markdown como um formato de conteúdo primário, alguns deles, o único formato. Por exemplo, Hugo, o gerador de site estático usado pela Smashing Magazine, ainda requer arquivos markdown para publicação paginada. O que significa que, se a Smashing Magazine quiser usar um CMS para armazenar artigos, ele precisa interagir com arquivos de remarcação ou converter todo o conteúdo em arquivos de remarcação. Se você procurar na documentação Next.js, Nuxt.js, VuePress, Gatsby.js e assim por diante, o markdown aparecerá com destaque. É também a sintaxe padrão para arquivos README no GitHub, que também a usa para formatação em notas e comentários de solicitação de pull.

Existem algumas menções honrosas de iniciativas para trazer a ergonomia do markdown para as massas. O Netlify CMS e o TinaCMS (o descendente espiritual do Forestry) fornecerão interfaces de usuário onde a sintaxe de remarcação é abstraída principalmente para os editores. Você geralmente descobrirá que os editores baseados em markdown em CMSs oferecem funcionalidade de visualização para a formatação. Alguns editores, como o Notion, permitem que você cole a sintaxe de remarcação e a traduzam para sua formatação nativa. Mas acho que é seguro dizer que a energia que foi usada para inovar para remarcação não favoreceu as pessoas que não gostam de escrever sua sintaxe. Não subiu na pilha, por assim dizer.

Fluxos de trabalho de conteúdo ou fluxos de trabalho de desenvolvedor?

Para um desenvolvedor que cria seu blog, o uso de arquivos markdown reduz parte da sobrecarga de colocá-lo em funcionamento, já que os frameworks geralmente vêm com análise interna ou geralmente o oferecem como parte do código inicial. E não há nada extra para se inscrever. Você pode usar o git para confirmar esses arquivos junto com seu código. Se você estiver confortável com git diffs, terá até controle de revisão como está acostumado com programação. Em outras palavras, como os arquivos de remarcação estão em texto simples, eles podem ser integrados ao fluxo de trabalho do desenvolvedor.

Mas, além disso, a experiência do desenvolvedor logo fica mais complexa. E você acaba comprometendo a experiência do usuário de sua equipe como criadores de conteúdo, e nossa própria experiência de desenvolvedor fica presa à remarcação para resolver problemas que estão muito além de sua intenção de design.

Sim, pode ser legal se você conseguir que sua equipe de conteúdo use o git e verifique suas alterações, mas ao mesmo tempo, esse é o melhor uso do tempo deles? Você realmente quer que seus editores se deparem com conflitos de mesclagem ou como fazer o rebase de branches? Git é difícil o suficiente para desenvolvedores que o usam todos os dias. E essa configuração realmente representa o melhor fluxo de trabalho para pessoas que trabalham principalmente com conteúdo? Não é este um caso em que a experiência do desenvolvedor superou a experiência do editor, e não é o custo, o tempo e o esforço que poderiam ser necessários para tornar algo melhor para os usuários?

Como as expectativas e necessidades dos ambientes de conteúdo e edição evoluíram, não acho que a redução seja suficiente para nós. Não vejo como parte da ergonomia do desenvolvedor acaba favorecendo os não desenvolvedores, e acho que mesmo para os desenvolvedores, o markdown está retendo nossa própria criação e necessidades de conteúdo. Porque o conteúdo na web mudou significativamente desde o início dos anos 2000.

De parágrafos a blocos

O Markdown sempre teve a opção de optar por HTML se você quisesse coisas mais complexas. Isso funcionou bem quando o autor também era o webmaster, ou pelo menos conhecia HTML. Também funcionou bem porque os sites geralmente eram principalmente HTML e CSS. A maneira como você projetou sites foi principalmente criando layouts de página inteira. Você pode transformar Markdown na marcação HTML e colocá-lo junto com seu arquivo style.css . Claro, também tínhamos CMSs e geradores de sites estáticos nos anos 2000, mas na maioria das vezes eles funcionavam da mesma forma, inserindo o conteúdo HTML dentro de templates sem qualquer passagem de “props” entre os componentes.

Mas a maioria de nós não cria mais HTML como antigamente. O conteúdo na web evoluiu de artigos com formatação de rich text simples para multimídia composta e componentes especializados, muitas vezes com interatividade do usuário (que é uma maneira elegante de dizer “chamada para ações de inscrição em boletim informativo”).

De artigos a aplicativos

No início de 2010, a Web 2.0 estava em seu apogeu e as empresas de software como serviço começaram a usar a Web para aplicativos de dados pesados. HTML, CSS e JavaScript foram cada vez mais usados ​​para conduzir UIs interativas. Bootstrap de código aberto do Twitter, sua estrutura para criar interfaces de usuário mais consistentes e resilientes. Isso impulsionou o que podemos chamar de “componentização” do web design. Mudou a forma como construímos para a web de uma forma fundamental.

Os vários frameworks CSS que surgiram nesta era (por exemplo, Bootstrap e Foundation) tendiam a usar nomes de classes padronizados e assumiram estruturas HTML específicas para tornar menos difícil criar interfaces de usuário resilientes e responsivas. Com a filosofia de web design do Atomic Design e convenções de nome de classe como Block-Element-Modifier (BEM), o padrão foi mudado de pensar primeiro no layout da página para ver as páginas como uma coleção de elementos de design repetíveis e compatíveis.

Qualquer conteúdo que você tenha dentro do markdown não é compatível com isso. A menos que você tenha entrado na toca do coelho de inserir os analisadores de remarcação e ajustado para produzir a sintaxe desejada (mais sobre isso mais tarde). Não é à toa que o Markdown foi projetado para ser simples artigos em rich text de elementos HTML nativos que você segmentaria com uma folha de estilo.

Isso ainda é um problema para as pessoas que usam o Markdown para direcionar conteúdo para seus sites.

A Web Incorporável

Mas algo também aconteceu com o nosso conteúdo. Não só poderíamos começar a encontrá-lo fora das <article> HTML semânticas, mas ele começou a conter mais… coisas. Muito do nosso conteúdo saiu de nossos LiveJournals e blogs para as mídias sociais: Facebook, Twitter, tumblr, YouTube. Para obter os snippets de conteúdo de volta em nossos artigos, precisávamos incorporá-los. A convenção HTML começou usando a tag <iframe> para canalizar o player de vídeo do YouTube ou até mesmo inserir uma caixa de tweets entre seus parágrafos de texto. Alguns sistemas começaram a abstrair isso em “códigos curtos”, na maioria das vezes colchetes contendo alguma palavra-chave para identificar qual bloco de conteúdo ela deveria representar e alguns atributos de valor-chave. Por exemplo, dev.to habilitou a sintaxe da linguagem de modelagem líquida para ser inserida em seu editor Markdown:

 {% youtube dQw4w9WgXcQ %}

Claro, isso requer que você use um analisador Markdown personalizado e tenha uma lógica especial para garantir que o HTML correto foi inserido quando a sintaxe foi transformada em HTML. E seus criadores de conteúdo terão que lembrar desses códigos (a menos que haja algum tipo de barra de ferramentas para inseri-los automaticamente). E se um colchete for excluído ou bagunçado, isso pode quebrar o site.

Mas e o MDX?

Uma tentativa de resolver a necessidade de conteúdo de bloco é o MDX, apresentado com o slogan “Markdown para a era do componente”. O MDX permite que você use a linguagem de modelagem JSX, bem como o JavaScript, entrelaçado na sintaxe de remarcação. Há muita engenharia impressionante na comunidade em torno do MDX, incluindo Unified.js , que é especializado em analisar várias sintaxes em Abstract Syntax Trees (ASTs), para que sejam mais acessíveis para serem usadas programaticamente. Observe que a padronização do markdown tornaria o trabalho para o pessoal por trás do Unified.js e seus usuários mais simples, porque há menos casos extremos para atender.

O MDX certamente traz uma melhor experiência do desenvolvedor na integração de componentes no Markdown. Mas não traz uma melhor experiência de editor, porque adiciona muita sobrecarga cognitiva à produção e edição de conteúdo:

 import {Chart} from './snowfall.js' export const year = 2018 # Last year's snowfall In {year}, the snowfall was above average. It was followed by a warm spring which caused flood conditions in many of the nearby rivers. <Chart year={year} color="#fcb32c" />

A quantidade de conhecimento assumido apenas para este exemplo simples é substancial. Você precisa saber sobre módulos ES6, variáveis ​​JavaScript, sintaxe de modelagem JSX e como usar props, códigos hexadecimais e tipos de dados, e precisa estar familiarizado com quais componentes você pode usar e como usá-los. E você precisa digitá-lo corretamente e em um ambiente que lhe dê algum tipo de feedback. Não tenho dúvidas de que haverá ferramentas de autoria mais acessíveis em cima do MDX, parece resolver algo que não precisa ser um problema em primeiro lugar.

A menos que você seja extremamente diligente em como compor e nomear seus componentes MDX, ele também vincula seu conteúdo a uma apresentação específica. Basta pegar o exemplo acima trazido da página inicial do MDX. Você encontrará um hexadecimal de cor codificado para o gráfico. Quando você redesenha seu site, essa cor pode não ser compatível com seu novo sistema de design. Claro, não há nada que impeça você de abstrair isso e usar o prop color=”primary” , mas também não há nada na ferramenta que o leve a tomar decisões sábias como essa.

Incorporar preocupações específicas de apresentação em seu conteúdo tornou-se cada vez mais uma responsabilidade e algo que atrapalhará a adaptação, iteração e movimentação rápida do seu conteúdo. Ele o bloqueia de maneiras muito mais sutis do que ter conteúdo em um banco de dados. Você corre o risco de acabar no mesmo lugar que sair de uma instalação madura do WordPress com plugins. É complicado separar estrutura e apresentação.

A demanda por conteúdo estruturado

Com sites e jornadas de usuário mais complexos, também vemos a necessidade de apresentar os mesmos conteúdos em todo o site. Se você estiver executando um site de comércio eletrônico, deseja incorporar informações do produto em vários lugares fora de uma única página do produto. Se você administra um site de marketing moderno, deseja poder compartilhar a mesma cópia em várias visualizações personalizadas.

Para fazer isso de forma eficiente e confiável, você precisará adaptar o conteúdo estruturado. Isso significa que seu conteúdo precisa ser incorporado com metadados e fragmentado de forma que seja possível analisar a intenção. Se um desenvolvedor vê apenas “página” com “conteúdo”, fica muito difícil incluir as coisas certas nos lugares certos. Se eles puderem acessar todas as “descrições de produtos” com uma API ou uma consulta, tudo ficará mais fácil.

Com o markdown, você está limitado a expressar taxonomias e conteúdo estruturado para algum tipo de organização de pastas (tornando difícil colocar o mesmo conteúdo em várias taxonomias) ou precisa aumentar a sintaxe com outra coisa.

Jekyll, um dos primeiros Static Site Generator (SSG) criado para arquivos markdown, introduziu o “Front Matter” como uma maneira de adicionar metadados a postagens usando YAML (um formato de valor-chave simples que usa espaços para criar escopo) entre três traços na parte superior do arquivo. Então, agora você terá duas sintaxes para lidar. YAML também tem a reputação de ser travesso (especialmente se você é da Noruega). No entanto, outros SSGs adotaram essa convenção, bem como CMSs baseados em git que usam markdown como formato de conteúdo.

Quando você precisa adicionar sintaxe adicional aos seus arquivos simples para obter algumas das possibilidades do conteúdo estruturado, você pode começar a se perguntar se realmente vale a pena. E para quem é o formato e quem ele exclui.

Se você pensar bem, muito do que fazemos na web não é apenas consumir conteúdo, estamos criando! Atualmente estou escrevendo este longo artigo em um processador de texto avançado no meu navegador.

Há uma expectativa crescente de que você também possa criar conteúdo de bloco em aplicativos de conteúdo modernos. As pessoas começaram a se acostumar com experiências de usuário agradáveis ​​que funcionam e parecem boas, e onde não se espera que você tenha que aprender sintaxe especializada. O Medium popularizou a noção de que você pode ter uma criação de conteúdo deliciosa e intuitiva na web. E por falar em “noção”, o popular aplicativo de notas aprofundou o conteúdo do bloco e permite que os usuários misturem o máximo de uma ampla variedade de tipos diferentes. A maioria desses blocos vai além do markdown e dos elementos nativos do HTML.

É notável que a Notion, descrevendo seu processo para tornar seu conteúdo acessível por meio de sua API altamente antecipada, faz questão de escolher seu formato de conteúdo, que:

Os documentos de um editor Markdown geralmente analisam e são renderizados de maneira diferente em outro aplicativo. A inconsistência tende a ser gerenciável para documentos simples, mas é um grande problema para a rica biblioteca de blocos e opções de formatação em linha do Notion, muitas das quais simplesmente não são suportadas em nenhuma implementação Markdown amplamente usada.

A noção foi com um formato baseado em JSON que os permite expressar como dados estruturados. O argumento deles é que torna mais fácil e previsível a interação com os desenvolvedores que desejam construir sua própria apresentação do conteúdo do bloco que sai das APIs do Notion.

Se não for Markdown, então o quê?

Suspeito que a proeminência do Markdown impediu a inovação e o progresso do conteúdo digital. Então, quando defendo que devemos parar de escolhê-lo como principal forma de armazenar conteúdo, é difícil dar uma resposta direta sobre o que deve substituí-lo. O que sabemos, no entanto, é o que devemos esperar de formatos de conteúdo modernos e ferramentas de autoria.

Vamos investir em experiências de autoria acessíveis

O uso de markdown exige que você aprenda sintaxe e, muitas vezes, várias sintaxes e tags personalizadas para ser prático com as expectativas modernas. Hoje, isso parece uma expectativa completamente desnecessária para colocar na maioria das pessoas. Eu gostaria que pudéssemos direcionar mais energia para criar experiências editoriais acessíveis e agradáveis ​​que produzam formatos de conteúdo portáteis modernos.

Embora seja notoriamente difícil criar ótimos editores de conteúdo de bloco, existem algumas opções viáveis ​​que podem ser estendidas e personalizadas para seu caso de uso (por exemplo, Slate.js, Quill.js ou Prosemirror). Por outro lado, investir nas comunidades em torno dessas ferramentas também pode ajudar no desenvolvimento delas.

Cada vez mais, as pessoas esperam que as ferramentas de autoria sejam acessíveis, em tempo real e colaborativas. Por que alguém deveria apertar um botão salvar na web em 2021? Por que não seria possível fazer uma alteração em um documento sem arriscar uma condição de corrida, porque seu colega estava com o documento aberto em uma guia? Devemos esperar que os autores tenham que lidar com conflitos de mesclagem? E não deveríamos tornar mais fácil para os criadores de conteúdo trabalharem com conteúdo estruturado com recursos visuais que façam sentido?

Para ser um pouco polêmico: as inovações da última década em estruturas JavaScript reativas e componentes de interface do usuário são perfeitas para criar ferramentas de autoria incríveis. Em vez de usá-los para transpilar Markdown para HTML e em uma árvore de sintaxe abstrata para integrá-lo em uma linguagem de modelo JavaScript que gera HTML.

O conteúdo do bloco deve seguir uma especificação

Eu não mencionei editores WYSIWYG para HTML. Porque eles são a coisa errada. Editores de conteúdo de bloco modernos devem preferencialmente interoperar com um formato especificado. Os editores mencionados têm pelo menos um modelo de documento interno sensato que pode ser transformado em algo mais portátil. If you look at the content management system landscape, you start to see various JSON-based block content formats emerge. Some of them are still tied to HTML assumptions or overly concerned with character positions. And none of them aren't really offered as a generic specification.

At Sanity.io, we decided early that the block content format should never assume HTML as neither input nor output, and that we could use algorithms to synchronize text strings. More importantly, was it that block content and rich text should be deeply typed and queryable. The result was the open specification Portable Text. Its structure not only makes it flexible enough to accommodate custom data structures as blocks and inline spans; it's also fully queryable with open-source query languages like GROQ.

Portable Text isn't design to be written or be easily readable in its raw form; it's designed to be produced by an user interface, manipulated by code, and to be serialized and rendered where ever it needs to go. For example, you can use it to express content for voice assistants.

 { "style": "normal", "_type": "block", "children": [ { "_type": "span", "marks": ["a-key", "emphasis"], "text": "some text" } ], "markDefs": [ { "_key": "a-key", "_type": "markType", "extraData": "some data" } ] }

An interesting side-effect of turning block content into structured data is exactly that: It becomes data! And data can be queried and processed. That can be highly useful and practical, and it lets you ask your content repository questions that would be otherwise harder and more errorprone in formats like Markdown.

For example, if I for some reason wanted to know what programming languages we've covered in examples on Sanity's blog, that's within reach with a short query. You can imagine how trivial it is to build specialized tools and views on top of this that can be helpful for content editors:

 distinct( *["code" in body[]._type] .body[_type == "code"] .language ) // output [ "text", "javascript", "json", "html", "markdown", "sh", "groq", "jsx", "bash", "css", "typescript", "tsx", "scss" ]

Example: Get a distinct list of all programming languages that you have code blocks of.

Portable Text is also serializable, meaning that you can recursively loop through it, and make an API that exposes its nodes in callback functions mapped to block types, marked-up spans, and so on. We have spent the last years learning a lot about how it works and how it can be improved, and plan to take it to 1.0 in the near future. The next step is to offer an editor experience outside of Sanity Studio. As we have learned from Markdown, the design intent is important.

Of course, whatever the alternative to markdown is, it doesn't need to be Portable Text, but it needs to be portable text. And it needs to share a lot of its characteristics. There have been a couple of other JSON-based block content format popping up the last few years, but a lot of them seem to bring with them a lot of “HTMLism.” The convenience is understandable, since a lot of content still ends up on the web serialized into HTML, but the convenience limits the portability and the potential for reuse.

You can disregard my short pitch for something we made at Sanity, as long as you embrace the idea of structured content and formats that let you move between systems in a fundamental manner. For example, a goal for Portable Text will be improved compatibility with Unified.js, so it's easier to travel between formats.

Embracing The Legacy Of Markdown

Markdown em todos os seus sabores, interpretações e garfos não vai embora. I suspect that plain text files will always have a place in developers' note apps, blogs, docs, and digital gardens. As a writer who has used markdown for almost two decades, I've become accustomed to “markdown shortcuts” that are available in many rich text editors and am frequently stumped from Google Docs' lack of markdownisms. But I'm not sure if the next generation of content creators and even developers will be as bought in on markdown, and nor should they have to be.

I also think that markdown captured a culture of savvy tinkerers who love text, markup, and automation. I'd love to see that creative energy expand and move into collectively figuring out how we can make better and more accessible block content editors, and building out an ecosystem around specifications that can express block content that's agnostic to HTML. Structured data formats for block content might not have the same plain text ergonomics, but they are highly “tinkerable” and open for a lot of creativity of expression and authoring.

If you are a developer, product owner, or a decision-maker, I really want you to be circumspect of how you want to store and format your content going forward. If you're going for markdown, at least consider the following trade-offs:

Markdown is not great for the developer experience in modern stacks :

• It can be a hassle to parse and validate, even with great tooling.
• Even if you adopt CommonMark, you aren't guaranteed compatibility with tooling or people's expectations.
• It's not great for structured content, YAML frontmatter only takes you so far.

Markdown is not great for editorial experience :

• Most content creators don't want to learn syntax, their time is better spent on other things.
• Most markdown systems are brittle, especially when people get syntax wrong (which they will).
• It's hard to accommodate great collaborative user experiences for block content on top of markdown.

Markdown is not great in block content age , and shouldn't be forced into it. Block content needs to:

• Be untangled from HTMLisms and presentation agnostic.
• Accommodate structured content, so it can be easily used wherever it needs to be used.
• Have stable specification(s), so it's possible to build on.
• Support real-time collaborative systems.

What's common for people like me who challenge the prevalence of markdown, and those who are really into the simple way of expressing text formating is an appreciation of how we transcribe intent into code. That's where I think we can all meet. But I do think it's time to look at the landscape and the emerging content formats that try to encompass modern needs, and ask how we can make sure that we build something that truly caters to editorial experience, and that can speak to developer experience as well.

I want to express my gratitude to Titus Wormer (@wooorm) for his insightful feedback on my first draft of this post, and for the great work he and the Unified.js team have done for the web community.