org-publish-workbook
org-export can easily generate multiple versions of the same org data; an org-publish-workbook binds an export backend with an org-publish project, to help with the process of iteratively customizing output.
A workbook consists of an entry in org-publish-workbook-alist, a set of entries in org-publish-project-alist and an org-export-derived-backend.
example setup
The initial outline of publishing this project's README.md consisted of the following setup.
(org-publish-workbook-add
'documentation
'(md ;; workbook derived from markdown exporter (ox-md.el)
:filters-alist ;; word wrap paragraphs, with hyphens
((:filter-paragraph (lambda (content backend info)
(with-temp-buffer
(insert content)
(modify-category-entry ?- ?|)
(set-fill-column 60)
(fill-region (point-min) (point-max) 'full t nil)
(buffer-string)))))
:exclude ".*"
:base-extension ".md"))
(org-publish-workbook-add-project
'documentation
'("org-publish-workbook"
:base-directory "~/workbook/lib"
:include ["org-publish-workbook.org"]
:publishing-directory "~/workbook/lib/org-publish-workbook"
:decorators ((:before-processing
(lambda () ;; insert title as md export is body only
(org-map-entries (lambda () (org-demote-subtree)) "LEVEL=1")
(org-insert-heading)
(insert "org-publish-workbook"))))))
creating a workbook
Workbooks are initialized with org-publish-workbook-add. This function adds an entry to org-publish-workbook-alist, based on the first argument, label.
The second argument, backend, can be either a symbol, or a list starting with a symbol and an alist of options. The symbol should reference an org-export backend; the provided options are used to create an org-export-derived-backend.
Publish project specific options :base-directory, :base-extension, :exclude, :publishing-directory, :template and :template-directory can be also be specified, to set the workbook's projects' default values.
The rest of the arguments are used to create projects with org-publish-workbook-add-project.
org-export backend
Each workbook creates a reusable (further extendable) derived backend based on the original exporter, for use with all of it's projects. For a list of options and settings, please see the doc string of org-export-define-derived-backend.
org-publish projects
When a project is added to a workbook, it is added to org-publish-project-alist labelled as [workbook-project].
When not set directly, options default to values set in each respective workbook, or their equivalent environment variables; root-directory is set to the Emacs server's initial working directory.
- :template-directory; .etc/export-template
- :output-directory; .var
Commonly used options are :include, :exclude and :recursive - the custom properties :template and :decorate create export hooks through output decorators.
output decorators
By adding decorators to a publishing project's export pipeline, the :final-output, or the contents of each buffer :before-processing, can be directly edited.
When editing the :final-output, the function supplied to workbook-decorate is called with contents and optional args. The function's output becomes the result of this export action.
:before-processing hooks are expanded within the context of each current-buffer, allowing for direct editing.
Each hook is activated during a project's :preparation-function, and deactivated in it's :completion-function.
template decorator
When a project's :template property is set, by default, a hook is run during publishing to insert or update the current buffer's #+SETUPFILE property before any processing takes place.
Alternately, the insert-template-fn variable can be updated to specify a function which will be called with the resolved path of the project's template file.
rendering
The org-publish-workbook-render function publishes a workbook's projects. Optional arguments are force, async and projects - to publish only the ones specified.
tests
emacs -batch \
-l ert \
-l org-publish-workbook-tests.el \
-f ert-run-tests-batch-and-exit