118 lines
2.5 KiB
Markdown
118 lines
2.5 KiB
Markdown
# Pandoc
|
|
|
|
A watcher and Mix tasks for installing and invoking [pandoc](https://pandoc.org/).
|
|
|
|
## 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:
|
|
|
|
```elixir
|
|
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:
|
|
|
|
```elixir
|
|
def deps do
|
|
[
|
|
{:pandoc, "~> 0.3", only: :dev}
|
|
]
|
|
end
|
|
```
|
|
|
|
Once installed, change your `config/config.exs` to pick your pandoc version of
|
|
choice:
|
|
|
|
```elixir
|
|
config :pandoc, version: "3.6.1"
|
|
```
|
|
|
|
Now you can install pandoc by running:
|
|
|
|
```bash
|
|
$ mix pandoc.install
|
|
```
|
|
|
|
And invoke pandoc with:
|
|
|
|
```bash
|
|
$ 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:
|
|
|
|
```elixir
|
|
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`:
|
|
|
|
```elixir
|
|
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`:
|
|
|
|
```elixir
|
|
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:
|
|
|
|
```elixir
|
|
pandoc: {Pandoc, :watch, [:default]}
|
|
```
|
|
|
|
Note we are enabling the file system watcher.
|
|
|
|
## Licence
|
|
|
|
pandoc source code is licensed under the MIT License.
|