Allow for serving feeds from a separate domain.

This (indirectly) enables support for FeedBurner. Added docs for
FeedBurner configuration. Clarify how defining the SITEURL attribute
affects URL structure. Closes #177.

docs/settings.rst

@@ -62,10 +62,13 @@ Setting name (default value)                        What does it do?
 `RELATIVE_URLS` (``True``)                          Defines whether Pelican should use relative URLs or
                                                     not.
 `SITENAME` (``'A Pelican Blog'``)                   Your site name
-`SITEURL`                                           Base URL of your website. Note that this is
+`SITEURL`                                           Base URL of your website. Not defined by default,
-                                                    not a way to tell Pelican whether to use relative URLs
+                                                    which means the base URL is assumed to be "/" with a
-                                                    or static ones. You should instead use the
+                                                    root-relative URL structure. If `SITEURL` is specified
-                                                    `RELATIVE_URL` setting for that purpose.
+                                                    explicitly, URLs will be generated with an absolute
+                                                    URL structure (including the domain). If you want to
+                                                    use relative URLs instead of root-relative or absolute
+                                                    URLs, you should instead use the `RELATIVE_URL` setting.
 `STATIC_PATHS` (``['images']``)                     The static paths you want to have accessible
                                                     on the output path "static". By default,
                                                     Pelican will copy the 'images' folder to the
@@ -86,10 +89,10 @@ Setting name (default value)                        What does it do?
 URL Settings
 ------------
 
-You can customize the URL's and locations where files will be saved. The URL's and
+You can customize the URLs and locations where files will be saved. The URLs and
-SAVE_AS variables use python's format strings. These variables allow you to place
+SAVE_AS variables use Python's format strings. These variables allow you to place
-your articles in a location such as '{slug}/index.html' and link to then as
+your articles in a location such as '{slug}/index.html' and link to them as
-'{slug}' for clean urls. These settings give you the flexibility to place your
+'{slug}' for clean URLs. These settings give you the flexibility to place your
 articles and pages anywhere you want.
 
 Note: If you specify a datetime directive, it will be substituted using the
@@ -216,15 +219,26 @@ the ``TAG_FEED`` and ``TAG_FEED_RSS`` settings:
 ================================================    =====================================================
 Setting name (default value)                        What does it do?
 ================================================    =====================================================
-`CATEGORY_FEED` ('feeds/%s.atom.xml'[2]_)           Where to put the category Atom feeds.
+`FEED_DOMAIN` (``None``, i.e. base URL is "/")      The domain prepended to feed URLs. Since feed URLs
-`CATEGORY_FEED_RSS` (``None``, i.e. no RSS)         Where to put the category RSS feeds.
+                                                    should always be absolute, it is highly recommended
+                                                    to define this (e.g., "http://feeds.example.com"). If
+                                                    you have already explicitly defined SITEURL (see
+                                                    above) and want to use the same domain for your
+                                                    feeds, you can just set:  `FEED_DOMAIN = SITEURL`
 `FEED` (``'feeds/all.atom.xml'``)                   Relative URL to output the Atom feed.
 `FEED_RSS` (``None``, i.e. no RSS)                  Relative URL to output the RSS feed.
-`TAG_FEED` (``None``, ie no tag feed)               Relative URL to output the tag Atom feed. It should
+`CATEGORY_FEED` ('feeds/%s.atom.xml'[2]_)           Where to put the category Atom feeds.
+`CATEGORY_FEED_RSS` (``None``, i.e. no RSS)         Where to put the category RSS feeds.
+`TAG_FEED` (``None``, i.e. no tag feed)             Relative URL to output the tag Atom feed. It should
                                                     be defined using a "%s" match in the tag name.
 `TAG_FEED_RSS` (``None``, ie no RSS tag feed)       Relative URL to output the tag RSS feed
 `FEED_MAX_ITEMS`                                    Maximum number of items allowed in a feed. Feed item
                                                     quantity is unrestricted by default.
+`FEED_MAIN_URL` (``'feeds/all.atom.xml'``)          URL appended to domain for the main Atom feed and
+                                                    used to populate its `<link>` in the base template.
+                                                    Useful when you want the feed link to differ from the 
+                                                    filesystem path, such as when using web server
+                                                    aliases/rewrites or FeedBurner (see below).
 ================================================    =====================================================
 
 If you don't want to generate some of these feeds, set ``None`` to the
@@ -232,6 +246,25 @@ variables above.
 
 .. [2] %s is the name of the category.
 
+FeedBurner
+----------
+
+If you want to use FeedBurner for your primary Atom feed, there are two
+primary fields to configure in the `FeedBurner
+<http://feedburner.google.com>`_ interface: "Original Feed" and "Feed Address".
+If using the default Pelican `FEED` attribute and assuming your feeds
+are served from the `www.example.com` domain, you would enter
+`http://www.example.com/feeds/all.atom.xml` in the "Original Feed" field in
+FeedBurner.
+
+For the "Feed Address" field in the FeedBurner interface, you may choose
+whatever suffix you prefer. In your Pelican settings, assign this suffix to
+the `FEED_MAIN_URL` setting. So if your FeedBurner feed address is set to
+`http://feeds.feedburner.com/myblogfeed`, in your Pelican settings you would
+set: `FEED_MAIN_URL = "myblogfeed"`. Then set the `FEED_DOMAIN` setting to
+`http://feeds.feedburner.com`, or `http://feeds.example.com` if you are using
+a CNAME on your own domain (i.e., FeedBurner's "MyBrand" feature).
+
 Pagination
 ==========
 

pelican/settings.py

@@ -18,6 +18,7 @@ _DEFAULT_CONFIG = {'PATH': None,
                    'STATIC_PATHS': ['images', ],
                    'THEME_STATIC_PATHS': ['static', ],
                    'FEED': 'feeds/all.atom.xml',
+                   'FEED_MAIN_URL': 'feeds/all.atom.xml',
                    'CATEGORY_FEED': 'feeds/%s.atom.xml',
                    'TRANSLATION_FEED': 'feeds/all-%s.atom.xml',
                    'FEED_MAX_ITEMS': '',

pelican/themes/notmyidea/static/css/main.css

@@ -26,8 +26,6 @@ body {
     text-align: left;
 }
 
-
-
 /* Headings */
 h1 {font-size: 2em }
 h2 {font-size: 1.571em}	/* 22px */
@@ -304,7 +302,7 @@ img.left, figure.left {float: right; margin: 0 0 2em 2em;}
 		.social a[href*='digg.com'] {background-image: url('../images/icons/digg.png');}
 		.social a[href*='facebook.com'] {background-image: url('../images/icons/facebook.png');}
 		.social a[href*='last.fm'], .social a[href*='lastfm.'] {background-image: url('../images/icons/lastfm.png');}
-		.social a[href*='atom.xml'] {background-image: url('../images/icons/rss.png');}
+		.social a[type$='atom+xml'], .social a[type$='rss+xml'] {background-image: url('../images/icons/rss.png');}
 		.social a[href*='twitter.com'] {background-image: url('../images/icons/twitter.png');}
 		.social a[href*='linkedin.com'] {background-image: url('../images/icons/linkedin.png');}
 

pelican/themes/notmyidea/templates/base.html

@@ -4,9 +4,9 @@
         <title>{% block title %}{{ SITENAME }}{%endblock%}</title>
         <meta charset="utf-8" />
         <link rel="stylesheet" href="{{ SITEURL }}/theme/css/{{ CSS_FILE }}" type="text/css" />
-        <link href="{{ SITEURL }}/{{ FEED }}" type="application/atom+xml" rel="alternate" title="{{ SITENAME }} ATOM Feed" />
+        <link href="{{ FEED_DOMAIN }}/{{ FEED_MAIN_URL }}" type="application/atom+xml" rel="alternate" title="{{ SITENAME }} Atom Feed" />
         {% if FEED_RSS %}
-        <link href="{{ SITEURL }}/{{ FEED_RSS }}" type="application/atom+xml" rel="alternate" title="{{ SITENAME }} RSS Feed" />
+        <link href="{{ FEED_DOMAIN }}/{{ FEED_RSS }}" type="application/rss+xml" rel="alternate" title="{{ SITENAME }} RSS Feed" />
         {% endif %}
 
         <!--[if IE]>
@@ -56,9 +56,9 @@
                 <div class="social">
                         <h2>social</h2>
                         <ul>
-                            <li><a href="{{ SITEURL }}/{{ FEED }}" rel="alternate">atom feed</a></li>
+                            <li><a href="{{ FEED_DOMAIN }}/{{ FEED_MAIN_URL }}" type="application/atom+xml" rel="alternate">atom feed</a></li>
                             {% if FEED_RSS %}
-                            <li><a href="{{ SITEURL }}/{{ FEED_RSS }}" rel="alternate">rss feed</a></li>
+                            <li><a href="{{ FEED_DOMAIN }}/{{ FEED_RSS }}" type="application/rss+xml" rel="alternate">rss feed</a></li>
                             {% endif %}
 
                         {% for name, link in SOCIAL %}

samples/pelican.conf.py

@@ -11,6 +11,7 @@ REVERSE_CATEGORY_ORDER = True
 LOCALE = ""
 DEFAULT_PAGINATION = 4
 
+FEED_DOMAIN = SITEURL
 FEED_RSS = 'feeds/all.rss.xml'
 CATEGORY_FEED_RSS = 'feeds/%s.rss.xml'