Participe da Maratona Behind the Code! A competição de programação que mais te desafia! Inscreva-se aqui

Avance do Markdown ao HTML5 com o marked-it

O Markdown está rapidamente se tornando uma das linguagens preferenciais de marcação para a criação de conteúdo técnico. A criação simples e o uso disseminado do Markdown na comunidade de desenvolvedores, bem como o suporte à colaboração entre os autores e SMEs o torna atrativo para os criadores de conteúdo.

À medida que a popularidade dele aumenta, o mesmo acontece com a demanda para proporcionar criações aprimoradas. No entanto, há uma linha sutil entre ampliar o Markdown para recursos aprimorados de criação e destruir a natureza simples do Markdown de que os autores e colaboradores gostam tanto.

Também sabemos que a maioria dos aplicativos modernos de documentos precisam de resultados em HTML5 para atender aos requisitos de design e criar a melhor experiência do usuário. Com o marked-it, a IBM desenvolveu um gerador para analisar o Markdown em HTML5 e processar as extensões criadas pela equipe para oferecer alguns dos recursos avançados de criação, mas sem complicar demais a marcação do Markdown.

Tentando preservar a simplicidade do Markdown, as extensões são uma forma de se conectar aos pontos bem definidos no processo de geração em HTML. Assim, é possível definir formas de adicionar classes aos elementos, uma nova marcação do Markdown ou, até mesmo, organizar um grupo de tópicos. Neste artigo, apresento a você alguns dos principais elementos do marked-it que o tornam uma ferramenta útil para exibir conteúdo gerado em HTML5 a partir do Markdown em um website.

Classes

A principal extensão do marked-it está relacionada à capacidade de usar atributos de metadados no Markdown. Um atributo é um mapeamento de nome ou nome-valor que pode ser vinculado a um elemento do Markdown. Em seguida, os atributos são transmitidos aos elementos HTML5 gerados resultados e exibidos como classes. Muitas vezes, eles são usados para garantir o estilo CSS correto do resultado HTML5 gerado. Depois que os atributos são definidos, é possível aplicar esses valores a qualquer elemento do Markdown, como cabeçalhos, parágrafos e blocos de código.

Talvez você precise definir direitos autorais e outros metadados para prefixá-los ou anexá-los de modo uniforme no resultado HTML5 gerado. Nessa extensão, é possível usar os arquivos padrão de cabeçalho e rodapé que são acionados durante a transformação. Talvez também seja necessário adicionar tags HTML de abertura e fechamento para o arquivo com base em seus requisitos de publicação.

Para atender aos requisitos de acessibilidade, também há uma extensão para adicionar cabeçalhos de linha das tabelas, resumos das tabelas e títulos de figuras.

Marcação do Markdown

Embora o Markdown possa conter HTML, idealmente, os autores podem usá-lo na íntegra. Para os casos em que a marcação básica do Markdown não for suficiente, a equipe da IBM Cloud definiu uma nova marcação reconhecida pelo marked-it.

Quando definimos uma nova marcação, em geral, procuramos exemplos do setor em que outras equipes ampliaram com sucesso o Markdown básico e replicamos esse processo. As conrefs são um bom exemplo de áreas em que conseguimos detectar uma implementação existente do Markdown que se baseava na implementação popular em marcação DITA e aplicá-la ao marked-it.

Outro exemplo de uma nova marcação no marked-it são os vídeos. Embora os escritores possam incluir o código iframe do arquivo do Markdown, não seria muito mais fácil apenas identificar algo como um vídeo e deixar o gerador fazer todo o trabalho? Isso também garante que todas as marcações de vídeos sejam consistentes. Essa extensão de vídeo permite que os autores codifiquem um vídeo usando a marcação do Markdown da imagem. Em seguida, eles o definem como um vídeo.

Por exemplo, ![Título do vídeo](https://www.youtube.com/embed/<video-ID>){: video output="iframe"}

Organização de tópicos

Além do resultado HTML5 padrão que o marked-it produz a partir de cada arquivo do Markdown, o gerador também pode produzir um arquivo de sumário em diferentes formatos. Cada entrada do sumário produzida para um tópico do Markdown contém um conjunto aninhado de cabeçalhos estruturados, ou topicrefs, que corresponde à estrutura dos cabeçalhos da origem inicial do Markdown. Cada cabeçalho do sumário, ou topicref, também contém um link para um ID principal de cabeçalho correspondente no arquivo de resultado HTML5 que foi gerado a partir da origem do Markdown.

Isso significa que só é necessário definir os arquivos do Markdown na ordem em que deseja que eles sejam exibidos na navegação, e que o marked-it criará um arquivo totalmente estruturado de sumário que tem entradas para o arquivo principal do Markdown e todos os títulos que ele contém.

Quem usa o marked-it?

Alguns exemplos do conteúdo oferecido no Markdown da IBM são os documentos da IBM Cloud e o IBM Developer. Nessas duas implementações, o marked-it faz parte de um processo automatizado de pipeline de desenvolvimento em que os criadores de conteúdo podem criar e confirmar alterações, e um desenvolvimento é acionado automaticamente para produzir o resultado HTML5 que é consumido no respectivo aplicativo.

Quer saber mais sobre o marked-it? Consulte nossa especificação. O gerador marked-it é uma ferramenta de open-source e sempre buscamos contribuições!