Una ventana de terminal que se ejecuta en una computadora portátil Linux con un tema de escritorio al estilo de Ubuntu.

Puede usar pandocen Linux para convertir entre más de 40 formatos de archivo. También puede usarlo para crear un sistema simple de documentos como código escribiendo en Markdown, almacenando gity publicando en cualquiera de sus formatos compatibles.

Conversión de documentos y Docs-as-Code

Si tiene un documento en cualquiera de los  pandoc's muchos formatos de archivo admitidos, convertirlo a cualquiera de los demás es muy sencillo. ¡Es una herramienta útil para tener!

Pero el poder real de se pandochace evidente cuando lo usa como la base de un sistema simple de documentos como código. La premisa de docs-as-code es adoptar algunas de las técnicas y principios del desarrollo de software y aplicarlos a la escritura de documentación, especialmente para proyectos de desarrollo de software. Sin embargo, puedes aplicarlo al desarrollo de cualquier tipo de documentación.

Los desarrolladores de software utilizan su editor favorito o su entorno de desarrollo integrado (IDE) para escribir sus programas. El código que escriben se guarda en archivos de texto. Estos contienen el código fuente del programa.

Utilizan un sistema de control de versiones, o VCS ( Git es el más popular), para capturar cambios en el código fuente a medida que se desarrolla y mejora. Esto significa que el programador tiene un historial completo de todas las versiones de los archivos de código fuente. Él o ella pueden acceder rápidamente a cualquier versión anterior de un archivo. Git almacena archivos en un repositorio. Hay un repositorio local en la computadora de cada desarrollador y un repositorio central, compartido y remoto que a menudo está alojado en la nube.

Cuando están listos para producir una versión funcional del programa, usan un compilador para leer el código fuente y generar un ejecutable binario.

Al escribir sus documentos en un lenguaje de marcado ligero basado en texto, puede usar un VCS para controlar la versión de su escritura. Cuando esté listo para distribuir o publicar un documento, puede usarlo pandoc para generar tantas versiones diferentes de su documentación como necesite, incluidas las basadas en la web ( HTML ), procesadas por texto o compuestas ( LibreOffice, Microsoft Word, TeX ), formato de documento portátil ( PDF ), libro electrónico ( ePub ), etc.

Puede hacer todo esto desde un conjunto de archivos de texto ligeros controlados por versiones.

Instalación de pandoc

Para instalar pandocen Ubuntu, use este comando:

sudo apt-get install pandoc

sudo apt-get install pandoc en una ventana de terminal.

En Fedora, el comando que necesita es el siguiente:

sudo dnf instalar pandoc

sudo dnf instala pandoc en una ventana de terminal.

En Manjaro, debe escribir:

sudo pacman -Syu pandoc

sudo pacman -Syu pandoc en una ventana de terminal.

Puede comprobar qué versión ha instalado utilizando la --versionopción:

pandoc --versión

pandoc --version en una ventana de terminal.

Usar pandoc sin archivos

Si lo usa pandocsin ninguna opción de línea de comandos, también acepta entradas escritas. Simplemente presione Ctrl + D para indicar que ha terminado de escribir. pandoc espera que escriba en formato Markdown y genera una salida HTML.

Veamos un ejemplo:

pandoc

pandoc en una ventana de terminal.

Hemos escrito algunas líneas de Markdown y estamos a punto de presionar Ctrl + D.

Líneas de muestra de rebajas escritas en pandoc en una ventana de terminal.

Tan pronto como lo hacemos,  pandocgenera la salida HTML equivalente.

HTML generado por pandoc en una ventana de terminal.

Sin pandocembargo, para hacer algo útil con , realmente necesitamos usar archivos.

Conceptos básicos de Markdown

Markdown es un lenguaje de marcado ligero y se le da un significado especial a ciertos caracteres. Puede utilizar un editor de texto sin formato para crear un archivo Markdown.

Markdown se puede leer fácilmente, ya que no hay etiquetas visualmente engorrosas que distraigan del texto. El formato en los documentos de Markdown se parece al formato que representa. A continuación se muestran algunos de los conceptos básicos:

  • Para enfatizar el texto con cursiva , envuélvalo en asteriscos.*This will be emphasized*
  • Para el   texto en negrita , use dos asteriscos. **This will be in bold**
  • Los encabezados están representados por el signo de número / marca de almohadilla ( #). El texto está separado del hash por un espacio. Use un hash para un encabezado de nivel superior, dos para un segundo nivel, y así sucesivamente.
  • Para crear una lista con viñetas, comience cada línea de la lista con un asterisco e inserte un espacio antes del texto.
  • Para crear una lista numerada, comience cada línea con un dígito seguido de un punto y luego inserte un espacio antes del texto.
  • Para crear un hipervínculo, escriba el nombre del sitio en corchetes ( []), y la dirección URL en paréntesis [ ()], así: [Link to How to Geek](https://www.howtogeek.com/).
  • Para insertar una imagen, escriba un signo de exclamación inmediatamente antes de los corchetes ( ![]). Escriba cualquier texto alternativo para la imagen entre corchetes. Luego, encierre la ruta a la imagen entre paréntesis [ ()“]. He aquí un ejemplo:  ![The Geek](HTG.png).

Cubriremos más ejemplos de todos estos en la siguiente sección.

Conversión de archivos

Las conversiones de archivos son sencillas. pandocPor lo general, puede averiguar con qué formatos de archivo está trabajando a partir de sus nombres de archivo. Aquí, vamos a generar un archivo HTML a partir de un archivo Markdown. La -oopción (salida) dice pandocel nombre del archivo que deseamos crear:

pandoc -o sample.html sample.md

pandoc -o sample.html sample.md en una ventana de terminal.

Nuestro archivo de muestra de Markdown, sample.md, contiene la sección corta de Markdown que se muestra en la imagen a continuación.

Markdown texto en el archivo sample.md en una ventana del editor gedit.

Se crea un archivo llamado sample.html. Cuando hacemos doble clic en el archivo, nuestro navegador predeterminado lo abrirá.

Representación HTML del archivo de rebajas sample.md, en una ventana del navegador.

Ahora, generemos un documento de texto con formato de documento abierto que podamos abrir en LibreOffice Writer:

pandoc -o sample.odt sample.md

pandoc -o sample.odt sample.md en una ventana de terminal.

El archivo ODT tiene el mismo contenido que el archivo HTML.

Un documento ODT renderizado a partir de markdown y abierto en LibreOffice Writer.

Un toque limpio es el texto alternativo de la imagen que también se utiliza para generar automáticamente un título para la figura.

Una leyenda de figura generada automáticamente en LibreOffice Writer.

Especificar formatos de archivo

Las opciones -f(desde) y -t(hasta) se utilizan para indicar pandocqué formatos de archivo desea convertir. Esto puede resultar útil si trabaja con un formato de archivo que comparte una extensión de archivo con otros formatos relacionados. Por ejemplo, TeX y LaTeX usan la extensión ".tex".

También estamos usando la -sopción (independiente) por  pandoc lo que generaremos todo el preámbulo de LaTeX requerido para que un documento sea un documento LaTeX completo, autónomo y bien formado. Sin la -sopción (independiente), la salida aún sería LaTeX bien formada que podría insertarse en otro documento LaTeX, no se analizaría correctamente como un documento LaTeX independiente.

Escribimos lo siguiente:

pandoc -f markdown -t latex -s -o sample.tex sample.md

pandoc -f markdown -t latex -s -o sample.tex sample.md en una ventana de terminal.

Si abre el archivo "sample.tex" en un editor de texto, verá el LaTeX generado. Si tiene un editor LaTeX, puede abrir el archivo TEX para ver una vista previa de cómo se interpretan los comandos de composición tipográfica LaTeX. Reducir la ventana para que se ajustara a la imagen de abajo hizo que la pantalla pareciera pequeña, pero, en realidad, estaba bien.

Un archivo LaTeX abierto en Texmaker, que muestra una vista previa de la página compuesta.

Usamos un editor de LaTeX llamado Texmaker. Si desea instalarlo en Ubuntu, escriba lo siguiente:

sudo apt-get install texmaker

En Fedora, el comando es:

sudo dnf instalar texmaker

En Manjaro, use:

sudo pacman -Syu texmaker

Conversión de archivos con plantillas

Probablemente esté empezando a comprender la flexibilidad que pandocproporciona. Puede escribir una vez y publicar en casi cualquier formato. Es una gran hazaña, pero los documentos se ven un poco vanilla.

Con las plantillas, puede dictar qué estilos  pandocutiliza cuando genera documentos. Por ejemplo, puede indicarle pandocque use los estilos definidos en un archivo de hojas de estilo en cascada (CSS) con la --cssopción.

Hemos creado un pequeño archivo CSS que contiene el texto a continuación. Cambia el espacio por encima y por debajo del estilo del encabezado de nivel. También cambia el color del texto a blanco y el color de fondo a un tono de azul:

h1 {
  color: #FFFFFF;
  color de fondo: # 3C33FF;
  margen superior: 0px;
  margen inferior: 1px;
}

El comando completo está a continuación; tenga en cuenta que también usamos la opción independiente ( -s):

pandoc -o sample.html -s --css sample.css sample.md

pandoc usa el estilo único de nuestro archivo CSS minimalista y lo aplica al encabezado de nivel uno.

HTML renderizado a partir de markdown con un estilo CSS aplicado al encabezado de nivel uno, en una ventana del navegador

Otra opción de ajuste que tiene disponible cuando trabaja con archivos HTML es incluir marcado HTML en su archivo Markdown. Esto se pasará al archivo HTML generado como marcado HTML estándar.

Sin embargo, esta técnica debe reservarse para cuando solo está generando salida HTML. Si está trabajando con varios formatos de archivo,  pandoc ignorará el marcado HTML para archivos que no sean HTML y se pasará a ellos como texto.

También podemos especificar qué estilos se utilizan cuando se generan archivos ODT. Abra un documento de LibreOffice Writer en blanco y ajuste el encabezado y los estilos de fuente para satisfacer sus necesidades. En nuestro ejemplo, también agregamos un encabezado y un pie de página. Guarde su documento como "odt-template.odt".

Ahora podemos usar esto como plantilla con la --reference-docopción:

pandoc -o sample.odt --reference-doc = odt-template.odt sample.md

pandoc -o sample.odt --reference-doc = odt-template.odt sample.md en una ventana de terminal.

Compare esto con el ejemplo de ODT anterior. Este documento utiliza una fuente diferente, tiene encabezados de colores e incluye encabezados y pies de página. Sin embargo, se generó exactamente a partir del mismo archivo Markdown "sample.md".

Un archivo ODT renderizado a partir de una rebaja con un documento de LibreOffice que actúa como una hoja de estilo, en una ventana de LibreOffice Writer.

Las plantillas de documentos de referencia se pueden utilizar para indicar diferentes etapas de la producción de un documento. Por ejemplo, puede tener plantillas que tengan marcas de agua "Borrador" o "Para revisión". Se utilizaría una plantilla sin marca de agua para un documento finalizado.

Generando archivos PDF

De forma predeterminada, pandoc utiliza el motor PDF LaTeX para generar archivos PDF. La forma más sencilla de asegurarse de que se satisfacen las dependencias de LaTeX adecuadas es instalar un editor de LaTeX, como Texmaker.

Sin embargo, es una instalación bastante grande: Tex y LaTeX son bastante pesados. Si el espacio de su disco duro es limitado, o si sabe que nunca usará TeX o LaTeX, es posible que prefiera generar un archivo ODT. Luego, puede abrirlo en LibreOffice Writer y guardarlo como PDF.

Documentos como código

Hay varias ventajas de usar Markdown como su lenguaje de escritura, incluidas las siguientes:

  • Trabajar con archivos de texto sin formato es rápido: se cargan más rápido que los archivos de procesador de texto de tamaño similar y también tienden a moverse más rápido por el documento. Muchos editores, incluidos  gedit, Vimy Emacs, utilizan el resaltado de sintaxis con el texto Markdown.
  • Tendrá una línea de tiempo de todas las versiones de sus documentos: si almacena su documentación en un VCS, como Git, puede ver fácilmente las diferencias entre dos versiones del mismo archivo. Sin embargo, esto solo funciona realmente cuando los archivos son de texto sin formato, ya que eso es con lo que un VCS espera trabajar.
  • Un VCS puede registrar quién hizo los cambios y cuándo: Esto es especialmente útil si colabora a menudo con otros en proyectos grandes. También proporciona un depósito central para los propios documentos. Muchos servicios de Git alojados en la nube, como GitHub, GitLab y BitBucket, tienen niveles gratuitos en sus modelos de precios.
  • Puede generar sus documentos en varios formatos: con solo un par de scripts de shell simples, puede extraer los estilos de CSS y documentos de referencia. Si almacena sus documentos en un repositorio de VCS que se integra con las plataformas de Integración y Despliegue Continuo (CI / CD), se pueden generar automáticamente cada vez que se crea el software.