Pandoc

A watcher and Mix tasks for installing and invoking pandoc.

Requirements

Currently only supports linux-amd64 architectures.

Installation

If you are going to convert markup in production, then you add pandoc as dependency on all environments but only start it in dev:

def deps do
  [
    {:pandoc, "~> 0.3", runtime: Mix.env() == :dev}
  ]
end

However, if your markup is preconverted during development, then it only needs to be a dev dependency:

def deps do
  [
    {:pandoc, "~> 0.3", only: :dev}
  ]
end

Once installed, change your config/config.exs to pick your pandoc version of choice:

config :pandoc, version: "3.6.1"

Now you can install pandoc by running:

$ mix pandoc.install

And invoke pandoc with:

$ mix pandoc default documents/hello.md -o priv/static/posts/hello.html

The executable is kept at _build/pandoc-TARGET. Where TARGET is your system target architecture.

Profiles

The first argument to pandoc is the execution profile. You can define multiple execution profiles with the current directory, the OS environment, and default arguments to the pandoc task:

config :pandoc,
  version: "3.6.1",
  default: [
    args: ~w(--mathjax),
    cd: Path.expand("../documents", __DIR__)
  ]

When mix pandoc default is invoked, the task arguments will be appended to the ones configured above. Note profiles must be configured in your config/config.exs, as pandoc runs without starting your application (and therefore it won't pick settings in config/runtime.exs).

Adding to Phoenix

To add pandoc to an application using Phoenix, you will need Phoenix v1.6+ and the following steps.

First add it as a dependency in your mix.exs:

def deps do
  [
    {:phoenix, "~> 1.6"},
    {:pandoc, "~> 0.3", runtime: Mix.env() == :dev}
  ]
end

Now let's change config/config.exs to configure pandoc to write to priv/static/posts:

config :pandoc,
  version: "3.6.1",
  default: [
    args: fn extra_args ->
      {_, [input_file], _} = OptionParser.parse(extra_args, switches: [])
      ~w(--output=../priv/static/posts/#{Path.rootname(input_file)}.html)
    end,
    cd: Path.expand("../documents", __DIR__)
  ]

For development, we want to enable the watcher. So find the watchers configuration in your config/dev.exs and add:

pandoc: {Pandoc, :watch, [:default]}

Note we are enabling the file system watcher.

Licence

pandoc source code is licensed under the MIT License.