Org Pandoc Import

The worst part about org-mode? Having to leave it.

This package aims to reduce this pain by leveraging Pandoc to convert selected file types to org.

There are two tiers of non-org file avoidance:

1. The basic “get me out of here” — org-pandoc-import-{to,as}-org allows you to easily convert supported non-org files to an org file/buffer with Pandoc
2. “I don’t even want to see non-org files” — org-pandoc-import-transient-mode is for you
   • (via file handlers) intercepts requests for non-org files it knows it can convert
   • uses org-pandoc-import-to-org to convert the file to a temporary org file
   • opens this org file instead
   • exports back to the original non-org file on save

Installation

Straight

(use-package org-pandoc-import
  :straight (:host github
             :repo "tecosaur/org-pandoc-import"
             :files ("*.el" "filters" "preprocessors")))

Doom

;; $DOOMDIR/packages.el
(package! org-pandoc-import
  :recipe (:host github
           :repo "tecosaur/org-pandoc-import"
           :files ("*.el" "filters" "preprocessors")))

;; $DOOMDIR/config.el
(use-package! org-pandoc-import :after org)

Dependences

• Pandoc

That’s the only hard dependency. However ox-pandoc and ox-gfm can be useful for exporting with org-pandoc-import-transient-mode.

That said, as they are currently implemented, the pre-processors for Rmarkdown and TSV files use sed (only really affects Windows users).

Screenshots

Default backends

markdown

associated with: .md, .markdown

LaTeX

associated with: .tex, .latex

reStructuredText

(rst) associated with: .rst

ODT

associated with: .odt

DOCX

associated with: .docx

Jupyter Notebooks

(ipynb) associated with: .ipynb

Rmarkdown

(markdown) associated with: .Rmd, .rmd

CSV

associated with: .csv

TSV

(csv) associated with: .tsv

AsciiDoc

(docbook) associated with: .adoc, .asciidoc

Currently

• Rmarkdown and TSV files require sed
• AsciiDoc requires ~asciidoctor~

in order to pre-process the file for Pandoc.

Default transient-mode backends

Please note that this mode is off by default. It is however a global mode, so enable it once in your config and it will be active everywhere.

The active transient backends are determined by org-pandoc-import-transient-associations.

markdown

using Org’s gfm export if available, otherwise md

ODT

using Org’s odt export

csv, tsv

using org-table-export

When ox-pandoc is available, the following formats are also enabled by default, and use ox-pandoc to export.

• rst
• docx

txt

using ~~org-pandoc-export-to-asciidoc~

Adding new backends

For something supported out of the box by Pandoc, it couldn’t be easier — just

(org-pandoc-import-backend foo)

This will add foo to org-pandoc-import-backends, and create the following functions

• org-pandoc-import-foo-as-org
• org-pandoc-import-foo-to-org

Which will reference these variables,

• org-pandoc-import-foo-args
• org-pandoc-import-foo-filters
• org-pandoc-import-foo-preprocessors
• org-pandoc-import-foo-extensions

That last variable will be set to ("foo"), and will cause org-pandoc-import-{to,as}-org to automatically select this backend when called on .foo files.

These all have docstrings — check them out!