Usar Marked 2 para previsualizar AsciiDoc

Marked 2 es una aplicación para previsualizar ficheros en formato Markdown, pero ¿sabías que puede trabajar con casi cualquier fichero de marcas? En este artículo te enseñamos cómo trabajar con ficheros en formato AsciiDoc.

Índice de contenidos

• 1. Introducción
• 2. Entorno
• 3. Instalación de Asciidoctor
• 4. Configuración de Marked 2
• 5. Conclusiones
• 6. Sobre el autor

1. Introducción

He trabajado bastante tiempo con Markdown como sistema de documentación, pero después de probar AsciiDoc me quedo con este último por ser igual de sencillo que el primero pero encima mucho más flexible y completo.

Para saber más sobre AsciiDoc @esloho nos lo pone fácil con el tutorial Documentación con Asciidoctor: buena, bonita y barata. Muy recomendable.

En mis tiempos de Markdown me compré Marked 2, una estupenda aplicación de escritorio para hacer la pre-visualización de lo que vas escribiendo. Es sencilla y muy barata para la buena funcionalidad que proporciona. Al empezar a trabajar con AsciiDoc dejé esta aplicación de lado, pero sólo por torpeza ya que Marked 2 no sólo es capaz de trabajar con Markdown, sino prácticamente con cualquier lenguaje que podamos procesar mediante algún programa.

Así que en este tutorial vamos a ver cómo podemos usar Asciidoctor (el procesador de AsciiDoc) para mostrar los resultados en Marked 2.

Sí, sí, ya sé que Atom tiene un plugin que nos permite hacer directamente una pre-visualización del AsciiDoc que estamos escribiendo pero, qué queréis que os diga, para estas cosas me cuesta dejar mi querido Vim (cada uno puede usar su editor preferido). Además un poquito de postureo nunca viene mal, y siendo más analíticos Atom, entre otras cosas, no soporta todavía corrección ortográfica en otros idiomas que no sea el inglés y sí, Vim también tiene cursor múltiple.

2. Entorno

El tutorial está escrito usando el siguiente entorno:

• Hardware: Portátil MacBook Pro 15» (2.5 GHz Intel i7, 16GB 1600 Mhz DDR3, 500GB Flash Storage).

• AMD Radeon R9 M370X

• Sistema Operativo: Mac OS X El Capitan 10.11.5

• Asciidoctor 1.5.4

• Marked 2 v2.5.6 (922)

3. Instalación de Asciidoctor

Lo primero que tenemos que hacer es instalar Asciidoctor para poder procesar los ficheros de texto en formato AsciiDoc. En el tutorial de @esloho mencionado antes tenéis una opción, aquí os voy a mostrar otra.

Vamos a aprovechar que en OS X ya viene instalado Ruby para instalarlo directamente. Abrimos un terminal y ejecutamos:

$ sudo gem update --system 
$ sudo gem install -n /usr/local/bin asciidoctor 

4. Configuración de Marked 2

Si la aplicación Marked 2 la habéis comprado a través del App Store, la configuración que se expone aquí no os va a funcionar correctamente y os va a dar un error diciendo que no puede ejecutar el procesador externo porque no tiene permisos. Esto se debe a una serie de restricciones de seguridad que impone el OS X a las aplicaciones del App Store para que no puedan ejecutar procesos externos en nuestro ordenador. Podéis ver en el hilo en: custom-preprocessor-is-not-executable.

A mi me pasaba esto, puesto que la aplicación la compré en el App Store, y para solucionarlo lo mejor es que uséis este formulario para poneros en contacto con el creador de Marked 2, Brett, explicándole vuestro problema, para que os dé un código de licencia válido para la aplicación descargada desde la web.

Una vez tenemos instalada la aplicación descargada de la web, o si esta era nuestra situación inicial por no haber usado el App Store para la compra, podemos pasar a realizar la sencilla configuración.

Id a las preferencias, y abrid la pestaña de «Advanced». En esta pestaña debéis activar el check de «Enable Custom Processor» y poned los siguientes valores:

Path: /usr/local/bin/asciidoctor
Args: --backend html5 -o - -

Os dejo una imagen para que veáis como debe quedar:

Es importante que os aparezca el «OK» en verde. Para ello, la primera vez que pongáis el valor es probable que os pida permiso para acceder a esa ruta, aceptad el diálogo que os parece.

5. Conclusiones

Con estos sencillos pasos ya podéis abrir ficheros en formato AsciiDoc (extensión .adoc) y trabajar con ellos como si de Markdown se tratase. Os dejo una imagen de como he escrito este mismo tutorial usando Vim + AsciiDoc + Marked 2.

Y acordaos de lo que os digo siempre, explorad las opciones de vuestras herramientas de trabajo para sacarles el máximo partido. Veréis cómo en muchos casos os sorprenderéis de lo que os estáis perdiendo 😉

6. Sobre el autor

Alejandro Pérez García (@alejandropgarci)
Ingeniero en Informática (especialidad de Ingeniería del Software) y Certified ScrumMaster

Socio fundador de Autentia Real Business Solutions S.L. – «Soporte a Desarrollo»

Socio fundador de ThE Audience Megaphone System, S.L. – TEAMS – «Todo el potencial de tus grupos de influencia a tu alcance»