117 lines
4.0 KiB
Org Mode
117 lines
4.0 KiB
Org Mode
#+title: Org Pandoc Import
|
|
#+author: tecosaur
|
|
|
|
#+html: <p><img src="https://img.shields.io/badge/Emacs-26.3+-blueviolet.svg?style=flat-square&logo=GNU%20Emacs&logoColor=white">
|
|
#+html: <img src="https://img.shields.io/badge/stage-stable-green?style=flat-square">
|
|
#+html: <img src="https://img.shields.io/badge/-Linux-fcc624?logo=linux&style=flat-square&logoColor=black">
|
|
#+html: <img src="https://img.shields.io/badge/-MacOS-lightgrey?logo=apple&style=flat-square&logoColor=black">
|
|
#+html: <a href="https://liberapay.com/tec"><img src="https://shields.io/badge/support%20my%20efforts-f6c915?logo=Liberapay&style=flat-square&logoColor=black"></a></p>
|
|
|
|
The worst part about =org-mode=? Having to leave it.
|
|
|
|
This package aims to reduce this pain by leveraging [[https://pandoc.org/][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
|
|
|
|
[[file:org-pandoc-import.svg]]
|
|
|
|
* Installation
|
|
** Straight
|
|
#+begin_src elisp
|
|
(use-package org-pandoc-import
|
|
:straight (:host github
|
|
:repo "tecosaur/org-pandoc-import"
|
|
:files ("*.el" "filters" "preprocessors")))
|
|
#+end_src
|
|
** Doom
|
|
#+begin_src elisp
|
|
;; $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)
|
|
#+end_src
|
|
|
|
** 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
|
|
|
|
[[file:screenshots/odt.png]]
|
|
|
|
[[file:screenshots/markdown.png]]
|
|
|
|
[[file: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=
|
|
|
|
Currently /Rmarkdown/ and /TSV/ files require ~sed~ 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=
|
|
|
|
* Adding new backends
|
|
For something supported out of the box by Pandoc, it couldn't be easier ---
|
|
just
|
|
#+begin_src elisp
|
|
(org-pandoc-import-backend foo)
|
|
#+end_src
|
|
|
|
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!
|