Collecting images into one directory for self-contained Org mode exports
Published on Jun 17, 2023.
I often embed images into my Org mode documents. Especially attachments via
org-download are convenient while composing notes or drafts.
To share such documents, I usually export them. While HTML export allows to inline
images, this is not an option for e.g. LaTeX (if I want to share the .tex
file) or even Org mode.
To create a self-contained export including images, I have written an Elisp
routine that extracts the file path from a link, copies the target file into a
common directory and returns a modified link to the new location.
The directory can be specified as a relative path, e.g. ./images/, which will
result in relative links in the exported document as well. The exported file can
then be easily compressed together with this directory into a zip file and send
off.
This is the code that defines the variable that configures the output path and the filter function:
(defvar hanno/org-copy-linked-files-export-path "images/" "Sets the directory that linked local files are copied to on export. The directory needs to already exist. Used by `hanno/org-link-filter-copy-images-on-export' as target directory.") (defun hanno/org-copy-linked-files-on-export (text backend _info) "Copy linked files in exports into a common location. Returns modified TEXT with path to the copied file for a given export BACKEND. Supported backends are HTML, LaTeX and Org mode. Intended to be added to `org-export-filter-link-functions'." (let (target source) (cond ((org-export-derived-backend-p backend 'html) (let* ((url (url-unhex-string (car (cl-remove-if (lambda (link) (not (string-match-p "^file:/" link))) (split-string-and-unquote text))))) (filename (file-name-nondirectory (car (url-path-and-query (url-generic-parse-url url)))))) (unless (string-empty-p filename) (setq target (concat (file-name-as-directory hanno/org-copy-linked-files-export-path) filename)) (setq source url) (with-demoted-errors "Copy-files-link-filter error: %S" (url-copy-file url target))))) ((or (org-export-derived-backend-p backend 'latex) (org-export-derived-backend-p backend 'org)) (let ((match (if (org-export-derived-backend-p backend 'latex) "\\includegraphics.*?{\\(.*?\\)}" "\\[\\[file:\\(.*?\\)\\]"))) (when (string-match match text) (setq source (match-string 1 text)) (let* ((filename (file-name-nondirectory source))) (setq target (concat (file-name-as-directory hanno/org-copy-linked-files-export-path) filename)) (with-demoted-errors "Copy-files-link-filter error: %S" (copy-file source target))))))) (when (and source target (file-exists-p target)) (string-replace source target text))))
By adding this function to org-export-filter-link-functions it will be
triggered once for each link when exporting an Org file:
(add-to-list 'org-export-filter-link-functions
'hanno/org-copy-linked-files-on-export)
The filter will handle links such as
[[file:/path/to/some/file]]
and is technically not limited to images but would work with any linked file type.
Note that links with a description result in a \href{...} instead of an
\includegraphics{...} in the LaTeX backend and are ignored by the filter to
avoid affecting external links. Similarly, links without the file: prefix are
not considered in the HTML backend.