¿Qué es AsciiDoc?
Cómo AsciiDoc ayuda a los programadores y escritores técnicos a marcar textos complejos sin usar HTML. Exploramos la sintaxis básica del formato AsciiDoc.
Imagina que estás escribiendo un artículo, un libro o un curso de formación. Pero no es suficiente escribir un simple texto, también necesitas estructurarlo: resaltar encabezados y citas, dar formato a enlaces y fórmulas. Para hacer que el material sea comprensible, necesitas marcar su estructura. Para esto se utilizan los lenguajes de marcado, como AsciiDoc.
En esta guía, vamos a explorar cómo crear archivos en formato AsciiDoc, qué programas se pueden utilizar para editarlos, cómo marcar el texto y obtener el resultado en HTML.
En esta guía, vamos a explorar cómo crear archivos en formato AsciiDoc, qué programas se pueden utilizar para editarlos, cómo marcar el texto y obtener el resultado en HTML.
¿Por qué elegir AsciiDoc?
Los lenguajes de marcado ayudan a estructurar los textos y marcar sus elementos principales. Con las construcciones para cada elemento, se puede marcar un encabezado, resaltar un concepto o un fragmento de código, insertar un enlace o una imagen.
En el desarrollo web, el lenguaje de marcado es HTML. Se utiliza para marcar los datos en una página. Por ejemplo, esta página también está marcada con HTML y el navegador la interpreta según las convenciones comunes. Gracias a HTML, puedes ver los encabezados, las listas y otros elementos que hemos introducido con construcciones especiales.
Pero muchos especialistas que trabajan con HTML lo consideran incómodo. Por ejemplo, para crear una lista, se utiliza la siguiente construcción en este lenguaje de marcado:
En el desarrollo web, el lenguaje de marcado es HTML. Se utiliza para marcar los datos en una página. Por ejemplo, esta página también está marcada con HTML y el navegador la interpreta según las convenciones comunes. Gracias a HTML, puedes ver los encabezados, las listas y otros elementos que hemos introducido con construcciones especiales.
Pero muchos especialistas que trabajan con HTML lo consideran incómodo. Por ejemplo, para crear una lista, se utiliza la siguiente construcción en este lenguaje de marcado:
<ul>
<li>Primer elemento de la lista</li>
<li>Segundo elemento de la lista
<ul>
<li>Primer subelemento del segundo elemento de la lista</li>
<li>Segundo subelemento del segundo elemento de la lista</li>
</ul>
</li>
</ul>
Marcar el texto de esta manera no es muy conveniente:
- Tuvimos que introducir 48 caracteres adicionales que no tienen relación con el texto
- Había una alta probabilidad de cometer un error. Si olvidamos especificar <li>``</li> o <ul>``</ul>, el navegador mostrará la marca incorrectamente. Este tipo de error puede afectar a los bloques de texto adyacentes
- Trabajar con este tipo de marcado es difícil porque a menudo los escritores, los gestores de contenido y los editores no conocen el lenguaje HTML
Se puede resolver este problema utilizando formatos de marcado de texto de terceros, como AsciiDoc. En esta guía, vamos a examinar precisamente este formato.
Trabajar con AsciiDoc es mucho más conveniente. Para estructurar el texto, solo necesitas introducir la cantidad mínima de caracteres adicionales. Por ejemplo, la lista del ejemplo anterior se puede escribir así:
Trabajar con AsciiDoc es mucho más conveniente. Para estructurar el texto, solo necesitas introducir la cantidad mínima de caracteres adicionales. Por ejemplo, la lista del ejemplo anterior se puede escribir así:
* Primer elemento de la lista
* Segundo elemento de la lista
** Primer subelemento del segundo elemento de la lista
** Segundo subelemento del segundo elemento de la lista
Como puedes ver, aquí solo hemos añadido seis caracteres adicionales, en lugar de los 48 del HTML.
AsciiDoc no es el único lenguaje de marcado con un formato sencillo y conveniente. Los escritores también suelen utilizar Markdown, que también reemplaza bien a HTML. Pero hay casos en los que AsciiDoc funciona mejor. Vamos a hablar de ellos en detalle.
AsciiDoc no es el único lenguaje de marcado con un formato sencillo y conveniente. Los escritores también suelen utilizar Markdown, que también reemplaza bien a HTML. Pero hay casos en los que AsciiDoc funciona mejor. Vamos a hablar de ellos en detalle.
Por qué AsciiDoc es mejor que Markdown
Si estás trabajando con textos en Markdown y estás satisfecho con su funcionalidad, no tiene sentido cambiar a otro lenguaje.
Sin embargo, AsciiDoc tiene algunas ventajas que Markdown no tiene.
Macros
En AsciiDoc es más conveniente añadir elementos a la página con macros, que son pequeños fragmentos de código que ayudan a automatizar tareas rutinarias.
Por ejemplo, consideremos cómo insertar un vídeo de YouTube en Markdown y AsciiDoc.
Para insertar un vídeo de YouTube con Markdown, puedes copiar el código HTML con la etiqueta <iframe> y añadirlo a la página. El código se verá así:
Sin embargo, AsciiDoc tiene algunas ventajas que Markdown no tiene.
Macros
En AsciiDoc es más conveniente añadir elementos a la página con macros, que son pequeños fragmentos de código que ayudan a automatizar tareas rutinarias.
Por ejemplo, consideremos cómo insertar un vídeo de YouTube en Markdown y AsciiDoc.
Para insertar un vídeo de YouTube con Markdown, puedes copiar el código HTML con la etiqueta <iframe> y añadirlo a la página. El código se verá así:
Por ejemplo:
Si la URL del video de YouTube se ve así: https://www.youtube.com/watch?v=abcdef123456, entonces el código insertado se vería así:
<iframe width="560" height="315" src="https://www.youtube.com/embed/abcdef123456" frameborder="0" allowfullscreen></iframe>
Para añadir un vídeo en formato AsciiDoc, se utiliza la macro video. Con ella, se pueden añadir vídeos tanto desde tu ordenador como desde recursos externos. Así es como se vería el marcado en formato AsciiDoc:
== Nuestro vídeo más popular
Introducción a la lógica, lección 1: Conceptos básicos
video::eXI_TFW5Cdo[youtube, width=560, height=315]
Como puedes ver, aquí el código es más corto, más bonito y más comprensible. En lugar de código HTML, se utiliza una construcción con el identificador del vídeo, su origen, ancho y alto. El resto lo hace AsciiDoc automáticamente.
Hay muchas macros en AsciiDoc. Con ellas, se pueden añadir audio, vídeo, crear botones interactivos, añadir diseños predefinidos para bloques, etc. Puedes encontrarlos en la documentación oficial de AsciiDoc.
Las macros no son la única ventaja sobre Markdown. Además, se utilizan otras funciones que funcionan según un estándar común y están disponibles en AsciiDoc. Por ejemplo, se pueden marcar fórmulas matemáticas. Estas ventajas no significan que no se puedan crear los mismos bloques en Markdown. Pero en AsciiDoc se utilizan estándares oficiales para ello. Además, las nuevas funciones funcionan de forma predecible y comprensible, y su escritura está estandarizada.
A continuación, vamos a explicar cómo marcar el texto en AsciiDoc. Pero para aplicar inmediatamente los nuevos conocimientos en la práctica, necesitas prepararte.
Hay muchas macros en AsciiDoc. Con ellas, se pueden añadir audio, vídeo, crear botones interactivos, añadir diseños predefinidos para bloques, etc. Puedes encontrarlos en la documentación oficial de AsciiDoc.
Las macros no son la única ventaja sobre Markdown. Además, se utilizan otras funciones que funcionan según un estándar común y están disponibles en AsciiDoc. Por ejemplo, se pueden marcar fórmulas matemáticas. Estas ventajas no significan que no se puedan crear los mismos bloques en Markdown. Pero en AsciiDoc se utilizan estándares oficiales para ello. Además, las nuevas funciones funcionan de forma predecible y comprensible, y su escritura está estandarizada.
A continuación, vamos a explicar cómo marcar el texto en AsciiDoc. Pero para aplicar inmediatamente los nuevos conocimientos en la práctica, necesitas prepararte.
Cómo empezar a trabajar con AsciiDoc
Para empezar a trabajar con el formato AsciiDoc, crea un archivo con la extensión .adoc. Así podrás seguir los ejemplos de esta guía.
Puedes editar el archivo con el Bloc de notas o un editor de texto, como VSCode, Sublime Text o Atom. Puedes abrir el archivo en un navegador con la extensión Asciidoctor.js Live Preview instalada. Aquí tienes enlaces a la extensión en las tiendas de los navegadores específicos:
Puedes editar el archivo con el Bloc de notas o un editor de texto, como VSCode, Sublime Text o Atom. Puedes abrir el archivo en un navegador con la extensión Asciidoctor.js Live Preview instalada. Aquí tienes enlaces a la extensión en las tiendas de los navegadores específicos:
Si utilizas el editor de texto VSCode, puedes instalar la extensión AsciiDoc. Añade resaltado de sintaxis, exportación a PDF, HTML y la función Live Preview al editor:
Si solo quieres probar la marcación, sin instalar nada adicional, puedes utilizar AsciiDoc Live. Es un editor en línea en el que puedes ver inmediatamente el resultado de la conversión de la marcación a HTML. También puedes exportar el texto del formato AsciiDoc a HTML.
Los desarrolladores de AsciiDoc recomiendan no utilizar Word, Libre Office, Google Docs y otros editores pesados. Estos dificultan el trabajo con .adoc. Tendrás que formatear el texto en el editor primero y luego copiarlo en .adoc y volver a formatearlo. Es un trabajo doble que se puede evitar si empiezas a trabajar con el texto en formato .adoc desde el principio.
Ahora que estás listo para trabajar con AsciiDoc, podemos analizar su sintaxis. Te recomendamos que apliques inmediatamente los nuevos conocimientos en la práctica para ver cómo funciona.
Los desarrolladores de AsciiDoc recomiendan no utilizar Word, Libre Office, Google Docs y otros editores pesados. Estos dificultan el trabajo con .adoc. Tendrás que formatear el texto en el editor primero y luego copiarlo en .adoc y volver a formatearlo. Es un trabajo doble que se puede evitar si empiezas a trabajar con el texto en formato .adoc desde el principio.
Ahora que estás listo para trabajar con AsciiDoc, podemos analizar su sintaxis. Te recomendamos que apliques inmediatamente los nuevos conocimientos en la práctica para ver cómo funciona.
Sintaxis de AsciiDoc
AsciiDoc se parece al formato de marcado Markdown. Si has trabajado con él, muchas cosas te parecerán similares e intuitivas. Y viceversa, si conoces AsciiDoc, usar Markdown no será difícil.
Además, AsciiDoc interpreta muchas construcciones del formato Markdown. Si tienes un texto en Markdown, prueba cambiar la extensión y ver cuántos elementos siguen siendo los mismos. Puedes ver una lista de compatibilidad en la documentación.
Vamos a examinar los ejemplos básicos de marcado que serán suficientes para dar formato a un texto básico. Vamos a explicar cómo marcar:
Además, AsciiDoc interpreta muchas construcciones del formato Markdown. Si tienes un texto en Markdown, prueba cambiar la extensión y ver cuántos elementos siguen siendo los mismos. Puedes ver una lista de compatibilidad en la documentación.
Vamos a examinar los ejemplos básicos de marcado que serán suficientes para dar formato a un texto básico. Vamos a explicar cómo marcar:
- Párrafos
- Encabezados
- Resaltado
- Listas
- Código
- Enlaces
- Citas
- Imágenes
- Tablas
- Fórmulas matemáticas
Vamos a analizar el marcado de cada elemento en detalle.
Párrafos
Cada nueva línea en el texto es un nuevo párrafo. Para añadirlo, simplemente pasa a una nueva línea. Pero para separar los párrafos entre sí, debes dejar una línea en blanco entre ellos. Así se entenderá dónde termina un párrafo y comienza otro:
Párrafos
Cada nueva línea en el texto es un nuevo párrafo. Para añadirlo, simplemente pasa a una nueva línea. Pero para separar los párrafos entre sí, debes dejar una línea en blanco entre ellos. Así se entenderá dónde termina un párrafo y comienza otro:
Aquí se puede ver que el primer párrafo está en la línea "1", la línea "2" es una línea divisoria y el siguiente párrafo está en la línea "3". No se necesitan caracteres para marcar un párrafo.
Encabezados
Los encabezados se utilizan para separar bloques lógicos y ayudar al lector a orientarse en el texto. En AsciiDoc se utilizan seis niveles de encabezados:
= — encabezado de primer nivel
== — encabezado de segundo nivel
=== — encabezado de tercer nivel
==== — encabezado de cuarto nivel
===== — encabezado de quinto nivel
====== — encabezado de sexto nivel
Encabezados
Los encabezados se utilizan para separar bloques lógicos y ayudar al lector a orientarse en el texto. En AsciiDoc se utilizan seis niveles de encabezados:
= — encabezado de primer nivel
== — encabezado de segundo nivel
=== — encabezado de tercer nivel
==== — encabezado de cuarto nivel
===== — encabezado de quinto nivel
====== — encabezado de sexto nivel
A medida que se avanza del primer al último nivel, el tamaño de los encabezados disminuye. Esto ayuda a marcar bloques del mismo nivel.
Resaltado
En los textos, es útil resaltar palabras clave o ideas para que el lector se centre en la parte más importante. El texto se puede resaltar en negrita o cursiva:
Resaltado
En los textos, es útil resaltar palabras clave o ideas para que el lector se centre en la parte más importante. El texto se puede resaltar en negrita o cursiva:
¿Sabías que _AsciiDoc_ es una *herramienta increíble* para marcar texto?
Puedes resaltar en negrita utilizando dos caracteres * alrededor del texto resaltado. Y la cursiva se indica con _ también alrededor del texto que se desea resaltar.
Listas
Al igual que en HTML, en AsciiDoc hay dos tipos de listas:
Lista numerada simple
Listas
Al igual que en HTML, en AsciiDoc hay dos tipos de listas:
- Numeradas
- Con viñetas
Lista numerada simple
== Receta paso a paso
. Verter 200 gramos de leche
. Agregar 50 gramos de helado
. Verter 10 gramos de miel
. Mezclar en la batidora durante cinco minutos
Para crear una lista con viñetas, utiliza el carácter *. Por ejemplo, así se vería una lista de compras:
Lista con viñetas simple
Lista con viñetas simple
== Comprar
* Leche
* Queso
* Yogur griego
* Yogur con frambuesa
* Pan
Además, en AsciiDoc se pueden crear anidamientos complejos de elementos de una lista dentro de otros. Para ello, añade un segundo carácter de lista. También se pueden combinar listas para crear construcciones complejas de varios niveles:
Lista compleja y anidada
Lista compleja y anidada
== Comprar
* En el supermercado
.. Leche
.. Queso
.. Yogur
... Griego
... Con frambuesa
.. Pan
* En la librería
** 100 años de soledad
** La casa de los espíritus
Formato de código
A menudo, se crea un archivo de texto para describir un proyecto que contiene código. En Códica enseñamos programación, por lo que constantemente mostramos fragmentos de código.
Para que el código no se pierda en el texto, también hay que resaltarlo. Así se verá su sintaxis. Para ello, se utiliza la construcción:
A menudo, se crea un archivo de texto para describir un proyecto que contiene código. En Códica enseñamos programación, por lo que constantemente mostramos fragmentos de código.
Para que el código no se pierda en el texto, también hay que resaltarlo. Así se verá su sintaxis. Para ello, se utiliza la construcción:
[source,lang]
----
Código
----
lang es un parámetro que indica el lenguaje. Las líneas con este parámetro no se ven en el texto final. Código es la parte del código que se quiere mostrar.
Así es como se vería el resaltado de código en Ruby:
Así es como se vería el resaltado de código en Ruby:
[source,ruby]
----
require 'sinatra'
get '/hi' do
"Hello World!"
end
----
Este tipo de resaltado de código ayudará a los complementos de terceros a resaltar la sintaxis.
Enlaces
Los enlaces se utilizan para referirse a otro material o página a la que el usuario debe ir. Esto ayuda a enriquecer el material con información adicional.
Para crear un enlace, utiliza la construcción link[description], donde:
Enlaces
Los enlaces se utilizan para referirse a otro material o página a la que el usuario debe ir. Esto ayuda a enriquecer el material con información adicional.
Para crear un enlace, utiliza la construcción link[description], donde:
- link es el enlace
- description es el texto del enlace
https://https://codica.la/guias[Guías del equipo de Códica]
No debe haber un espacio entre el enlace y [] para que el texto se enlace.
Durante la escritura de textos, algunos enlaces pueden ser añadidos como texto para que no se pueda hacer clic en ellos. Por ejemplo, para indicar un enlace a una página de prueba inexistente para describir el funcionamiento del código. Si añades un enlace que no sigue el patrón link[description], se convertirá automáticamente en un enlace en el que se insertará la URL en lugar de la descripción.
Para insertar un enlace como texto, se utiliza el carácter de escape. Esto indica que no se debe procesar esta parte del texto. En AsciiDoc, se utiliza el carácter \, que se coloca delante del enlace.
Durante la escritura de textos, algunos enlaces pueden ser añadidos como texto para que no se pueda hacer clic en ellos. Por ejemplo, para indicar un enlace a una página de prueba inexistente para describir el funcionamiento del código. Si añades un enlace que no sigue el patrón link[description], se convertirá automáticamente en un enlace en el que se insertará la URL en lugar de la descripción.
Para insertar un enlace como texto, se utiliza el carácter de escape. Esto indica que no se debe procesar esta parte del texto. En AsciiDoc, se utiliza el carácter \, que se coloca delante del enlace.
\https://app.codica.la/
Este enlace se procesará como texto y no se podrá hacer clic en él.
Citas
A menudo, en los textos es necesario insertar un discurso directo, como una cita de un experto. Para ello, se utiliza el carácter > :
Citas
A menudo, en los textos es necesario insertar un discurso directo, como una cita de un experto. Para ello, se utiliza el carácter > :
> La tarea principal no es encontrar un error, sino encontrar las condiciones en las que el código sigue funcionando
Si la cita tiene varias líneas, se pueden unir con la construcción > + :
> La depuración eficiente del código +
> es uno de los indicadores clave de los buenos desarrolladores
En el texto final, la cita se resaltará con comillas y el lector entenderá que es un discurso directo de un experto.
Imágenes
Las imágenes son una herramienta que ayuda a visualizar el texto. Por ejemplo, sin ellas, esta guía sería menos comprensible.
Las imágenes se añaden con la construcción image::image.png[], donde:
Imágenes
Las imágenes son una herramienta que ayuda a visualizar el texto. Por ejemplo, sin ellas, esta guía sería menos comprensible.
Las imágenes se añaden con la construcción image::image.png[], donde:
- image.png es la ruta de la imagen. Puede ser absoluta o relativa al "punto de partida". Esto depende de dónde se encuentre el archivo.
- [] es la descripción de la imagen, que utilizan los programas de lectura de pantalla o los motores de búsqueda.
Tablas
Las tablas son una forma de agrupar información similar, lo que puede reemplazar una lista si contiene información del mismo tipo.
Supongamos que necesitas añadir información sobre un lenguaje de programación y su campo de aplicación. Vamos a dividir la información en dos categorías:
Las tablas son una forma de agrupar información similar, lo que puede reemplazar una lista si contiene información del mismo tipo.
Supongamos que necesitas añadir información sobre un lenguaje de programación y su campo de aplicación. Vamos a dividir la información en dos categorías:
- Lenguaje
- Campo de aplicación
[cols=2]
|====
|HTML
|Páginas web y aplicaciones en el navegador
|JS
|Desarrollo web pass:[<br>] Desarrollo móvil pass:[<br>] GameDev
|====
- [cols=2] es la definición del número de columnas
- Pares |==== son el inicio y el final de la tabla
- | es una celda de la tabla
Pero esta tabla sería incomprensible, ya que no hay encabezados. Si los añadimos, la sintaxis se verá así:
|====
|Lenguaje |Dónde se utiliza
|HTML
|Páginas web y aplicaciones en el navegador
|JS
|Desarrollo web pass:[<br>] Desarrollo móvil pass:[<br>] GameDev
|====
En este ejemplo, desaparece la indicación [cols=2], ya que el número de celdas se determina por el número de encabezados. Los encabezados se especifican después de abrir la tabla en una sola línea. Cada encabezado comienza con el carácter |
La cadena pass:[<br>] añade la etiqueta HTML <br> para el salto de línea dentro de la celda. También se pueden añadir las etiquetas <kbd></kbd>, que marcan las teclas del teclado:
Para abrir DevTools, utiliza la combinación de teclas pass:[<kbd>Ctrl + Shift + I<kbd>]
Fórmulas matemáticas
A menudo, los textos sobre temas científicos y técnicos incluyen notaciones matemáticas. Esta funcionalidad no está disponible en HTML ni en AsciiDoc. Pero en AsciiDoc hay notaciones para fórmulas matemáticas que son procesadas por complementos de terceros, como MathJax.
Por defecto, para mostrar fórmulas se utiliza el formato AsciiMath. Para ello, se realizan dos acciones:
A menudo, los textos sobre temas científicos y técnicos incluyen notaciones matemáticas. Esta funcionalidad no está disponible en HTML ni en AsciiDoc. Pero en AsciiDoc hay notaciones para fórmulas matemáticas que son procesadas por complementos de terceros, como MathJax.
Por defecto, para mostrar fórmulas se utiliza el formato AsciiMath. Para ello, se realizan dos acciones:
- En el documento, antes de utilizar las fórmulas, se especifica la línea :stem:. Esto indica a los complementos que procesen el documento.
- Antes de la fórmula, se especifica la construcción stem:[Fórmula]
:stem:
stem:[EEx: x!=a^2+b^2, x,a,b in Z]
stem:[a]: Apple vende smartphones — stem:[true]
stem:[b]: Apple vende manzanas — stem:[false]
stem:[a ^^ b]: Apple vende smartphones y manzanas — stem:[false]
Supongamos stem:[X=5]
Cuando se indican fórmulas matemáticas, se utilizan signos de la notación AsciiMath. Se convierten en símbolos matemáticos. Para que el intérprete reconozca correctamente las fórmulas, se deben utilizar notaciones especiales. Por ejemplo, el signo ≠ se debe indicar en la fórmula como !=.
Los signos, su visualización y escritura se pueden aprender en la página oficial de AsciiMath.
Los signos, su visualización y escritura se pueden aprender en la página oficial de AsciiMath.
Conclusión
Hemos examinado los casos básicos de marcado de texto. Puedes encontrar la documentación completa sobre cómo trabajar con AsciiDoc en los enlaces útiles. Allí aprenderás sobre todas las macros del lenguaje.
AsciiDoc hace que el material sea comprensible y lógico, ya que con él se puede estructurar el texto, resaltar los puntos importantes, visualizar ejemplos y marcar fórmulas matemáticas. AsciiDoc tiene una sintaxis sencilla y muchas macros con funciones adicionales, por lo que es una buena alternativa a HTML y Markdown.
AsciiDoc hace que el material sea comprensible y lógico, ya que con él se puede estructurar el texto, resaltar los puntos importantes, visualizar ejemplos y marcar fórmulas matemáticas. AsciiDoc tiene una sintaxis sencilla y muchas macros con funciones adicionales, por lo que es una buena alternativa a HTML y Markdown.
Enlaces útiles
- Documentación completa de AsciiDoc (inglés)
- AsciiMath (inglés)
Leer otros artículos de Guías
Lea otros artículos relevantes del mundo de la tecnología y el espíritu empresarial.