Pesquisa de site

Experimente AsciiDoc em vez de Markdown


Da próxima vez que você escrever, use AsciiDoc e Asciidoctor como alternativas ao Markdown.

Sou um usuário satisfeito da linguagem de marcação Docbook baseada em XML. Para mim, é um sistema preciso, explícito e detalhado que me permite ter metadados contextuais e específicos de domínio no que escrevo. O melhor de tudo, porém, é que ele pode ser transformado (é assim que os usuários de XML o chamam quando o XML é convertido em outro formato) em praticamente qualquer formato, incluindo HTML, EPUB, FO para PDF, texto simples e muito mais. Porém, com grande poder vem muita digitação e, às vezes, o Docbook parece excedente aos requisitos. Felizmente, existe o AsciiDoc, um sistema de escrita de texto simples com a mesma sensação sem marcação do Markdown, mas que se transforma no Docbook para aproveitar sua precisão e flexibilidade.

Regras AsciiDoc

Assim como o Markdown, um dos objetivos do AsciiDoc é que você realmente não precisa aprender. Em vez disso, pretende ser intuitivo e natural. Você pode muito bem ter escrito trechos de AsciiDoc válidos sem perceber, caso tenha adicionado um pouco de estilo a um documento de texto simples para facilitar a leitura. Por exemplo, se você costuma separar parágrafos com uma linha em branco, então você escreveu o equivalente à tag HTML <p> ou Docbook <para>. Parece óbvio, mas na academia geralmente não é feito separar parágrafos com linhas em branco; portanto, mesmo essa convenção simples é tecnicamente marcação.

Aqui está a sintaxe mais comum.

Estilos de texto

Os estilos de texto incluem o básico, como negrito, itálico e fonte de código. A maior parte da notação é relativamente intuitiva, com a possível exceção do itálico.

*Negrito*

_Itálico_

*_Negrito e itálico_*

`Monoespaço ou código`

Código

O código é marcado com crases ou por declaração explícita de um bloco de código.

`Monoespaço ou código`

[source,python]
----
print('a whole code block')
----

Manchetes

Os títulos são marcados com sinais de igual à esquerda (=):

= Título 1 (<h1>)

== Título 2 (<h2>)

=== Título 3 (<h3>)

==== Título 4 (<h4>)

===== Título 5 (<h5>)

====== Título 6 (<h6>)

Ligações

Os hiperlinks favorecem primeiro o link, seguido pela palavra ou frase usada para “disfarçar” o link como texto.

Este é um http://example.com[hyperlink] que leva ao site example.com.

Não acho isso tão elegante quanto a notação de link do Markdown, mas é muito mais flexível. Por exemplo, você pode adicionar atributos em links AsciiDoc:

Este é um https://example.com[link,role=external,window=_blank] com o conjunto de atributos target="_blank".

Muito mais

AsciiDoc também possui links internos para que você possa vincular de uma seção a outra, um padrão para cabeçalhos de documentos, geração automática de tabela de conteúdo, capacidade de incluir outros documentos dentro de outro e muito mais.

Mas o melhor de tudo é que o AsciiDoc é, na verdade, padronizado. Nem todo mundo sabe disso, mas o termo “Markdown” não se refere a uma linguagem de marcação leve. Diferentes organizações e grupos personalizam e alteram regularmente o Markdown para seu próprio uso, portanto, ao usar o Markdown, você realmente deve verificar qual markdown pretende usar. Muitas das convenções que você pode ter aprendido em um site que usa Markdown não são transferidas para outro site que usa Markdown. Essencialmente, não existe um padrão para Markdown, e isso resultou em tanta confusão que o projeto Commonmark.org foi formado na tentativa de montar uma definição padronizada.

O AsciiDoc foi projetado desde o início com uma definição padrão, portanto, a ferramenta ou site que afirma analisar o AsciiDoc na verdade analisa todos os AsciiDoc válidos, porque há apenas um AsciiDoc válido.

AsciiDoc para qualquer coisa

O objetivo de escrever em uma linguagem de marcação leve como AsciiDoc é garantir previsibilidade e consistência quando o texto é analisado. Você deseja que uma pessoa escreva um script ou execute um aplicativo que outra pessoa escreveu, para poder transformar seu texto simples em qualquer formato que funcione melhor para ela. Às vezes, é HTML (aliás, o formato de saída nativo do Markdown e linguagem substituta quando há algo faltando em sua própria sintaxe). Outras vezes, é um EPUB ou um PDF para impressão, Docbook, um documento do LibreOffice ou qualquer número de formatos de saída possíveis.

Existem várias ferramentas para ajudá-lo a transformar o AsciiDoc para outro formato. Um comando popular é o Asciidoctor, que você pode instalar usando seu gerenciador de pacotes. Por exemplo, no Fedora, CentOS ou RHEL:

$ sudo dnf install asciidoctor

Em sistemas baseados em Debian:

$ sudo apt install asciidoctor

Alternativamente, você pode instalá-lo em qualquer sistema operacional com Ruby:

$ gem install asciidoctor

Aqui está um exemplo simples de documento AsciiDoc, que você pode criar usando qualquer editor de texto ou até mesmo um processador de texto (como o LibreOffice), desde que salve o arquivo como texto simples. A maioria dos aplicativos espera que um documento de texto simples use a extensão .txt e, embora seja uma convenção usar a extensão .adoc para AsciiDoc, não é necessário. Asciidoctor não requer nenhuma extensão especial.

= This is my example document

It's not written in _Markdown_, nor _reStructured Text_.
This is *AsciiDoc*.

It can be transformed into nearly any format using the tool `Asciidoctor` and other similar parsers.
Try it for yourself!

Para transformar um documento AsciiDoc em HTML, execute asciidoctor:

$ asciidoctor example.adoc

O arquivo example.adoc é transformado em HTML5 por padrão, mas você pode usar backends diferentes para obter acesso a mais formatos.

Do AsciiDoc para XML

Meu favorito é o backend Docbook, porque ele transforma meu AsciiDoc em Docbook XML, permitindo-me usar meu conjunto de ferramentas Docbook existente (Makefiles personalizados, Apache FOP, xsltproc, xmlto e assim por diante) para completar meu trabalho:

$ asciidoctor --backend docbook5 example.adoc

Isso gera o Docbook XML. Os dois últimos backends integrados são xhtml5 e manpage.

Do AsciiDoc para o EPUB

Se quiser transformar sua escrita em um e-book, você pode instalar o backend EPUB3:

$ gem install asciidoctor-epub3

Transforme seu AsciiDoc em EPUB:

$ asciidoctor-epub3 example.adoc

Do AsciiDoc para PDF

Você também pode transformar AsciiDoc diretamente em PDF:

$ gem install asciidoctor-pdf
$ asciidoctor-pdf example.adoc

(Seth Kenlon, CC BY-SA 4.0)

Quem deve usar o AsciiDoc

AsciiDoc é excelente para redatores técnicos e redatores que possuem requisitos precisos sobre como desejam que o texto seja organizado e analisado. É um formato de marcação claro e estritamente definido que elimina a confusão dos formatos Markdown concorrentes e se transforma em todos os principais formatos. O AsciiDoc é reconhecidamente mais detalhado e possivelmente menos intuitivo que o Markdown, mas ainda é apenas texto simples para que você possa criar qualquer coisa, e o Asciidoctor facilita o processamento. Da próxima vez que você escrever um documento para qualquer finalidade, considere experimentar o AsciiDoc.

Artigos relacionados: