# pandox

> Rod's extensions for Pandoc, the universal document converter.

Latest version **0.0.2** (published 2013-11-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install pandox
pnpm add pandox
yarn add pandox
bun add pandox
```

Provides the commands `pandox-up-caser`, `pandox-string-combiner`, `pandox-code-block-processor`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2013-11-01 |
| First published | 2013-10-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.10.3 |
| Dependencies | 4 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Rod Waldhoff |
| Maintainers | rodw |
| Keywords | Pandoc, filter, pandocfilters, pandoc scripting, markdown, ast, json |

## Links

- npm: https://www.npmjs.com/package/pandox
- Repository: https://github.com/rodw/pandox
- Issues: http://github.com/rodw/pandox/issues
- npm.io page: https://npm.io/package/pandox

## Dependencies (4)

- [argf](https://npm.io/package/argf.md) latest
- [temp](https://npm.io/package/temp.md) latest
- [execSync](https://npm.io/package/execSync.md) latest
- [optimist](https://npm.io/package/optimist.md) latest

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.0.2 (latest) — 2013-11-01
- 0.0.1 — 2013-10-21

## README

# Pandox

## A collection of PANDOc eXtensions

**Pandox** is a small collection of utilities that extend [John MacFarlane's Pandoc](http://johnmacfarlane.net/pandoc/), the "universal document converter".

### Using

#### The Command Line Interface

The *Pandox* extensions are typically invoked by piping a JSON-formatted AST (generated via `pandoc -t json FILENAME`) in as stdin, and piping the transformed JSON-formatted AST to another pandoc invocation for rendering.  For example:

```console
> pandoc -t json README.md | coffee lib/up-caser.coffee | pandoc -f json -t html
```

will generate an HTML version of the `README.md` file, first applying the filter defined in `up-caser`.

The npm module includes directly executable scripts for each extension.  Hence:

```console
> pandoc -t json README.md | pandox-up-caser | pandoc -f json -t html
```

also works (following `npm install -g pandox`).

Use the `--help` or `-h` command line parameter for more information:

```console
> node lib/pandoc-filter.js --help

Usage: node lib/pandoc-filter.js [OPTIONS] [FILE]

Options:
  -h, --help    Show this help message.
  -f, --filter  A filter to apply before this one. May be repeated.

Examples:
  pandoc -t json FILE.md | node lib/pandoc-filter.js
  pandoc -t json FILE.md > FILE.json && node lib/pandoc-filter.js FILE.json
```

#### The API (Code-Level) Interface

*Pandox* processes the JSON-format abstact-syntax tree that *pandoc* can generate when given the `-t json` flag. The internal API is (intended to be) the same the [*Pandoc* filters API](http://johnmacfarlane.net/pandoc/scripting.html) that exists for Haskell and Python.

If you'd like to try your hand at writing custom JavaScript-based *Pandoc* filters, simply extend the `PandocFilter` class or supply a filtering method. For example:

```js
var PandocFilter = require('pandoc-filter');

function upcase(type,content) {
  if(type==='Str') {
    return { t:type, c:content.toUpperCase();
  } else {
    return null;
  }
}

var filter = new PandocFilter(upcase);
```

Several examples can be found in the `./lib` directory.

See the comments in `./lib/pandoc-filter.coffee` (or `./lib/pandoc-filter.js`) for a detailed explanation of the API.

### The Extensions

#### UpCaser

The `UpCaser` filter is a trivial extension primarily intended to serve as an example.

It will convert any string values to upper case, but ignores code blocks, urls, and other special cases.

Usage example:

```console
> pandoc -t json README.md | pandox-up-caser | pandoc -f json -t html
```

#### StringCombiner

By default, Pandoc's AST treats each (whitespace-delimited) word as an indepdent block.  For instance, the string:

    Hello World.

is represented in the AST as three separate blocks:

```js
[ { t:'Str',c:'Hello' }, { t:'Space',c:[] }, { t:'Str',c:'World.' } ]
```

The `StringCombiner` filter will collapse these sequences of strings and spaces into a single (multi-word) string:

```js
[ { t:'Str',c:'Hello World.' } ]
```

Usage example:

```console
> pandoc -t json MY-FILE.md | pandox-string-combiner | pandoc -f json -t html
```

#### CodeBlockProcessor

The `CodeBlockProcessor` filter adds several capabilities to the way in which *Pandoc* handles "fenced code blocks", such as:

    ```
    This is a sample of text inside a "fenced" code block.
    ```

*Pandoc* supports several parameters that control the way in which a code block is rendered.  The general form is:

    ```{#THE-ID .CLASS-ONE .CLASS-TWO NAME="VALUE" NAME2="VALUE2"}
    This is a sample of text inside a "fenced" code block.
    ```

where:

  * `#THE-ID` is used to identify the code block in things like HTML anchors and Latex cross-references.

  * `.CLASS-ONE`and `.CLASS-TWO` enumerate HTML classes to assign to the code block, and sometimes influence the rendering in other ways.  For example, adding the class `.numberLines` will cause *Pandoc* to number the lines in the code block when rendering it.

  * `NAME="VALUE"` and `NAME2="VALUE2"` enumerate name-value pairs that can be used to modify the way in which the code block is rendered. For example, adding the pair `startFrom=100` will cause *Pandoc* to number the lines starting with 100 rather than 1.

`CodeBlockProcessor` adds a few new parameters that can be controlled by name-value pairs.

  * `input-file` - replaces the body of the code block with the contents of the specified file.

  * `input-cmd` - replaces the body of the code block with output of the specified command.

  * `exec` - executes the body of the code block as it were a shell script

  * `output-file` - writes the body of the code block to the specified file.

  * `output-cmd` - pipes the body of the code block to the specified command.

Usage example:

```console
> pandoc -t json MY-FILE.md | pandox-code-block-processor | pandoc -f json -t html
```

## License

*Pandox* is made availble under an MIT-license. See `license.txt` for details.

---
_Source: https://npm.io/package/pandox · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._