Org-publish-meta (org-pm)

By: Ioannis Zannos (zannos [at] gmail [dot] com)

Date: December 2013

Simplify and extend org-publish in Emacs Org-mode.

The project is how in early beta testing phase.

What it is

Org-pm (short for org-publish-meta) is an emacs-lisp package that simplifies and extends the task of defining org-mode publication projects, and permits the copying sections of files to multiple projects. While it can be used for website generation with org-mode’s native publish mechanism, it also supports export of html with YAML headers for the Jekyll and Octopress website generation engines.

Org-mode is an Emacs library “for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system” (http://orgmode.org/).

• For Org-mode see: http://orgmode.org/
• For Org-mode project publishing mechanism see: http://orgmode.org/manual/Publishing.html#Publishing

What it does

Org-pm simplifies the definition of org-mode publishing projects, by coding project publishing options as org-mode sections instead of as emacs-lisp code. It thus virtually eliminates the need to use emacs-lisp code for the definition of projects. Furthermore, project definitions as well as css and scripts can be included in the same org-mode files that hold the text contents to be published.

Org-pm makes it possible to publish a any node (section) of a file to any number of different projects. It saves the contents of org-publish-projects-alist as well as the list of copied sections of files whenever a project is defined or sections of a file are exported. It can also automatically create and add YAML front matter of files for use with Jekyll or Octopress, based on project or section (subtree) properties, or configurations saved in org-mode file sections.

How it works

Org-pm does not require for a file to be placed inside the folder of an Org-mode (publishing) project. Instead, one specifies in a section (node) of a file, the projects to which it belongs through properties or tags.

With a single command, org-pm copies or exports as html the sections of files to the publishing directories of specified projects.

Project definitions (property-lists) are written as nodes (sections) in any org-mode file, using headings as property names and contents as values of the properties. Tags are used to indicate those sections which contain project definitions and also those files and nodes which belong to projects.

Org-pm scans an org-mode file and adds to org-publish-project-alist any projects that this file may contain. It also creates a list of the projects to which the file or any of its sections should be copied into variable org-pm-files. Org-pm automatically saves org-publish-project-alist and org-pm-files to a file for use in further Emacs-sessions.

A minibuffer-menu plus default keyboard shortcuts give access to the commands needed to copy sections to files and publish the relevant projects.

Features

• Use keyboard shortcuts to add or remove a section to/from any project.
• Generate default project automatically and provide project configuration template for further editing.
• Generate project definitions from org-mode style contents of sections.
• Use section headings, tags and properties to define projects and to indicate all necessary properties for copying and publishing.
• Copy any section of a file to any one or more projects.
• Create YAML front matter for Jekyll, Octopress or similar markdown-based publishing schemes, based on properties of a section.
• Include CSS, JavaScript and other script files in the org-mode file as sections. Contents of sections are copied as-they-are. No need to use extra markup or escape characters.
• Automatically save configurations for use in further sessions (no need to manually edit project definitions in emacs-lisp).
• Create org-mode buffer containing list of projects, with links for opening the files that contain those definitions.

Installing, getting started

Place org-pm.el in a folder that is member of the list contained in variable load-path, or add the path where org-pm.el is to the path:

(add-to-list 'load-path "/path/to/org-publish-meta")

Install required package grizzl from online repositories:

(package-install 'grizzl)

Then run this to install org-pm:

(require 'org-pm)

Once org-pm is installed, type H-m H-m to open a menu of commands. (H = Hyper = the function key on Mac). Alternatively run command org-pm-menu.

About the files of this package

file:./org-pm.org

Contains all released code of the package. Org-babel-load-file to compile this file in order to produce an updated version of org-pm.el.

file:./org-pm.el

Contains all released code of the package. Produced by running org-babel-load-file on org-pm.org.

file:./readme.org

This file.

file:./tutorial.org

Essential introduction to using org-pm.

file:./dash.el

Dash.el package by Magnar Sven. Used by org-pm.

file:./REFERENCE.org

Outdated reference draft. For later.

file:./org-pm-extensions.org

Some ideas from early code, for consideration later.

file:./pretty-print.el

Pretty-print package. (currently not used)

file:./roadmap.org

Ideas for future extensions.

file:./org-pm-project-template-jekyll.org

Template for projects that export to Jekyll. Currently set as default.

file:./org-pm-project-template-plain.org

Template for projects that export to html using default org-mode headers. Not tested recently.