Skip to content

Save yourself from non-org formats, thanks to pandoc

License

Notifications You must be signed in to change notification settings

declantsien/org-pandoc-import

 
 

Repository files navigation

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

org-pandoc-import.svg

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

screenshots/odt.png

screenshots/markdown.png

screenshots/csv.png

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!

About

Save yourself from non-org formats, thanks to pandoc

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Emacs Lisp 91.3%
  • Lua 8.7%