Documentación para un proyecto con Markdown y Pandoc

Hablé el otro día de una plantilla para documentación que había ayudado a crear a mi hermano para su nuevo proyecto. Como me parece que hicimos un buen curro voy a hablar un poco más de ella, de las características que tiene y de cómo se usa.

La idea

La idea principal es separar el contenido del formato, de tal manera que se pueda escribir en un lenguaje de marcado ligero como es Markdown desentendiéndose por completo del aspecto, que se gestiona en una plantilla para Pandoc. Como la salida es un pdf, la plantilla está escrita en LaTeX, el paso intermedio mediante el cual Pandoc pasa de Markdown a pdf.

Otro tema es el de los metadatos, es decir, el autor, la licencia y otras opciones de control. Este tipo de datos los introducimos en un archivo aparte o en un bloque YAML al inicio del contenido. Así, también se desacoplan tanto del contenido como del formato.

Por último, Ekaitz quería poder crear un documento corto (al que llamaré artículo de ahora en adelante) o uno largo (libro) con la misma plantilla, cosa que hemos conseguido con unos $if$ estratégicamente colocados.

Características

La plantilla para Pandoc que controla el formato se llama, con gran originalidad, template.latex y deriva de la plantilla general1. Estas son sus características:

  • Usa xelatex, tenemos ordenatas potentes y así nos ahorramos movidas con la codificación y las fuentes. Necesita por lo tanto polyglossia para el idioma y fontspec para establecer las fuentes.

  • Letra sans serif, concretamente DejaVu que es libre, moderna y se lee bien.

  • Capítulos tuneados, para el caso del libro los capítulos son más parecidos a secciones que a los típicos capítulos de LaTeX. Lo conseguimos gracias al paquete titlesec. Por cierto, cuidado con la versión que a veces la organiza y asesina los números de sección.

% Definitions related to chapters only if book is used
$if(book)$
% REMAKE CHAPTER FOR FANCYHEADER
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\makeatletter
    \let\stdchapter\chapter
    \renewcommand*\chapter{%
    \@ifstar{\starchapter}{\@dblarg\nostarchapter}}
    \newcommand*\starchapter[1]{
        \stdchapter*{#1}
        \thispagestyle{chapter} % This is the point
        \markboth{\MakeUppercase{#1}}{}
    }
    \def\nostarchapter[#1]#2{
        \stdchapter[{#1}]{#2}
        \thispagestyle{chapter}
    }
\makeatother
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Chapter formating
\usepackage{titlesec}
\newcommand{\hsp}{\hspace{20pt}}
\titleformat{\chapter}[hang]{\Huge}{\thechapter\hsp}{0pt}{\Huge}
\titlespacing*{\chapter}{0pt}{0pt}{40pt}
$endif$
  • Logo en la portada y en la primera página de los capítulos para el libro, y en el encabezado para el artículo. Este último gracias al paquete fancyhdr que permite personalizar los encabezados y pies de páginas. Os pongo el caso del artículo donde se ven las variables que corresponden a los metadatos:
% Article titlepage, similar to book chapter
\fancypagestyle{articletitle}{%
  \fancyhead{} % clear header
  \fancyhead[L]{\includegraphics[height=23pt]{img/logo.png}}
  \fancyhead[R]{\LARGE{$title$}}
  \fancyfoot[R]{$author$}
  \fancyfoot[L]{\textcopyleft $license$}
}
  • Símbolo de copyleft obtenido girando el de copyright con:
\newcommand{\copyleft}{\reflectbox{\copyright}}
  • Citas en gris con una barra vertical a la izquierda gracias al paquete framed más un poco de tuneado del entorno quote. En el proceso aprendimos a renovar un entorno y a usar \let para guardar el entorno viejo 😀
% Beautiful quotes
%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{framed}

% Use custom leftbar
\renewenvironment{leftbar}[1][\hsize]
  { \color{gray}
      \def\FrameCommand
      {{\color{lightgray}\vrule width 3pt}}
      \MakeFramed{\hsize#1\advance\hsize-\width\FrameRestore}%
  }
  {\endMakeFramed}

% Put leftbar on quote
\let\oldquote=\quote
\let\oldendquote=\endquote
\renewenvironment{quote}
    {\vspace{10pt}\leftbar\vspace*{-6pt}\oldquote}
    {\oldendquote\endleftbar\vspace{10pt}}

Uso

Como ya hemos visto otras veces que hemos usado Pandoc necesitamos varias cosas:

  • Markdowns de entrada donde escribiremos el contenido
  • La plantilla que acabamos de analizar en el apartado anterior.
  • Metadatos en un bloque YAML, en un archivo yaml o con la opción --metadata.
  • Opciones de Pandoc, en nuestro caso le indicamos que compile con xelatex y que nos numere las secciones.

Esto nos lleva a lo siguiente (para la versión libro, por poner un ejemplo):

pandoc -N --latex-engine=xelatex --template=template.latex input.md metadata.yaml -o book.pdf --metadata=book:true

Esa orden gigante está recogida en el Makefile que, como podéis ver lo ha hecho alguien que sabe programar, osea, yo no. Así se puede crear el libro solo con make book y el artículo con make article a su vez.

Para ello hay que seguir los siguientes pasos, adaptados del Readme:

  1. Meter el contenido en la carpeta src. Ordenará los diferentes archivos md por orden alfabético así que lo más lógico si hay más de uno es numerarlos.
  2. Añadir un bloque de metadatos en el contenido tomando como referencia article.yaml y book.yaml. O modificar estos propios archivos según convenga.
  3. Elegir entre un documento corto (article) o uno largo (book).
  4. Ejecutar make book o make article para crear el pdf correspondiente

Pues más o menos este es el resumen de lo que está hecho, solo queda que cada cual lo pruebe y vea si le convence. Tiene licencia Apache así que a usarlo sin miedo.


Aquí el hermano me lía pero también me manda músicas molonas así que se autocompensa 😀


  1. Para extraer la plantilla general recordemos que se hace pandoc -D latex > template.latex 
Anuncios

4 pensamientos en “Documentación para un proyecto con Markdown y Pandoc

  1. nasciiboy

    tal ves te interese echar un vistaso a esto https://github.com/nasciiboy/morg/, el formato aun esta muy verde, pero puede exportarse sin mucho trauma a html (olvide activar el TOC opcional, mañana en una actualizacion lo soluciono (y tambien cambio alguno que otro comando)), no exporta a pdf, ni nada parecido, tampoco tiene opciones para formulas matematicas, pero hay esta…

    Responder
  2. Pingback: En qué ando: abril | Onda Hostil

¡Opina sin miedo! (Puedes usar Markdown)

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s