Ir al contenido principal

Descripción

pandy es un wrapper para linea de comandos para pandoc más cositas copadas (si usas Markdown - HTML). Basicamente toma un archivo/carpeta, de qué formato convertir y a qué formato convertir, y lo corre por Pandoc.

Características:

  • Carpeta de output manteniendo o no la estructura
  • La fuente puede ser un archivo, una carpeta, .list que contenga las rutas a los archivoso .ini
  • Formatos: algunos se puede abreviar (mirar abajo)
  • Formato de salida: se pueden poner más de uno! solo separalo con espacios.
  • Podes crear un librito re lindo (HTML, solo añade navegación entre archivos) como una wiki o documentación. Si no te gusta/queres el "Next-Prev", podes usar los titulos de archivo. Crea un lindo y simple index o incluí el tuyo.
  • Usa un archivo de configuración: así no tenes que acordarte de todos los argumentos o escribir un "wrapper" para un script "wrapper" :)
  • Soporte para [TOC]. Significa que el archivo que lo tenga, va a tener una tabla de contenido. No mas eso de separar archivos con tabla de contenido, los que no tienen y finalmente ponerlos en una carpeta.
  • Si usas markdown y convertis a HTML hay cositas lindas para vos: abbreviations (de las verdaderas, no como esas que son ignoradas por pandoc), admonitions y WikiLinks.
  • Un template default no-tan-feo para libro

Uso

Ejecutalo como pandy FUENTE [opciones]

Los formatos son una selección de los mas usados:

  • de: docbook, html, json, latex, markdown, markdown_github, markdown_mmd, markdown_phpextra, markdown_strict, mediawiki (or mw), opml, rst, textile
  • salida: all the above + asciidoc, beamer, docx (or doc), epub, epub3, fb2, html5, odt, opendocument (or opendoc), pdf, plain, rtf, slides (or slide)
Todos los "markdown"s pueden escribirse como "md": markdown -> md; markdown_github -> md_github; etc. También, "link_attributes" y "hard_line_breaks" son habilitados automaticamente.

El formato de slides se especifica con --slides

Si unis y usas salida, solo tenes que especificar la carpeta. Toma el nombre de la carpeta padre/fuente.

pandy deja usar algunas opciones de pandoc pero con otros nombres:

SOURCE
Archivo, carpeta, .list or .ini. Un .list es un archivo que contiene las rutas a los archivos en el orden que se convertirán.
--from, -f
Formato de entrada
--to, -t
Formato/s de salida (puede ser una lista separada con espacios)
--output FOLDER, -o FOLDER
Carpeta de salida
--self
archivo contenido
--header FILE
Archivo Header. Incluido como es (Incluido como es: en crudo, verbatim)
--footer FILE
Archivo Footer. Incluido como es (Incluido como es: en crudo, verbatim)
--index FILE
Index personalizado para book. Puede usar wikiLinks
--html4
Usar html4 en lugar de html5
--merge, -m
Unir archivos.
--slides FORMAT
Formato para slides.
--bib FILE
Archivo de bibliografía
--css FILE
CSS externo
--highlight STYLE
Estilo de highlight
--highlight-no
Sin highlight
--tpl FILE
Archivo de template.
--toc, -t
Incluir TOC
--depth NUMBER
Profundidad de TOC
--hide
Esconder e-mail
--sections
Envolver en <section>s, identificadores ahi en lugar de los titulos
--pandoc PANDOC
Path de Pandoc. Default: pandoc
--data-dir FOLDER
Carpeta de datos
--flat
No mantener la estructura de la carpeta
--book, -b
Crear un libro con navegación (next/prev) e index
--no-nav, -nn
(Para book) deshabilitar la navegación del libro
--nav-title, -nt
(Para book) usar titulos en la navigación
--no-side, -ns
(Para book) deshabilitar la navegación del sidebar
--no-side-toc, -nst
(Para book) deshabilitar el TOC en el sidebar (dejar en el documento)
--config FILE
Usar archivo de configuración (option=valor)
--tpl-pandy
(For book) Template de Pandy: simple y no tan feo

Si usas Markdown y convertís a HTML, hay regalitos para vos. Podés tener abbreviations, como en PHP Markdown Extra (que se convierten en tales):

 Some text with an ABBR and a REF. Ignore REFERENCE and ref.

  *[ABBR]: Abbreviation
  *[REF]: Abbreviation Reference

Y admonitions:

 [class/type:optional title]
  - markdown
  - super
  - content

El class/type puede ser algo como "informacion", "peligro", "tip", "ayudita", "hambriento", "pato", "sippi"...

También podes incluir una etiqueta para tabla de contenido ([TOC]) para que ese archivo tenga TOC en lugar de poner --toc o separar archivos en dos grupos y después ponerlos juntos. (Lo añade automaticamente después de buscar el archivo, nada de magia).

"Book" (libro) convierte todos los archivos a HTML y agrega navegación. Muy bueno para documentación simple.

Index

Para ver un ejemplo de este uso, ir a mis notas de japones

Si usas Markdown, podes crear tu propio index (index.md)y tener wikilinks. Los WikiLinks pueden estar en cualquier archivo, como [:nombre-archivo][título opcional] donde nombre-archivo es el nombre del archivo con o sin extensión, y si no incluís un título, se encuentra el del archivo. El orden de los archivos en el index afecta a la navegación del sidebar. Con esto podes crear documentación mas copada o usarlo como una simple wiki.

Template

Si queres crear tu propio template para book, pandy agrega un par de variables para que incluyas:

Variable Explicación
side_navigation navegación de barra lateral
book_navigation navegación de libro (anterior/index/siguiente)
project-index link a index. Útil si tenes subcarpetas
project-title Título del Index. Útil si creas tu propio index con título

Si no te gusta poner las opciones en el CLI, o tener un script que llame a pandy con los argumentos que quieras, podes crear un archivo de configuración con clave = valor (como los ini). Ejemplo:

 PANDOC_DATA_DIR = C:\Program Files\Pandoc
 TEMPLATE = github.html
 HIGHLIGHT= zenburn
 FORMATS_TO = html pdf
 NAV = True

Especificar el archivo con --config (la extensión no importa, los INI headers son ignorados. No te preocupes) o tener un settings.ini donde corre pandy.

Descarga

pandy 2.0.3
Necesita Pandoc y Python 3

Python 3

Cambios

Versión 2.0.3

  • misc fixes/bugs
  • fixes for css

Versión 2.0

  • Total rewrite! Many fixes and (internal) cleanup/improvement.
  • new wiki links: like markdown reference links but inverted: [:file][title]
  • wikilinks in any file (not only index) (book)
  • auto discover index
  • if custom index has title, use it as project title
  • list all titles (and toc) in index
  • order files according to custom index
  • navigation: pages titles in sidebar, next-prev
  • option to hide navigation in book
  • option to exclude toc from sidebar navigation
  • Navigations in pandoc variables
  • built-in template (book)
  • modify command options
  • read .ini automatically in folder where runs/source
  • args take precedence over ini, which take precedence over default
  • change .ini format. See examples (basically remove quotes, lists are space separated)

Versión 1.9

  • only python 3
  • fixes for book
  • prints file being converted
  • Filter extensions for converting, only html (hardcoded)
  • add titles in sidebar for navigation (--navside). Include book_navigation in your Pandoc template

Versión 1.8.1

  • New admonition syntax

Versión 1.8

  • Clean up code and refactoring
  • default config in dictionary
  • minor fix for admonitions
  • Fix finding H1
  • config file support (ini without sections)
  • changes to args
  • add processing messages
  • no more tmp files
  • Fix merging
  • merge (HTML): now can parse metadata block and have toc for full document
  • book: include toc ONLY on selected file
  • book: fix having title twice in file when declared with meta-block
  • fix titles in book: add them, if not found add the filename (no extension)
  • wikiLinks: if md link has no title and it's an existing file, use the filename as title
  • Book: warn if no output path (defaults to current directory) and source directory is the running one
  • config dict takes precedence over args

Versión 1.5

  • Rewritten!
  • Add abbreviations parsing: markdown -> html
  • Add admonition parsing
  • Add warning when book also have other output formatting & html
  • Add warning custom index with wiki links only for markdown
  • Add more formats for input and output
  • fix: formats_to: no duplicates
  • fix: --nav only for book
  • fix: add html5 output default, can change to html with --html4
  • fix: when merging add title HTML tag

Versión 1.0

  • First release
  • folder (recursive) support
  • merge files in directory (automatically)