Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/singond/gradle-pandoc
A Gradle plugin for converting markdown files to output with Pandoc
https://github.com/singond/gradle-pandoc
gradle-plugin pandoc
Last synced: 10 days ago
JSON representation
A Gradle plugin for converting markdown files to output with Pandoc
- Host: GitHub
- URL: https://github.com/singond/gradle-pandoc
- Owner: Singond
- License: apache-2.0
- Created: 2018-12-17T17:22:32.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2019-11-01T10:18:59.000Z (about 5 years ago)
- Last Synced: 2024-11-06T20:43:34.388Z (about 2 months ago)
- Topics: gradle-plugin, pandoc
- Language: Java
- Size: 47.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Pandoc plugin for Gradle
========================
This plugin enables using the Pandoc converter from a build script.
[Pandoc](https://pandoc.org/index.html) is a universal tool which can convert
documents to and from a wide array of formats, including (but not limited to)
Markdown, HTML, Texinfo, man, LaTeX, PDF and even Microsoft Word docx.
The plugin does _not_ come bundled with Pandoc. Instead, it uses system calls
to invoke whichever version of Pandoc is installed on your system. Please see
the Pandoc website in order to download the tool.
Requirements
------------
- [Pandoc](https://pandoc.org/index.html) and its dependencies must be
installed on your system.
Usage
=====
To enable the plugin, add the following to the top of your `build.gradle`:
```groovy
buildscript {
repositories {
maven {
url 'https://dl.bintray.com/singon/maven'
}
}
dependencies {
// Prefer a fixed version instead of '0.+'
classpath 'com.github.singond:gradle-pandoc:0.+'
}
}
apply plugin: 'com.github.singond.pandoc'
```
A new task type `Pandoc` is now available; its fully-qualified name is
`com.github.singond.gradle.pandoc.Pandoc`.
Also, a single instance of this task called `pandoc` has been added to your
project. You need to configure it first, for example:
```groovy
pandoc {
sources "docs"
outputDir "$buildDir/docs"
format "html", "html"
format "latex", "pdf"
}
```
This will convert every file in the `docs` directory into a corresponding
`html` and `pdf` file in the `${buildDir}/docs` directory, assuming thah
`pandoc` is installed on your system and available in `PATH`.
Locating Pandoc Installation
--------------
If the `pandoc` tool is not in your `PATH`, the build will not be able to
complete successfully. In order to correct this, specify another location by
adding:
```groovy
pandoc {
...
pandocPath "/path/to/pandoc"
}
```
Controlling Output
------------------
### Output Format
If you don't specify any conversion format, this plugin will not do anything.
To add a conversion format, specify its name, and (optionally) a corresponding
file name extension in the `format` method.
The format name (here, `latex`) must be a format name recognized by Pandoc.
Please refere to the `pandoc` manual for the list of available formats.
```groovy
pandoc {
...
format "latex", "pdf"
}
```
This tells Gradle to convert every source file into a `pdf` file by using
the `latex` conversion format. It roughly translates into:
```sh
pandoc filename.md --to=latex --output=filename.pdf
```
If the format name and file extension is the same, you can omit the second
argument:
```
pandoc {
...
format "html"
}
```
You can also specify more than one format:
```
pandoc {
...
format "latex", "pdf"
format "html"
}
```
This will convert every source file into a `pdf` file (through LaTeX)
and a `html` file.
### Output Directory
The converted files are placed into the `${outputDir}` directory.
By default, they are divided into subdirectories according to their type.
For example, consider we have the following file structure in the project root:
```
docs/
document-1.md
document-2.md
document-3.md
```
This is our `build.gradle`:
```
pandoc {
sources "docs"
outputDir "$buildDir/docs"
format "html"
format "latex", "pdf"
}
```
Running `gradle pandoc` will result in the following files being created
(assuming that your build directory is set to `build` (the default):
```
build/
docs/
html/
document-1.html
document-2.html
document-3.html
latex-pdf/
document-1.pdf
document-2.pdf
document-3.pdf
```
If you prefer not to split the output files into subdirectories by type,
you can set the `separateOutput` option to false:
```
pandoc {
sources "docs"
outputDir "$buildDir/docs"
format "html"
format "latex", "pdf"
separateOutput false
}
```
Assuming the same source files structure, this will yield:
```
build/
docs/
document-1.html
document-1.pdf
document-2.html
document-2.pdf
document-3.html
document-3.pdf
```