From: Joey Hess Date: Sun, 11 Oct 2009 20:42:49 +0000 (-0400) Subject: ikiwiki-calendar: New command automates creation of archive pages using the calendar... X-Git-Url: https://scripts.mit.edu/gitweb/www/ikiwiki.git/commitdiff_plain/e1939185d29e1431861e63d6526cb3a498d6033e ikiwiki-calendar: New command automates creation of archive pages using the calendar plugin. --- diff --git a/debian/changelog b/debian/changelog index a79faf7fb..22935955a 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,10 @@ +ikiwiki (3.20091010) UNRELEASED; urgency=low + + * ikiwiki-calendar: New command automates creation of archive pages + using the calendar plugin. + + -- Joey Hess Sun, 11 Oct 2009 15:54:45 -0400 + ikiwiki (3.20091009) unstable; urgency=low * parentlinks: Add has_parentlinks template parameter to allow styling diff --git a/doc/examples/blog.mdwn b/doc/examples/blog.mdwn index 2155d7fea..f542cad0c 100644 --- a/doc/examples/blog.mdwn +++ b/doc/examples/blog.mdwn @@ -23,3 +23,7 @@ Some additional configuration you might want to do: enable comments to posts to the blog: comments_pagespec => 'blog/posts/* and !*/Discussion', + +* Enable the [[calendar|plugins/calendar]] plugin and run the + [[ikiwiki-calendar]] command from cron daily to get an interlinked + set of calendar archives. diff --git a/doc/ikiwiki-calendar.mdwn b/doc/ikiwiki-calendar.mdwn new file mode 100644 index 000000000..e2cc612f3 --- /dev/null +++ b/doc/ikiwiki-calendar.mdwn @@ -0,0 +1,51 @@ +# NAME + +ikiwiki-calendar - create calendar archive pages + +# SYNOPSIS + +ikiwiki-calendar [-f] your.setup [pagespec] [year] + +# DESCRIPTION + +`ikiwiki-calendar` creates pages that use the [[ikiwiki/directive/calendar]] +directive, allowing the archives to be browsed one month +at a time, with calendar-based navigation. + +You must specify the setup file for your wiki. The pages will +be created inside its `srcdir`, beneath the `archivebase` +directory used by the calendar plugin (default "archives"). + +You will probably want to specify a [[ikiwiki/PageSpec]] +to control which pages are included on the calendars. The +default is all pages. To limit it to only posts in a blog, +use something like "posts/* and !*/Discussion". + +It defaults to creating calendar pages for the current +year, as well as the previous year, and the next year. +If you specify a year, it will create pages for that year. + +Existing pages will not be overwritten by this command by default. +Use the `-f` switch to force it to overwrite any existing pages. + +## CRONTAB + +While this command only needs to be run once a year to update +the archive pages for each new year, you are recommended to set up +a cron job to run it daily, at midnight. Then it will also update +the calendars to highlight the current day. + +An example crontab: + + 0 0 * * * ikiwiki-calendar ~/ikiwiki.setup "posts/* and !*/Discussion" + +# TEMPLATES + +This command uses two [[template|wikitemplates]] to generate +the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`. + +# AUTHOR + +Joey Hess + +Warning: this page is automatically made into ikiwiki-calendar's man page, edit with care diff --git a/doc/ikiwiki/directive/calendar.mdwn b/doc/ikiwiki/directive/calendar.mdwn index 8a257d6eb..b2ac75b11 100644 --- a/doc/ikiwiki/directive/calendar.mdwn +++ b/doc/ikiwiki/directive/calendar.mdwn @@ -1,5 +1,4 @@ The `calendar` directive is supplied by the [[!iki plugins/calendar desc=calendar]] plugin. -This plugin requires extra setup. See the plugin documentation for details. This directive displays a calendar, similar to the typical calendars shown on some blogs. @@ -12,16 +11,28 @@ some blogs. \[[!calendar type="year" year="2005" pages="blog/* and !*/Discussion"]] +## setup + The calendar is essentially a fancy front end to archives of previous pages, usually used for blogs. It can produce a calendar for a given month, -or a list of months for a given year. - -The month format calendar simply links to any page posted on each -day of the month. The year format calendar links to archive pages, with -names like `archives/2007` (for all of 2007) and `archives/2007/01` -(for January, 2007). For this to work, you'll need to create these archive -pages. They typically use [[inline]] to display or list pages created in -the given time frame. +or a list of months for a given year. The month format calendar simply +links to any page posted on each day of the month. The year format calendar +links to archive pages, with names like `archives/2007` (for all of 2007) +and `archives/2007/01` (for January, 2007). + +While you can insert calendar directives anywhere on your wiki, including +in the sidebar, you'll also need to create these archive pages. They +typically use this directive to display a calendar, and also use [[inline]] +to display or list pages created in the given time frame. + +The `ikiwiki-calendar` command can be used to automatically generate the +archive pages. It also refreshes the wiki, updating the calendars to +highlight the current day. This command is typically run at midnight from +cron. An example crontab: + +An example crontab: + + 0 0 * * * ikiwiki-calendar ~/ikiwiki.setup "posts/* and !*/Discussion" ## usage diff --git a/doc/plugins/calendar.mdwn b/doc/plugins/calendar.mdwn index 8ade70004..bc1bc6c71 100644 --- a/doc/plugins/calendar.mdwn +++ b/doc/plugins/calendar.mdwn @@ -3,13 +3,9 @@ This plugin provides a [[ikiwiki/directive/calendar]] [[ikiwiki/directive]]. The directive displays a calendar, similar to the typical calendars shown on -some blogs. +some blogs. -Since ikiwiki is a wiki compiler, to keep the calendar up-to-date, -wikis that include it need to be periodically refreshed, typically by cron -at midnight. Example crontab: - - 0 0 * * * ikiwiki -setup ~/ikiwiki.setup -refresh +The [[ikiwiki-calendar]] command is used to keep the calendar up-to-date. ## CSS diff --git a/ikiwiki-calendar b/ikiwiki-calendar new file mode 100755 index 000000000..ec572cb7c --- /dev/null +++ b/ikiwiki-calendar @@ -0,0 +1,59 @@ +#!/usr/bin/perl +use warnings; +use strict; +use IkiWiki; +use IkiWiki::Setup; +use Getopt::Long; + +sub usage () { + die gettext("usage: ikiwiki-calendar [-f] your.setup [pagespec] [year]"), "\n"; +} + +my $force=0; +GetOptions( + "force" => \$force, +) || usage(); +my $setup=shift || usage(); +my $pagespec=shift || "*"; +my $year=shift || 1900+(localtime(time))[5]; + +%config=IkiWiki::defaultconfig(); +IkiWiki::Setup::load($setup); +IkiWiki::loadplugins(); +IkiWiki::checkconfig(); + +my $archivebase = 'archives'; +$archivebase = $config{archivebase} if defined $config{archivebase}; + +sub writearchive ($$;$) { + my $template=template(shift); + my $year=shift; + my $month=shift; + + my $page=defined $month ? "$year/$month" : $year; + + my $pagefile=newpagefile("$archivebase/$page", $config{default_pageext}); + $template->param(pagespec => $pagespec); + $template->param(year => $year); + $template->param(month => $month) if defined $month; + + if ($force || ! -e "$config{srcdir}/$pagefile") { + writefile($pagefile, $config{srcdir}, $template->output); + IkiWiki::rcs_add($pagefile) if $config{rcs}; + } +} + +IkiWiki::lockwiki(); + +foreach my $y ($year-1, $year, $year+1) { + writearchive("calendaryear.tmpl", $y); + foreach my $m (qw{01 02 03 04 05 06 07 08 09 10 11 12}) { + writearchive("calendarmonth.tmpl", $y, $m); + } +} + +IkiWiki::rcs_commit_staged(gettext("calendar update"), undef, undef) + if $config{rcs}; +IkiWiki::unlockwiki(); + +system("ikiwiki", "-setup", $setup, "-refresh"); diff --git a/templates/calendarmonth.tmpl b/templates/calendarmonth.tmpl new file mode 100644 index 000000000..37ad78c5c --- /dev/null +++ b/templates/calendarmonth.tmpl @@ -0,0 +1,3 @@ +[[!calendar type=month month= year= pages=""]] + +[[!inline pages="creation_month() and creation_year() and " show=0 feeds=no reverse=yes]] diff --git a/templates/calendaryear.tmpl b/templates/calendaryear.tmpl new file mode 100644 index 000000000..714bd6d47 --- /dev/null +++ b/templates/calendaryear.tmpl @@ -0,0 +1 @@ +[[!calendar type=year year= pages=""]]