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.
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
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.
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.
- 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.
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
.
- 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.