Allow sorting to be combined and/or reversed

2 files changed, 20 insertions, 1 deletions

diff --git a/doc/ikiwiki/pagespec/sorting.mdwn b/doc/ikiwiki/pagespec/sorting.mdwn
index 61516bec5..f27972d4e 100644
--- a/doc/ikiwiki/pagespec/sorting.mdwn
+++ b/doc/ikiwiki/pagespec/sorting.mdwn
@@ -15,6 +15,10 @@ orders can be specified.
   full title was set.
 """]]
 
+In addition, you can combine several sort orders and/or reverse the order of
+sorting, with a string like `age -title` (which would sort by age, then by
+title in reverse order if two pages have the same age).
+
 Plugins can add additional sort orders, so more might be available on this
 wiki.
 
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index bfa6617bd..1010e76e4 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -593,7 +593,9 @@ function of the ikiwiki wrapper when it is being generated.
 	hook(type => "sort", id => "foo", call => \&sort_by_foo);
 
 This hook adds an additional [[ikiwiki/pagespec/sorting]] order or overrides
-an existing one. The callback is given two page names as arguments, and
+an existing one.
+
+The callback is given two page names followed by the parameter as arguments, and
 returns negative, zero or positive if the first page should come before,
 close to (i.e. undefined order), or after the second page.
 
@@ -603,6 +605,19 @@ For instance, the built-in `title` sort order could be reimplemented as
 		pagetitle(basename($_[0])) cmp pagetitle(basename($_[1]));
 	}
 
+and to sort by an arbitrary `meta` value, you could use:
+
+	# usage: sort="meta(description)"
+	sub sort_by_meta {
+		my $param = $_[2];
+		error "sort=meta requires a parameter" unless defined $param;
+		my $left = $pagestate{$_[0]}{meta}{$param};
+		$left = "" unless defined $left;
+		my $right = $pagestate{$_[1]}{meta}{$param};
+		$right = "" unless defined $right;
+		return $left cmp $right;
+	}
+
 ## Exported variables
 
 Several variables are exported to your plugin when you `use IkiWiki;`