Skip to content

Latest commit

 

History

History

pp

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
macros
macros
 
 
test
test
 
 
README.md
README.md
 
 
TODO.md
TODO.md
 
 

README.md

PP-Macros

PP v2.8 | pandoc v2.7.2

"The Pandoc-Goodies PP-Macros Library" — An ongoing collaborative effort to build a library of PP macros to extend pandoc workflow: custom inline and block styling in pandoc documents, external syntax highlighters, interaction with external scripts and tools, and much more.

Copyright © Tristano Ajmone 2017, MIT License.

Table of Contents

Introduction

The /macros/ folder is the container of the pp-macros library. The library is a collection of various macros files, all ending with .pp extension (an arbitrary choice). Each file is a collection of macros for a specific topic. The separation of macros into different files is intended to facilitate selecting and discarding specific macros, and mixing them with macros from elsewhere.

The file macros.pp is the main macros file, which loads all other macros.

About PP

PP is a text preprocessor designed by Christophe Delord (@CDSoft) for pandoc (and more generally Markdown and reStructuredText). PP ships with some very powerful built-in macros for literate programming, diagrams (GraphViz, PlantUML and ditaa), figures (Asymptote and R) and invoking scripts (Bash, Cmd, PowerShell, Python, Haskell and R) within markdown source files.

But the great power of PP is it's extensibility through user-defined macros, branching and conditional statements.

PP is cross-platform and available as a single standalone binary file:

For some introductory tutorials on using PP, see:

Requirements

The current macros library requires PP version >= 2.8.

PP is evolving rapidly thanks to Christophe's kind dedication to users' features requests. Future versions of PP might break backward compatibility of some macros, but I'll try to ensure that the macros of this library should always work with the latest release of PP.

At the beginning of this page you'll always find an opening line reporting the latest PP version used for testing the macros library.

You can download prebuilt binaries of the latest version of PP from the following link:

Or you can download and compile the sources (Haskell) of specific PP releases from GitHub:

If you are looking for binaries of a specific release of PP, you can visit PP's Download Archive page:

Available Macros

Currently, our PP macros library offers only macros targeting HTML output.

"The Pandoc-Goodies PP-Macros Library" is organized into separate module files ("pp-macros sets"), stored in the /macros/ folder:

NOTE: Since the release of PP v1.7-2 macros that were Windows-only are now cross-platform.

GitHub Alerts

GFM-Alerts.pp
GFM-Alerts.css

A set of macros to create GitHub alerts (aka flash messages) within pandoc documents:

macros:

  • !GFMAlertsInlineCSS — Inject required CSS
  • !GFMAlert( CONTENTS ) — Alert (blue)
  • !GFMError( CONTENTS ) — Warning (red)
  • !GFMWarn( CONTENTS ) — Error (yellow)
  • !GFMSuccess( CONTENTS ) — Success (green)
  • !GFMAlertNote( CONTENTS ) — Note (grey)
  • !GFMAlertPlain( CONTENTS ) — same as Note (alias of !GFMAlertNote)

CHANGES --- Since GFM-Alerts.pp v2.1 the HTML tags and the CSS produced by these macros have changed: Alerts are now wrapped in a single <div>, and class names have changed.

Also, the new !GFMAlertNote macro replaces !GFMAlertPlain (which is kept as an alias).

The changes are backward compatible, so you don't need to change your documents to keep using them.

To render the alerts properly you'll need the definitions found in "GFM-Alerts.css". You can either:

  1. Include "GFM-Alerts.css" in the final document via pandoc --css option — you can exploit the %PP_MACROS_PATH% env var: --css %PP_MACROS_PATH%GFM-Alerts.css
  2. Add the contents of "GFM-Alerts.css" to your pandoc template stylesheet.
  3. Use the !GFMAlertsInlineCSS macro to inject "GFM-Alerts.css" as an inline CSS definition in the final document.

PANDOC v2 FENCED DIVS --- Pandoc v2.x users are advised to use the new fenced divs syntax instead of these PP macros: fenced divs offer finer control over the final HTML, and pandoc can convert them to other formats too (unlike raw HTML injected into markdown source). The final result is exactly the same. See /test/GFM-Alerts.html for an example and more details.

As for other markdown flavours or tools, these macros will continue to be useful. And of course, the !GFMAlertsInlineCSS remains useful for all users.

NOTE --- The "Note" alert (alias "Plain", grey colours) isn't part of the original Primer-CSS alerts set. It was added to provide a more neutral, less showy alert box.

Examples:

Highlight

Highlight.pp

A set of macros for using André Simon's Highlight tool:

macros:

  • !HighlightFile(FILE)(LANG)[(OPTIONS)] — imports and syntax-highlights and external file. Output is a raw html <pre><code> block.
  • !Highlight(LANG)([OPTIONS])(CODE) — syntax-highlights the block of source code passed as CODE parameter (using lines of tildes instead of brackets; see Note below).
  • !HighlightInlineTheme(THEME) — retrieves a Highlight theme and injects its CSS version into the documents. A quick solution for theming Highlight code without having to import an external CSS file via pandoc.

NOTE 1: The CODE parameter is passed between lines of tildes instead of brackets:

  !Highlight( LANG )( OPTIONS )
  ~~~~~
  CODE
  ~~~~~
  }

From PP's documentation:

The last argument can be enclosed between lines of tildes or backticks (of the same length) instead of parenthesis, brackets or braces and. This is useful for literate programming, diagrams or scripts (see examples). Code block arguments are not stripped: spaces and blank lines are preserved.

NOTE 2: This macro, when run inside Windows CMD, creates a temporary file (named "_pp-tempfileX.tmp", where X is a numeric counter) in the macros folder (/pp/macros/) for each macro call in the document, to temporarily store the code to highlight. At each PP invocation the X counter is reset, and the previous temp files are written over. These temporary files are set to be ignored by Git, so you shouldn't worry about them.

When run inside Shell/Bash (including Git Bash for Windows) it doesn't write any temporary files to disk.

NOTE 3: You can use Highlight along with pandoc built in syntax highlighter — pandoc only highlights markdown code blocks (fenced, or backticked) and will ignore the <pre><code> raw html blocks produced by Highlight.

Pandoc automatically adds its own stylesheet for its highlighted code, the Highlight macro doesn't.

Pandoc highlighted source code uses different tags from Highlight, so their stylesheets won't clash nor overlap.

Examples:

Inline Formatting

InlineFormatting.pp
kbd_GitHub.css

A convenience set of shortcut-macros for various standard html inline elements:

  • !kbd( KEY1 )[( KEY2 )( KEY3 )( KEY4 )] — keystrokes in <kbd> tags.
  • !kbdInlineCSS — Inject required CSS ("kbd_GitHub.css")

The !kbd macro can take from 1 to 4 parameters, each representing the text to show in the Keystroke.

Examples:

Macros Documentation

WIP! Coming soon…

Documentation and usage examples for the macros library is still work in progress. Right now, to gain insight into the macros you should refer to the /test/ folder, an peek at the markdown source of the template preview and the batch files used to convert it: