• Introduction
• Usage
• 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.

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:

Warning: This package currently only works with exporters that export to a single format. Some exporters (e.g., ox-pandoc) export to many different formats, using their own custom export functions instead of org-export-to-file(), and as a result won't work correctly with org-autoexport. The particular case of ox-pandoc is 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.