• Introduction
• Usage
• Pandoc
• Installation
• Contributing
• License

#Introduction

This emacs package allows you to synchronize exported versions of your org files, by auto-exporting them every time you save.

My original reason for writing it was because I prefer to write docs in org mode, but some forge sites don't support org mode as a format for their README files (looking at you, sourcehut) and insist on Markdown. But I don't want to have to remember to export after each change.

This being emacs, there are several ways to do it. One is simply to add a local after-save-hook function (here's one that auto-exports to github-flavoured Markdown on save):

# Local Variables:
# eval: (add-hook 'after-save-hook #'org-gfm-export-to-markdown nil 'local)
# End:

This works, but I find it ugly. It means copy-pasting hard-to-remember code at the end of each org file, instead of declaring the export in the same way as other org declarations. More seriously, it doesn't take narrowing or the active region into account: if the file is saved while its buffer is narrowed, or a region is active, only that part of the buffer will be exported.

Instead I want to be able to do something similar to what the org-auto-tangle package does for tangling, and be able to say:

#+auto_export: gfm

That way, I can have the auto-export control for a bunch of org files as part of a common setup file declared by #+setupfile:, so I don't have to repeat myself.

#Usage

The package defines a minor mode called org-autoexport-mode, which (if enabled) will try to export to other formats after saving the current org file. It will perform one export for each #+auto_export: option it finds. You can also invoke the export process interactively, via the org-autoexport-do-export() function. For example, this declaration would export to markdown and HTML:

#+auto_export: md
#+auto_export: html

By default the exported filename is based on the org filename. You can use the EXPORT_FILE_NAME file property to override this.

Auto-export will fail if the requested export backend can't be found, and you'll get a popup warning buffer to that effect. In that case you will need to install and load the export backend first (for example, to get the gfm export mentioned above, you will need to load the ox-gfm package).

If want to suppress export for particular files (e.g., files included in other files via #+setupfile:) you can turn autoexport mode off for those files via local variables:

# Local Variables:
# org-autoexport-mode: nil
# End:

#Pandoc

The ox-pandoc exporter is a special case in that it uses pandoc to export to many different formats, so there is not one single export backend. Instead, that package has a dedicated export function for each format.

To auto-export using the pandoc exporter you need to indicate which export format to use, with a second argument on the #+auto_export: line. The general form is #+auto_export: EXPORTER FORMAT. For example, to export to RTF using pandoc you would say:

#+auto_export: pandoc rtf

In this case, instead of the standard backend mechanism, auto-export will look for an elisp function called org-pandoc-export-to-rtf.

To find the complete list of formats available with pandoc, type:

C-h a org-pandoc-export-to-

The style of export done by pandoc is controlled by the variable org-autoexport-function-template-map. You can add support for more special-case exporters by adding to this list if their export function names can be captured by a standard template. (I don't know of any at the moment apart from pandoc, but you never know what the future holds.)

The particular case of ox-pandoc is also supported by another package: org-auto-export-pandoc.

#Installation

Simply require the package in your emacs init file and hook it into org mode:

(require 'org-autoexport)
(add-hook 'org-mode-hook 'org-autoexport-mode)

Alternatively, you can install from MELPA via use-package:

(use-package org-autoexport
  :defer t
  :hook (org-mode . org-autoexport-mode))

Autoexport mode adds an AutoExp indicator to the mode line to show that it's active. You can change or suppress that using the diminish option of use-package.

#Contributing

You can find the source repo on sourcehut. Report any problems or suggestions here, or you can email me directly at zondo42@gmail.com.

#License

This package is licensed under the the 2-Clause BSD License.