https://github.com/smimram/ocaml-pandoc

An OCaml library for creating pandoc filters.
https://github.com/smimram/ocaml-pandoc

ocaml pandoc

Last synced: 3 months ago
JSON representation

An OCaml library for creating pandoc filters.

• Host: GitHub
• URL: https://github.com/smimram/ocaml-pandoc
• Owner: smimram
• License: lgpl-2.1
• Created: 2021-04-28T06:25:52.000Z (almost 4 years ago)
• Default Branch: master
• Last Pushed: 2023-12-15T17:30:16.000Z (about 1 year ago)
• Last Synced: 2024-04-20T00:53:58.732Z (10 months ago)
• Topics: ocaml, pandoc
• Language: OCaml
• Homepage: https://smimram.github.io/ocaml-pandoc
• Size: 358 KB
• Stars: 29
• Watchers: 3
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGES.md
  • License: LICENSE

Awesome Lists containing this project

README

        
The OCaml pandoc library

========================

This library is meant to help creating filters for [pandoc](https://pandoc.org/)

which is tool to convert between textual formats, notably markdown and LaTeX. It

is vaguely inspired of the corresponding [Haskell

library](http://hackage.haskell.org/package/pandoc-types).

Documentation

-------------

The documentation for the library is [available

online](https://smimram.github.io/ocaml-pandoc/).

Building filters

----------------

Basically, a pandoc filter will

1. read JSON data from the standard input with `Yojson.Basic.from_channel`,

2. convert it to the library's standard representation with `Pandoc.of_json`,

3. transform it using the `Pandoc.map` function which recursively maps functions

  on various elements,

4. convert the result to JSON with `Pandoc.of_json`,

5. print the result on the standard output using `Yojson.Basic.to_string`.

Once you have build your filter (say, `myfilter`) you can use it to transform

pandoc documents while they are being processed by using the `--filter`

commandline argument. For instance:

```bash

pandoc --filter=myfilter file.md -o file.pdf

```

Examples

--------

Some examples are provided in the [examples](examples/) directory for you

convenience (or because I needed those).

- `pandoc-abbreviations`: adds non-breakable spaces after abbreviations (listed

  in `abbreviations` file). Pandoc already does this natively, but it does not

  play well with other plugins.

- `pandoc-crossref`: handles cross-references in LaTeX. It replaces references

  of the form `#chap:bla` and `#sec:bli` to `\cref{chap:bla}` and

  `\cref{sec:bli}` respectively.

- `pandoc-include`: includes other documents. It replaces

  ```

  !include "file"

  ```

  

  by the contents of the file `file`, it replaces

  

  ~~~

  ```{.ocaml include="test.ml" from=2 to=5}

  ```

  ~~~

  

  by the contents of the file `test.ml` between lines 2 and 5, it replaces

  ~~~

  ```{.ocaml include="test.ml" from=2 to=-1}

  ```

  ~~~

  

  by the content from line 2 to last but one line, it replaces

  ~~~

  ```{.ocaml include="test.ml" from="BEGIN" to="TO"}

  ```

  ~~~

  

  by the content between lines containing "BEGIN" and "END", excluded. Useful

  for including small code snippets delimited by comments such as `(* BEGIN *)`

  and `(* END *)`.

- `pandoc-inspect`: acts as the identity plugin, but prints the JSON output

  given by pandoc on the standard error. Useful for debugging and adding missing

  features to the library.

- `pandoc-pdf2png`: changes the extension of images from `.pdf` to

  `.png`. Useful if you want to compile both to pdf and html.

- `pandoc-replace`: replaces words by others. Useful for fixing capitalization

  for instance.

Bugs and features requests

--------------------------

The code is simple and stable enough for me but some features are missing. Feel

free to fill [bug reports](https://github.com/smimram/ocaml-pandoc/issues) or

submit [pull requests](https://github.com/smimram/ocaml-pandoc/pulls).