Skip to content

Pandoc Integration

Jump to bottom Edit New page
tajmone edited this page Oct 6, 2018 · 7 revisions 
Highlight v3.40 | pandoc v2.0.2 | PP v2.0

Integrating Highlight in Pandoc Workflow

This page provides useful information on how to integrate Highlight into Markdown and reStructuredText source documents processed by pandoc.

Table of Contents

Introduction

The solution proposed here relies on three tools to achieve integration of Highlight in pandoc source files:

  1. Pandoc
  2. PP (a generic pandoc preprocessor)
  3. The Highlight.pp macros files found in Highlight’s /extras/padoc/ folder

Pandoc

Pandoc — aka "the universal markup converter" — is a well known command line tool for converting documents from one format to another, and especially from/to various markdown flavors, including "pandoc markdown" (an extended markdown variant introduced by pandoc itself).

Pandoc is widely used for academic papers and technical documentation, so it comes with a built-in syntax highlighter.

Pandoc v2 (Oct 2017), introduced the new --syntax-definition=FILE and --highlight-style=FILE options which now allow to load dynamically custom syntax definitions and styles for highlighting. Nonetheless, there might still be a number of reasons why you might wish to integrate Highlight into your pandoc workflow:

  • Pandoc doesn’t provide any means to import the source code from an external file — every time the source file changes, you have to manually copy-&-paste its contents again. Invoking Highlight via PP macros allows to highlight external source files into your document; and tweaking the PP macros to leverage some shell scripts you can even filter which lines to extract from a source file.
  • Pandoc might lack some syntax definitions which are available for Highlight (and viceversa).
  • Highlight plug-ins offer powerful features to fine-tune syntax highlighting.

Since pandoc’s internal highlighter and Highlight integration (via PP) can peacefully coexist in the same workflow — even using both in the same document — adding Highlight to the workflow is an added bonus, not an "either/or" situation.

Of course, using Highlight instead of pandoc’s skylighting does add some overhead to documents processing; but unless you’re chain-converting hundreds of documents containing syntax highlighted source code, the overhead impact will be negligible enough to justify the gained benefits.

PP

Highlight PP-Macros leverages PP, a generic preprocessor "written with pandoc in mind". PP adds to the pandoc workflow the power of user definable macros and a set of built-in macros for cross-platform file I/O operations and conditional branching — and many other great features not cover here.

Since one of PP’s goals was to introduce literate programming functionality to the pandoc workflow, it provides a solid base for handling external files, invoking third party tools, and perform operations on blocks of source code.

Highlight Macros

The file "Highlight.pp" from the examples folder contains the macros for integrating Highlight in pandoc workflow. It was taken from the "Pandoc Goodies" project, this file being one of the various macros modules that make up the PP-Macros Library subproject hosted therein:

If you intend using Highlight pp-macros, you are strongly adviced to check regularly the above link for updated versions of "Highlight.pp":

The macros in the /extras/pandoc/ folder are intended mainly as a starting example of how to integrate Highlight into pandoc workflow, and they may not reflect the latest release of the macros found on the Pandoc Goodies project.

Further Reading and Live Examples

HELP US MAKE THIS DOCUMENTATION GROW BY CONTRIBUTING CONTENTS

Add a custom sidebar
Clone this wiki locally