#+ -*- fill-column:75; coding: utf-8-unix; -*- #+TITLE: Using the new org exporter * Setting up org-mode /Note:/ You'll need a rather current version of the Org mode git master for everything to work. See [[http://orgmode.org/worg/org-faq.html#keeping-current-with-Org-mode-development]] on how to get a current version. See [[http://orgmode.org/worg/dev/org-build-system.html]] for more information about installing Org mode. To use the new exporter the autoloads for it have to be created. If you install Org mode with, e.g. =make= ensure you have something like the following line in your local.mk: #+begin_example ORG_ADD_CONTRIB = org-e-* org-md org-export #+end_example * helper function to save this files code as new-exporter.emacs This is simply a helper function for tangling this file. The helper function is included in the tangled file, so I don't have to C-x C-e it before use. Adjust file names and path for your own use. #+begin_src emacs-lisp (defun roklein/save-dotemacs () "Save my emacs configuration as new-exporter.emacs" (interactive) (let* ((source-directory "~/Documents/org/emacs") (source-filename "newexporter.org") (destination-dir "~/Documents/org/emacs") (destination-filename "new-exporter.emacs")) (org-babel-tangle-file (expand-file-name source-filename source-directory) (expand-file-name destination-filename destination-dir) "emacs-lisp"))) #+end_src * load org specific settings First I'm setting the load-path for org-mode including contrib. Depending on your Org mode setup you don't need to load-path the contrib directory. #+begin_src emacs-lisp ;;; ;;; org-mode and contrib ;;; (setq load-path (cons "~/.emacs.d/org-mode/lisp" load-path)) (setq load-path (cons "~/.emacs.d/org-mode/contrib/lisp" load-path)) (require 'org-install) #+end_src * Initializing the new exporter First I initialize the alist. Note, the alist has a different name than the alist for the old exporter. #+begin_src emacs-lisp (setq org-e-publish-project-alist nil) #+end_src * Configuring a project ** alist entry for the complete project The project is made up from two components, the part publishing the org files (example-html) and the part copying the static files. #+begin_src emacs-lisp (add-to-list 'org-e-publish-project-alist '("example" :components ("example-html" "example-extra"))) #+end_src ** alist-entry for .org-files First I'm configuring setting up the alist entry for html publishing. #+begin_src emacs-lisp (add-to-list 'org-e-publish-project-alist '("example-html" #+end_src The first for items are necessary for any publishing project. They are pretty much the same as for the old exporter. The publishing functions name has changed to =org-e-publish-org-to-html=. The =:base-directory= is where the file to be published are located; =:base-extension= tells the publishing function which files are to be published, =:publishing-directory= is the directory where the exported files are written to, and =:publishing-function= is the function used be the publisher to export the files as determined by the =:base-directory= and =:base-extension=. #+begin_src emacs-lisp :base-directory "~/Documents/org/example" :base-extension "org" :publishing-directory "~/public_html/example.com" :publishing-function org-e-publish-org-to-html #+end_src The publisher can invoke a function each before starting the publishing process and after finishing it. E.g. you can disable the confirmation prompt when evaluating babel code and enable it again after publishing is complete. #+begin_src emacs-lisp :preparation-function example-prepare :completion-function example-complete #+end_src Some information I don't want to have in every .org files header... #+begin_src emacs-lisp :author "John Doe" :email "john.doe@example.com" :language "en" :section-numbers nil #+end_src Some settings for HTML styles and so on. These options look the same like in the old exporter. #+begin_src emacs-lisp :style "" :style-include-default nil :style-include-scripts nil :LaTeX-fragments nil #+end_src The =:html-preamble= variable can be set to one of four settings: - nil :: no preamble is created by the exporter - t :: a default preamble is created - a string :: a custom formatting string. =%t=, =%a=, =%e=, and =%d= are replaced by the title, the author's name, the author's email, or the date, respectively. - a function name :: a function which creates the preamble. The function must return a string. The =:html-postamble= variable can be set to the same four settings. For the string option =%a=, =%e=, =%d=, =%c=, and =%v= can be used to be replaced by the author's name, the author's email, the date, the Org/Emacs- version, or the org-e-html-validation-link, respectively. Other than the old exporter when you want to use a function, as I do here, the function itself must accept one option, a plist containing the export options. #+begin_src emacs-lisp :html-preamble example-preamble :html-postamble example-postamble )) #+end_src ** alist entry for any files simply to be copied This is pretty much the same as above, notice the difference in the base-extension — all the files I want to be copied verbatim — and the publishing-function. I added a recursive option here. While I tend to accumulate the org-files in the case-directory, I usually have extra directories for css files and images. #+begin_src emacs-lisp (add-to-list 'org-e-publish-project-alist '("example-extra" :base-directory "~/Documents/org/example" :publishing-directory "~/public_html/example.com" :base-extension "css\\|pdf\\|png\\|jpg\\|gif\\|ksh\\|sh\\|py" :publishing-function org-e-publish-attachment :recursive t )) #+end_src ** preparation and completion functions Most of this I took from older projects. The important stuff is disabling backup and babel confirmation before publishing and enabling it again after publishing. #+begin_src emacs-lisp ;; prepare environment before publishing and reset it after (defun example-prepare () (setq org-export-html-coding-system 'utf-8) (setq make-backup-files nil) (setq org-export-html-inline-images t) (setq org-export-allow-BIND t) (setq org-confirm-babel-evaluate nil)) (defun example-complete () (setq make-backup-files t) (setq org-confirm-babel-evaluate t)) #+end_src ** HTML preamble and postamble functions Note, the pre- and postamble functions have one argument which contains a plist of the export options (called so by the exporter). I noticed, I used a function from the old exporter, =org-get-file-contents=, so I changed it in the postamble-function to show another way. I'm not using the options argument in this example. #+begin_src emacs-lisp ;; pre- and postamble for html export (defun example-preamble (options) (org-get-file-contents "~/Documents/org/example/html/preamble.html")) (defun example-postamble (options) (with-temp-buffer (insert-file-contents "~/Documents/org/example/html/postamble.html") (buffer-string))) #+end_src * Publishing Press =M-x=, type org-e-publish, press =ENTER=, type the projects name (=TAB= completes, double =TAB= shows the available completions), e/g =example= and press =ENTER=.