Documentaton

breaks: false repo: https://mutabit.com/repos.fossil/documentaton/ parent: pandoc.md sync: - https://docutopia.tupale.co/documentaton:exportacion-multiformato - repo://es/capitulos/exportacion.md

Exportación de Markdown a PDF

Para exportar a distintos formatos lo que hacemos en los suguiente:

  pandoc archivo1.md archivo2.md archivoN.md --output compilado.pdf

Donde cada uno de los archivos .md son archivos de Markdown que ordenados constituiran el PDF final.

En ocasiones quisiéramos cambiar también las opciones de fuentes, paginación, títulos, tipografías, tamaño de página, etc. Usualmente expresamos todas ellas en un archivo de metadatos, llamado, por convención, metadata.yaml. Si queremos usar las opciones en ese archivo, para controlar nuestro PDF lo que hacemos es lo siguiente:

  pandoc metadata.yaml archivo1.md archivo2.md archivoN.md --output compilado.pdf

Por ejemplo, para el libro de Feminismo de Datos el archivo yaml de opciones es este.

Ejemplo: Producir una primera versión (pre-alfa) del librito/cartilla en PDF.

Corremos el comando dentro de la carpeta de español para producir la versión del libro:

 cd es/

 pandoc metadata.yaml \ 
     capitulos/presentacion.md  \
     capitulos/convenciones.md \
     capitulos/fossil.md  \
     capitulos/infraestructuras-bolsillo.md \
     capitulos/instaladores.md \
     -o documentaton.pdf

Veamos lo que hemos hecho en mayor detalle:

• Primero nos ubicamos en la carpeta del idioma donde están los textos que consitutyen nuestro libro.
• Luego empleamos Pandoc para exportarlo a distintos formatos, para ello indicamos cuál era el archivo de metadatos (metadata.yaml), que continene las opciones de personalización y luego cada uno de los capítulos en orden. En sistemas *nix el backslash (\) funciona dentro de archivos y órdenes ejecutables, indicando saltos de línas que van concatenadas y lo usamos para fácil lectura, colocando un argumento en una línea diferente.

Agregamos el archivo en PDF como archivo no versionado dentro del repositorio, es decir que no rastrearemos los cambios en el mismo.

Desde la raíz del repositorio hacemos:

  fossil uv add es/documentaton.pdf
  fossil uv sync -v

Edición y depuración del PDF

Para esto cambiaremos los archivos directamente en el repositorio, y luego crearemos algo que los sincronize de vuelta (o de modo bidireccional) con los pads originales.

Vamos a instalar un editor de Markdown para trabajar directamnte en los archivos del repositorio, por ejemplo Ghostwritter (Repositorio)

Para MacOS Ghostwritter aún no es estable, una alternativa es MacDown (Repositorio)

  brew cask install macdown