,
Posit Software, PBC [cph, fnd]| Title: | Manage and Run Universal Converter 'Pandoc' from 'R' |
|---|---|
| Description: | Provides a set of tools to install, manage and run several 'Pandoc' versions. |
| Authors: | Christophe Dervieux [aut, cre]
,
Posit Software, PBC [cph, fnd] |
| Maintainer: | Christophe Dervieux <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0.9001 |
| Built: | 2024-06-26 04:30:56 UTC |
| Source: | https://github.com/cderv/pandoc |
This function will set the specified version as the default version for the session. By default, the default active version in the most recent one among the installed version (nightly version excluded.)
pandoc_activate( version = "latest", rmarkdown = getOption("pandoc.activate_rmarkdown", TRUE), quiet = FALSE )pandoc_activate( version = "latest", rmarkdown = getOption("pandoc.activate_rmarkdown", TRUE), quiet = FALSE )
version |
This can be either:
|
rmarkdown |
if |
quiet |
|
invisibly, the previous active version.
If the version to activate is not yet installed, the user will be prompted
to choose to install the version.
When the package is loaded, an active version is set to the first Pandoc binary found between:
the latest Pandoc version installed with this package (e.g "2.14.2")
the version shipped with RStudio IDE. (version = "rstudio")
a version available in PATH (version = "system")
# activate version 2.18, including for use with rmarkdown package pandoc_activate("2.18") # activate only for this package functions and not rmarkdown pandoc_activate("2.18", rmarkdown = FALSE)# activate version 2.18, including for use with rmarkdown package pandoc_activate("2.18") # activate only for this package functions and not rmarkdown pandoc_activate("2.18", rmarkdown = FALSE)
This function allows to test if an active Pandoc version meets a min, max or
in between requirement. See pandoc_activate() about active
version.
pandoc_available(min = NULL, max = NULL)pandoc_available(min = NULL, max = NULL)
min |
Minimum version expected. |
max |
Maximum version expected |
If min and max are provided, this will check the active version is
in-between two versions. If non is provided (keeping the default NULL for
both), it will check for an active version and return FALSE if none is
active.
logical. TRUE if requirement is met, FALSE otherwise.
# Is there an active version available ? pandoc_available() # check for a minimum requirement pandoc_available(min = "2.11") # check for a maximum version pandoc_available(max = "2.18") # only returns TRUE if Pandoc version is between two bounds pandoc_available(min = "2.11", max = "2.12")# Is there an active version available ? pandoc_available() # check for a minimum requirement pandoc_available(min = "2.11") # check for a maximum version pandoc_available(max = "2.18") # only returns TRUE if Pandoc version is between two bounds pandoc_available(min = "2.11", max = "2.12")
This function will fetch information from Github https://github.com/jgm/pandoc about available Pandoc versions released.
pandoc_available_releases()pandoc_available_releases()
character vector of all available release.
pandoc_install(), pandoc_installed_versions()
Get path to the pandoc binary
pandoc_bin(version = "default") pandoc_bin_browse(version = "default")pandoc_bin(version = "default") pandoc_bin_browse(version = "default")
version |
Version to use. Default will be the
|
pandoc_bin_browse() allows to open in OS explorer the folder where
pandoc_bin() is at, when in interactive mode only.
Absolute path to the pandoc binary of the requested version.
pandoc_bin() pandoc_bin("2.18") pandoc_bin("nightly") pandoc_bin("rstudio") pandoc_bin("system") pandoc_bin_browse("2.18")pandoc_bin() pandoc_bin("2.18") pandoc_bin("nightly") pandoc_bin("rstudio") pandoc_bin("system") pandoc_bin_browse("2.18")
Open Pandoc's documentation about citation processing
pandoc_browse_citation()pandoc_browse_citation()
Open the webpage at the place regarding citation processing in Pandoc.
pandoc_browse_citation()pandoc_browse_citation()
Open Pandoc's documentation about exit codes
pandoc_browse_exit_code()pandoc_browse_exit_code()
Open the webpage at the place regarding exit code thrown by Pandoc.
pandoc_browse_exit_code()pandoc_browse_exit_code()
Open Pandoc's documentation about an extension
pandoc_browse_extension(extension = NULL)pandoc_browse_extension(extension = NULL)
extension |
One of the supported extension. See
|
Open the webpage at the place regarding the required extension.
pandoc_browse_extension() pandoc_browse_extension("auto_identifiers")pandoc_browse_extension() pandoc_browse_extension("auto_identifiers")
Open Pandoc's MANUAL
pandoc_browse_manual(id = NULL)pandoc_browse_manual(id = NULL)
id |
One of the id available in the HTML page (usually for anchor link). |
Open the Pandoc's MANUAL
https://pandoc.org/MANUAL.html
# open MANUAL home page pandoc_browse_manual() # open MANUAL at math part pandoc_browse_manual("math")# open MANUAL home page pandoc_browse_manual() # open MANUAL at math part pandoc_browse_manual("math")
Open Pandoc's documentation about a command line option
pandoc_browse_option(option = NULL)pandoc_browse_option(option = NULL)
option |
One of the supported long form command line option. As the Pandoc MANUAL only concerns the last released Pandoc's version, if the URL is incorrect this could mean the option has changed. |
Open the webpage at the place regarding the required option
pandoc_browse_option() pandoc_browse_option("embed-resources")pandoc_browse_option() pandoc_browse_option("embed-resources")
Open Pandoc's release page in browser
pandoc_browse_release(version = "latest")pandoc_browse_release(version = "latest")
version |
One of pandoc release version number (e.g '2.11.2') or |
Open the web page in browser in interactive mode or print the url
https://github.com/jgm/pandoc/releases
pandoc_browse_release() pandoc_browse_release("2.14")pandoc_browse_release() pandoc_browse_release("2.14")
This function will return the path to pandoc-citeproc if available. It will
only work with version of Pandoc installed by this package.
pandoc_citeproc_bin(version = "default")pandoc_citeproc_bin(version = "default")
version |
Version to use. Default will be the
|
the path to pandoc-citeproc binary if it exists. Since Pandoc 2.11,
the citeproc filter has been included into Pandoc itself and is no more
shipped as a binary filter.
# Look into current active version pandoc_citeproc_bin() # Look into a specific version pandoc_citeproc_bin("2.9.2")# Look into current active version pandoc_citeproc_bin() # Look into a specific version pandoc_citeproc_bin("2.9.2")
Main usage of Pandoc is to convert some text from a format into another. This function will do just that:
converting from a file or directly from text
writing to a file or directly to console
pandoc_convert( file = NULL, text = NULL, from = "markdown", to, output = NULL, standalone = FALSE, args = c(), version = "default" )pandoc_convert( file = NULL, text = NULL, from = "markdown", to, output = NULL, standalone = FALSE, args = c(), version = "default" )
file, text
|
One or the other should be provided |
from |
Format to convert from. This must be one of the format supported
by Pandoc. Default will be |
to |
Format to convert to. This must be one of the format supported by
Pandoc. This correspond to the |
output |
Pass a path to a file to write the result from Pandoc
conversion into a file. This corresponds to the |
standalone |
Should appropriate header and footer be included ?
This corresponds to |
args |
Any other flag supported by Pandoc CLI. See https://pandoc.org/MANUAL.html#options |
version |
Version to use. Default will be the
|
output is provided, the absolute file path. If not, the output of
pandoc binary run.
pandoc::pandoc_convert(text = "_This will be emphasize_", to = "latex") pandoc::pandoc_convert(text = "**This will be bold**", to = "html", version = "2.11.4")pandoc::pandoc_convert(text = "_This will be emphasize_", to = "latex") pandoc::pandoc_convert(text = "**This will be bold**", to = "html", version = "2.11.4")
This correspond to the --print-default-data-file CLI flag using
also --output to write a export a data file built in Pandoc.
pandoc_export_data_file(file, output = file, version = "default") pandoc_export_reference_doc(type = c("docx", "pptx"), version = "default")pandoc_export_data_file(file, output = file, version = "default") pandoc_export_reference_doc(type = c("docx", "pptx"), version = "default")
file |
One of data file name included in Pandoc (e.g |
output |
Path where to export the file. Default to working directory with the same file name. |
version |
Version to use. Default will be the
|
type |
one of |
pandoc_export_reference_doc() is a helper to quickly get the reference doc for
Word document (reference.docx) or Powerpoint document (reference.pptx)
the output (invisibly) where export has been done
# export style.html file included in Pandoc HTML template pandoc_export_data_file("styles.html", output = "custom.html") # export css file used for epub by default pandoc_export_data_file("epub.css") pandoc_export_reference_doc("docx") pandoc_export_reference_doc("pptx") pandoc_export_reference_doc("pptx", version = "2.11.4")# export style.html file included in Pandoc HTML template pandoc_export_data_file("styles.html", output = "custom.html") # export css file used for epub by default pandoc_export_data_file("epub.css") pandoc_export_reference_doc("docx") pandoc_export_reference_doc("pptx") pandoc_export_reference_doc("pptx", version = "2.11.4")
Pandoc highlighting can be customize using a JSON .theme file, passed to
--highlight-style= flag. This function
allows to generate the JSON version of one of the supported highlighting
style.
pandoc_export_highlight_theme( style = "pygments", output = style, version = "default" )pandoc_export_highlight_theme( style = "pygments", output = style, version = "default" )
style |
One of the support highlighting style. (See |
output |
Path (without extension) where to export the JSON |
version |
Version to use. Default will be the
|
The .theme extension is required and it will be enforced in during the
export by this function.
the filename where the theme has been exported.
This correspond to the --print-highlight-style CLI flag using
also --output to write a export a data file built in Pandoc.
# export tango theme used by Pandoc highlighting to `tango.theme` file pandoc_export_highlight_theme("tango") pandoc_export_highlight_theme("pygments", output = "my_theme.theme") pandoc_export_highlight_theme("zenburn", version = "system")# export tango theme used by Pandoc highlighting to `tango.theme` file pandoc_export_highlight_theme("tango") pandoc_export_highlight_theme("pygments", output = "my_theme.theme") pandoc_export_highlight_theme("zenburn", version = "system")
This correspond to the --print-default-template CLI flag. With
this function, one can easily export default LaTeX template for example.
pandoc_export_template(format = "markdown", output = NULL, version = "default")pandoc_export_template(format = "markdown", output = NULL, version = "default")
format |
One of Pandoc format using a text template. (e.g html, latex, revealjs) |
output |
Path where to save the file. If not provided, the default, template content will be print to the console. |
version |
Version to use. Default will be the
|
If output is not provided, the content of the template will be
printed and return as one string (invisibly). If output is provided, the file path of
the output (invisibly).
pandoc_export_template() pandoc_export_template("latex", output = "default.tex", version = "system")pandoc_export_template() pandoc_export_template("latex", output = "default.tex", version = "system")
Binary releases of Pandoc are available on its release page. By default, this
function will install the latest available version.
pandoc_install_nightly() is a wrapper for pandoc_install("nightly").
pandoc_update() is an alias for pandoc_install() default behavior.
pandoc_install(version = "latest", force = FALSE) pandoc_update() pandoc_install_nightly(n_last = 1L)pandoc_install(version = "latest", force = FALSE) pandoc_update() pandoc_install_nightly(n_last = 1L)
version |
This can be either:
|
force |
To set to |
n_last |
Set to |
Pandoc versions are installed in user data directories with one folder per
version. See pandoc_locate().
Only one nightly version is available at a time as there should be no need to switch between them. The latest nightly will be installed over the current one if any. Installing nightly version is useful for example to test a bug against the very last available built version.
Invisibly, the path where the binary is installed otherwise. NULL if already
installed.
# Install the latest pandoc version pandoc_install() # or pandoc_update() pandoc_uninstall("latest") # Install a specific pandoc version pandoc_install("2.11.4") pandoc_uninstall("2.11.4") # Install last nightly build of pandoc pandoc_install_nightly() pandoc_uninstall("nightly")# Install the latest pandoc version pandoc_install() # or pandoc_update() pandoc_uninstall("latest") # Install a specific pandoc version pandoc_install("2.11.4") pandoc_uninstall("2.11.4") # Install last nightly build of pandoc pandoc_install_nightly() pandoc_uninstall("nightly")
pandoc_installed_versions() lists all versions already installed
pandoc_installed_latest() returns the most recent installed version
pandoc_is_installed() allows to check for a specific installed version
pandoc_installed_versions() pandoc_installed_latest() pandoc_is_installed(version, error = FALSE, ask = FALSE)pandoc_installed_versions() pandoc_installed_latest() pandoc_is_installed(version, error = FALSE, ask = FALSE)
version |
This can be either:
|
error |
if |
ask |
if |
A character vector of installed versions or a logical for
pandoc_is_installed(). It will return NULL is no versions are installed.
For pandoc_is_installed(), TRUE if only the required version is
installed. If FALSE and ask is TRUE, the user will be prompt for
installing the version.
pandoc_installed_versions() pandoc_installed_latest() pandoc_is_installed("2.19.2") pandoc_installed_latest()pandoc_installed_versions() pandoc_installed_latest() pandoc_is_installed("2.19.2") pandoc_installed_latest()
Is a pandoc version active ?
pandoc_is_active(version)pandoc_is_active(version)
version |
This can be either:
|
TRUE is the version provided is currently the active one (i.e the one used when special "default" keyword is used).
# is Pandoc 2.19.2 active ? pandoc_is_active("2.19.2") # is it the Pandoc in PATH which is active ? pandoc_is_active("system")# is Pandoc 2.19.2 active ? pandoc_is_active("2.19.2") # is it the Pandoc in PATH which is active ? pandoc_is_active("system")
Pandoc uses this list in the Markdown reader. Strings found in this list will be followed by a non-breaking space, and the period will not produce sentence-ending space in formats like LaTeX. The strings may not contain spaces.
pandoc_list_abbreviations(version = "default")pandoc_list_abbreviations(version = "default")
version |
Version to use. Default will be the
|
This correspond to the option --abbreviations as CLI flag.
a character version of system default abbreviation known by Pandoc
pandoc_list_abbreviations() # check abbreviations available in a specific Pandoc's version pandoc_list_abbreviations("2.11.4")pandoc_list_abbreviations() # check abbreviations available in a specific Pandoc's version pandoc_list_abbreviations("2.11.4")
Pandoc has a system of extensions to activate or deactivate some features. Each format have a set of activated by default extensions and other supported extensions than can be activated.
pandoc_list_extensions(format = "markdown", version = "default")pandoc_list_extensions(format = "markdown", version = "default")
format |
One for the supported |
version |
Version to use. Default will be the
|
All the extensions for the last Pandoc version released are available in https://pandoc.org/MANUAL.html.
a data.frame (or a tibble if available) with 3 columns:
format: One of the Pandoc format
extensions : name of the extensions
default: Is the extensions activated by default or not ?
pandoc_list_extensions("markdown") pandoc_list_extensions("gfm") # target a specific version pandoc_list_extensions("html", version = "system")pandoc_list_extensions("markdown") pandoc_list_extensions("gfm") # target a specific version pandoc_list_extensions("html", version = "system")
List available supported formats
pandoc_list_formats(type = c("input", "output"), version = "default")pandoc_list_formats(type = c("input", "output"), version = "default")
type |
Either list |
version |
Version to use. Default will be the
|
a data.frame (or a tibble if available) with 2 column:
type (input or output)
formats (name of the formats that can be used as input or output)
# which input formats are available pandoc_list_formats() # which output formats are available pandoc_list_formats() # target a specific version pandoc_list_formats("input", version = "system")# which input formats are available pandoc_list_formats() # which output formats are available pandoc_list_formats() # target a specific version pandoc_list_formats("input", version = "system")
This function is useful to retrieve the supported languages by Pandoc's
syntax highlighter. These are the values that can be used as fenced code
attributes to trigger the highlighting of the block for the requested
language. See fenced_code_attributes extensions flag.
pandoc_list_highlight_languages(version = "default")pandoc_list_highlight_languages(version = "default")
version |
Version to use. Default will be the
|
a character vector of supported languages to use as fenced code attributes.
pandoc_list_highlight_languages() # check languages available in a specific Pandoc's version pandoc_list_highlight_languages("2.11.4")pandoc_list_highlight_languages() # check languages available in a specific Pandoc's version pandoc_list_highlight_languages("2.11.4")
Pandoc includes a highlighter which offer a styling mechanism to specify the
coloring style to be used in highlighted source code. This function returns
the supported values which can be specify at pandoc command line using the
--highlight-style= flag.
pandoc_list_highlight_style(version = "default")pandoc_list_highlight_style(version = "default")
version |
Version to use. Default will be the
|
a character vector of supported highlighting style name to use.
pandoc_list_highlight_style() # check style available in a specific Pandoc's version pandoc_list_highlight_style("2.11.4")pandoc_list_highlight_style() # check style available in a specific Pandoc's version pandoc_list_highlight_style("2.11.4")
This package helps install and manage Pandoc binaries in a specific folder.
This function helps with finding the path to those specific versions of Pandoc.
See pandoc_bin() for another way of getting paths to pandoc binaries
pandoc_locate(version = "default")pandoc_locate(version = "default")
version |
Version to use. Default will be the
|
Path of Pandoc binaries root folder if version is available.
# where is the default active version located ? pandoc_locate() pandoc::pandoc_is_installed("2.11.4") # where is a specific installed version located pandoc_locate("2.11.4") # return root folder of installed versions pandoc_locate(NULL)# where is the default active version located ? pandoc_locate() pandoc::pandoc_is_installed("2.11.4") # where is a specific installed version located pandoc_locate("2.11.4") # return root folder of installed versions pandoc_locate(NULL)
This function is a thin wrapper around the pandoc binary and allow to pass any arguments supported by the Pandoc binary.
pandoc_run(args, version = "default")pandoc_run(args, version = "default")
args |
Character vector, arguments to the pandoc CLI command |
version |
Version to use. Default will be the
|
The output of running pandoc binary
# Run any command line argument (prefer `pandoc_convert()` for conversion ) pandoc::pandoc_run(c("--version")) pandoc::pandoc_run(c("--list-input-formats"), version = "system")# Run any command line argument (prefer `pandoc_convert()` for conversion ) pandoc::pandoc_run(c("--version")) pandoc::pandoc_run(c("--list-input-formats"), version = "system")
You can run pandoc_installed_versions() to see which versions are
currently installed on the system.
pandoc_uninstall(version)pandoc_uninstall(version)
version |
which version to uninstalled. |
TRUE (invisibly) if uninstalling is successful.
pandoc_install("2.19.2") pandoc_is_installed("2.19.2") pandoc_uninstall("2.19.2")pandoc_install("2.19.2") pandoc_is_installed("2.19.2") pandoc_uninstall("2.19.2")
This is calling pandoc --version to retrieve the version of Pandoc used. A
special treatment is done for nightly version as Pandoc project does not
use a development version scheme between released versions. This function
will add a .9999 suffix to the version reported by Pandoc.
pandoc_version(version = "default")pandoc_version(version = "default")
version |
Version to use. Default will be the
|
The version number for pandoc binary as a base::numeric_version() object.
pandoc::pandoc_version() pandoc::pandoc_version(version = "system")pandoc::pandoc_version() pandoc::pandoc_version(version = "system")
RStudio IDE ships with a pandoc binary. The path is stored in RSTUDIO_PANDOC
environment variable. Theses function are helper to easily use this specific version.
pandoc_rstudio_version() pandoc_rstudio_bin()pandoc_rstudio_version() pandoc_rstudio_bin()
pandoc_rstudio_version() returns the version number for pandoc binary used by RStudio IDE as a base::numeric_version() object.
pandoc_system_bin() returns absolute path to the pandoc binary used by RStudio IDE.
pandoc_version(), pandoc_bin()
pandoc_rstudio_bin()pandoc_rstudio_bin()
Pandoc can also be installed on a system and available through the PATH. Theses function are helper to easily use this specific version.
pandoc_system_version() pandoc_system_bin()pandoc_system_version() pandoc_system_bin()
pandoc_system_version() returns the version number for pandoc binary found in PATH as a base::numeric_version() object.
pandoc_system_bin() returns absolute path to the pandoc binary found in PATH.
pandoc_version(), pandoc_bin()
pandoc_system_bin()pandoc_system_bin()
This function allows to run any R code by changing the active pandoc version to use without modifying the R session state.
with_pandoc_version( version, code, rmarkdown = getOption("pandoc.activate_rmarkdown", TRUE) ) local_pandoc_version( version, rmarkdown = getOption("pandoc.activate_rmarkdown", TRUE), .local_envir = parent.frame() )with_pandoc_version( version, code, rmarkdown = getOption("pandoc.activate_rmarkdown", TRUE) ) local_pandoc_version( version, rmarkdown = getOption("pandoc.activate_rmarkdown", TRUE), .local_envir = parent.frame() )
version |
This can be either:
|
code |
Code to execute with the temporary active Pandoc version. |
rmarkdown |
if |
.local_envir |
The environment to use for scoping. |
This is inspired from withr package.
The results of the evaluation of the code argument.
# Run with pandoc without activating the version for rmarkdown::render() with_pandoc_version("system", pandoc_bin(), rmarkdown = FALSE ) with_pandoc_version("2.11.4", rmarkdown::find_pandoc(), rmarkdown = TRUE) local({ local_pandoc_version("2.11.4") pandoc::pandoc_locate() rmarkdown::find_pandoc() }) rmarkdown::find_pandoc()# Run with pandoc without activating the version for rmarkdown::render() with_pandoc_version("system", pandoc_bin(), rmarkdown = FALSE ) with_pandoc_version("2.11.4", rmarkdown::find_pandoc(), rmarkdown = TRUE) local({ local_pandoc_version("2.11.4") pandoc::pandoc_locate() rmarkdown::find_pandoc() }) rmarkdown::find_pandoc()