Support ordering pages and articles when iterating in templates.

Order can be set to a metadata attribute or a sorting function.
Default to order by slug for articles and order by filename for pages.

docs/settings.rst

@@ -236,6 +236,11 @@ Setting name (default value)                            What does it do?
 ====================================================    =====================================================
 `ARTICLE_URL` (``'{slug}.html'``)                       The URL to refer to an ARTICLE.
 `ARTICLE_SAVE_AS` (``'{slug}.html'``)                   The place where we will save an article.
+`ARTICLE_ORDER_BY` (``'slug'``)                         The metadata attribute used to sort articles. By default
+                                                        the articles_page.object_list template variable is 
+                                                        ordered by slug. If you modify this, make sure all 
+                                                        articles contain the attribute you specify. You can
+                                                        also specify a sorting function.
 `ARTICLE_LANG_URL` (``'{slug}-{lang}.html'``)           The URL to refer to an ARTICLE which doesn't use the
                                                         default language.
 `ARTICLE_LANG_SAVE_AS` (``'{slug}-{lang}.html'``)       The place where we will save an article which
@@ -244,6 +249,13 @@ Setting name (default value)                            What does it do?
 `PAGE_SAVE_AS` (``'pages/{slug}.html'``)                The location we will save the page. This value has to be
                                                         the same as PAGE_URL or you need to use a rewrite in
                                                         your server config.
+`PAGE_ORDER_BY` (``'filename'``)                        The metadata attribute used to sort pages. By default
+                                                        the PAGES template variable is ordered by filename
+                                                        (path not included). Note that the option 'filename' 
+                                                        is a special option supported in the source code. If 
+                                                        you modify this settings, make sure all pages contain 
+                                                        the attribute you specify. You can also specify a 
+                                                        sorting function.
 `PAGE_LANG_URL` (``'pages/{slug}-{lang}.html'``)        The URL we will use to link to a page which doesn't
                                                         use the default language.
 `PAGE_LANG_SAVE_AS` (``'pages/{slug}-{lang}.html'``)    The location we will save the page which doesn't

pelican/generators.py

@@ -409,7 +409,8 @@ class ArticlesGenerator(Generator):
                                (repr(article.status),
                                 repr(f)))
 
-        self.articles, self.translations = process_translations(all_articles)
+        self.articles, self.translations = process_translations(all_articles,
+                order_by=self.settings['ARTICLE_ORDER_BY'])
 
         for article in self.articles:
             # only main articles are listed in categories and tags
@@ -517,7 +518,8 @@ class PagesGenerator(Generator):
                                (repr(page.status),
                                 repr(f)))
 
-        self.pages, self.translations = process_translations(all_pages)
+        self.pages, self.translations = process_translations(all_pages,
+                order_by=self.settings['PAGE_ORDER_BY'])
         self.hidden_pages, self.hidden_translations = (
                 process_translations(hidden_pages))
 

pelican/settings.py

@@ -57,10 +57,12 @@ DEFAULT_CONFIG = {
     'OUTPUT_RETENTION': (),
     'ARTICLE_URL': '{slug}.html',
     'ARTICLE_SAVE_AS': '{slug}.html',
+    'ARTICLE_ORDER_BY': 'slug',
     'ARTICLE_LANG_URL': '{slug}-{lang}.html',
     'ARTICLE_LANG_SAVE_AS': '{slug}-{lang}.html',
     'PAGE_URL': 'pages/{slug}.html',
     'PAGE_SAVE_AS': os.path.join('pages', '{slug}.html'),
+    'PAGE_ORDER_BY': 'filename',
     'PAGE_LANG_URL': 'pages/{slug}-{lang}.html',
     'PAGE_LANG_SAVE_AS': os.path.join('pages', '{slug}-{lang}.html'),
     'STATIC_URL': '{path}',

pelican/utils.py

@@ -430,7 +430,7 @@ def truncate_html_words(s, num, end_text='...'):
     return out
 
 
-def process_translations(content_list):
+def process_translations(content_list, order_by=None):
     """ Finds translation and returns them.
 
     Returns a tuple with two lists (index, translations).  Index list includes
@@ -440,6 +440,14 @@ def process_translations(content_list):
     the same slug have that metadata.
 
     For each content_list item, sets the 'translations' attribute.
+
+    order_by can be a string of an attribute or sorting function. If order_by
+    is defined, content will be ordered by that attribute or sorting function.
+    By default, content is ordered by slug.
+
+    Different content types can have default order_by attributes defined
+    in settings, e.g. PAGES_ORDER_BY='sort-order', in which case `sort-order`
+    should be a defined metadata attribute in each page.
     """
     content_list.sort(key=attrgetter('slug'))
     grouped_by_slugs = groupby(content_list, attrgetter('slug'))
@@ -485,6 +493,22 @@ def process_translations(content_list):
         translations.extend([x for x in items if x not in default_lang_items])
         for a in items:
             a.translations = [x for x in items if x != a]
+
+    if order_by:
+        if hasattr(order_by, '__call__'):
+            try:
+                index.sort(key=order_by)
+            except:
+                if hasattr(order_by, 'func_name'):
+                    logger.error("Error sorting with function %s" % order_by.func_name)
+                else:
+                    logger.error("Error sorting with function %r" % order_by)
+        elif order_by == 'filename':
+            index.sort(key=lambda x:os.path.basename(
+                    x.source_path or ''))
+        elif order_by != 'slug':
+            index.sort(key=attrgetter(order_by))
+
     return index, translations