The Org to Atom exporter I've preliminary announce some weeks ago entered a state I consider to be stable and consistent enough to be included into Org mode. It provides export, publishing and a sitemap functions that let you create an Atom feed for a web page project based on (multiple) Org mode files. An example that shows the support of inline images in feed entry content can be found [here]. [here]: http://ictsoc.de/code/org-atom/example.atom * Download and installation The Org to Atom exporter is maintained in a copy of Org mode's git repository in branch "org-atom" located at git://github.com/dmj/dmj-org-mode.git You can download the most recent version at [http://github.com/dmj/dmj-org-mode/raw/org-atom/lisp/org-atom.el] To use the exporter you need a recent version of atom-syndication.el, an elisp implementation of the Atom Syndication Format. You can get atom-syndication.el from github, too: git://github.com/dmj/atom-syndication.git * Usage Please see the almost complete documentation below or read via web at [http://ictsoc.de/code/org-atom.html] * Backward incompatibility If you have used an older version of the exporter you need to revise your configuration due to incompatible changes. Most notably: - in-buffer options and publishing properties have be (re)renamed to start with #+FEED and :feed instead of #+ATOM and :atom; - support for the atom:category element is temporarily removed; - some default values have changed: - content is not published by default - names of the atom:updated and atom:published property default to atom_updated and atom_published * Things yet to be done Besides support of even more atom elements (e.g. use tags for the atom:category element), the exporter would require a proper documentation for the Org mode manual, and of course some real-world testing. Thus I'm interested not just in bugs, glitches, inconsistencies, and complains about the exporter but some feedback about the present documentation, too. * Documentation Publish Atom feeds based on Org files ===================================== Date: 2010-06-15 18:49:21 CEST Table of Contents ================= 1 Exporting an Org file to Atom 1.1 In-buffer options 1.2 Headline properties 1.3 Export settings 1.4 Example 2 Publish feeds for a web page project 2.1 Publish a feed for each file in the project 2.2 Publish a combined feed for project files 1 Exporting an Org file to Atom ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An Atom feed consists of a head with feed meta data (e.g. feed title and description) and one or more feed entries. The exporter maps Org mode subtrees to Atom feed entries and requires special in-buffer options with feed as well as headline properties with entry specific meta data. 1.1 In-buffer options ====================== An Atom feed is identified by a globally unique identifier, preferably a UUID. Such an identifier must be present in a Org file supposed to get exported or published to Atom in the =#+FEED_ID= in-buffer option. If you do not use a UUID, the value of this in-buffer option must be a proper IRI, like for example a URL that identifies this particular feed. To be able to properly reference feed entry content and the feed itself[1], at least the URL of the feed must be given by the =#+FEED_URL=. By default Org assumes the published content available in the same place like the feed with the name of the Org file and the extension defined in =org-export-html-extension=. For example a feed for the file =example.org= with the in-buffer option =#+FEED_URL= set to =http://example.tld/feed.atom= is expected to reference content located on the URL =http://example.tld/example.html=. If you indent to use different URLs for the feed and the referenced content, you can set the content URL manually by providing the in-buffer option =#+FEED_CONTENT_URL=. Prospective feed entries are found by using the TAGS/PROP/TODO query specified in the =#+FEED_MAP_ENTRIES= option. If present, the exporter uses the in-buffer options =#+TITLE= and =#+DESCRIPTION= for the feed title and description. If no title is given, the exporter uses the file name. If you want the feed title or description to be different than title and description of the published HTML file, you can use the in-buffer options =#+FEED_TITLE= and =#+FEED_DESCRIPTION=. Atom feeds are required to have an associated author of a feed and its entries. Exporting an Org file to Atom thus always uses the author specified with the =#+AUTHOR= option as the name of the author of a feed. If this option is not present, Org falls back to use whatever the variable =user-full-name= is set to. 1.2 Headline properties ======================== A headline that matches the TAGS/PROP/TODO query for feed entries requires at least two headline properties to be present: The =ID= property with a unique identifier of the headline (preferable a UUID) and a property called =atom_published= containing a time stamp with the date an entry should be considered to be published. If these two properties are not present, they are automatically created using Org's default method to create ID properties[2] and current time and date for the publishing date[3] By default Org just publishes a link to the content of feed entry headlines. If you set the customization variable =org-atom-publish-content=, the whole subtree of a feed entry headline will be published within the feed entry. If you want the Atom entry point to a location different than the published HTML file, you can put the URL in the property =atom_href_alternate=. Additionally you can reference URLs related to the Atom entry by putting them into the property =atom_href_related= and a possible source of the information present in the headline in the property =atom_href_via=. 1.3 Export settings ==================== The =#+FEED_OPTIONS= line is a compact1 form to specify export settings. Here you can: git: turn on/off usage of =git blame= to obtain headline creation date content: turn on/off publishing content 1.4 Example ============ #+TITLE: News about example.tld #+AUTHOR: John Doe #+FEED_ID: f6c537d7-6733-427b-a2d5-a6a14b81a967 #+FEED_URL: http://example.tld/news.atom #+FEED_CONTENT_URL: http://example.tld/news.html #+FEED_MAP_ENTRIES: LEVEL=2+feed Calling =org-export-as-atom= on a file containing these in-buffer options will create an Atom feed with the title "News about example.tld" by the author "John Doe" and all level 2 headlines with the tag "feed" as feed entries. 2 Publish feeds for a web page project ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Atom exporter provides a publishing and a sitemap function to create Atom feeds in a publishing project. While the publishing function creates a feed for each file in the project that contains at least one feed entry headline, the sitemap function combines feed entries of the project files into one single feed. 2.1 Publish a feed for each file in the project ================================================ The function =org-publish-org-to-atom= can be used to create an Atom feed for every file in a publishing project that contains at least one feed entry headline. Files that do not contain feed entry headlines either because =#+FEED_MAP_ENTRIES= does not match or is not present are silently skipped. If the publishing project property =:publishing-url= is set and a file contains feed entries but no =#+FEED_URL= or =#+FEED_CONTENT_URL= in-buffer option, the URLs are automatically derived from this property assuming the files in =:publishing-directory= are published relative to this URL. If the published files have an extension other than "html" you can specify the content file extension by the property =:feed-content-extension=. 2.2 Publish a combined feed for project files ============================================== For publishing a combined feed for all entries in a project Org provides a sitemap function =org-atom-publish-org-as-atom-index=. It iterates over all files in the project, collects prospective feed entries and creates a combined feed in the file specified by =:sitemap-file=. Obviously feed metadata must be supplied in the publishing project: The property =:feed-id= holds the unique identifier for the feed, =:feed-title= the feed's title, and =:publishing-url= the base URL of the published project. I.e. the feed and its entry's content in =:base-directory= are assumed to be relative to this URL. Footnotes: [1] The specifications highly recommend a feed referencing its own location on the web. [2] See customization variable =org-id-method= [3] If you maintain your files in a git repository, you might look at the customization variable =org-atom-try-prepare-headline-git=. If it is non-nil, Org tries to obtain a date for a headline using the =git blame= command.