3 files changed, 45 insertions, 0 deletions
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 3ed0a3017..1cb26a076 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -313,6 +313,20 @@ A plugin can access the wiki's configuration via the `%config`
 hash. The best way to understand the contents of the hash is to look at
 [[ikiwiki.setup]], which sets the hash content to configure the wiki.
 
+### %pagestate
+
+The `%pagestate` hash can be used by plugins to save state that they will need
+next time ikiwiki is run. The hash holds per-page state, so to set a value,
+use `%pagestate{$page}{$id}{$key}=$value`, and to retrieve the value,
+use `%pagestate{$page}{$id}{$key}`.
+
+`$key` can be any string you like, but `$id` must be the same as the "id"
+parameter passed to `hook()` when registering the plugin. This is so
+ikiwiki can know when to delete pagestate for plugins that are no longer
+used.
+
+When pages are deleted, ikiwiki automatically deletes their pagestate too.
+
 ### Other variables
 
 If your plugin needs to access data about other pages in the wiki. It can
diff --git a/doc/plugins/write/external.mdwn b/doc/plugins/write/external.mdwn
index 0abc9b0a0..a1a3811dc 100644
--- a/doc/plugins/write/external.mdwn
+++ b/doc/plugins/write/external.mdwn
@@ -49,6 +49,11 @@ to access any such global hash. To get the "url" configuration value,
 call `getvar("config", "url")`. To set it, call 
 `setvar("config", "url", "http://example.com/)`.
 
+The `%pagestate` is a special hash with a more complex format. To access
+it, external plugins can use the `getstate` and `setstate` RPCs. To access
+stored state, call `getstate("page", "id", "key")`, and to store state,
+call `setstate("page", "id", "key", "value")`.
+
 ## Notes on function parameters
 
 The [[plugin_interface_documentation|write]] talks about functions that take
diff --git a/doc/todo/plugin_data_storage.mdwn b/doc/todo/plugin_data_storage.mdwn
index 7078a6ed3..21e925b5b 100644
--- a/doc/todo/plugin_data_storage.mdwn
+++ b/doc/todo/plugin_data_storage.mdwn
@@ -66,3 +66,29 @@ which pages have a calendar for the current time. Then ensure they are
 rebuilt at least once a day. Currently, it needs a cron job to rebuild
 the *whole* wiki every day; with this enhancement, the cron job would only
 rebuild the few pages that really need it.
+
+
+--- 
+
+New design:
+
+`%Ikiwiki::state` is an exported hash that stores per-page state.
+Set with `$state{$page}{id}{key}=$value`. The `id` is the same `id` passed
+to `hook()`.
+
+This is stored in the index like:
+
+src=foo.mdwn dest=bar.mdwn id_key=value [...]
+
+The underscore ensures that there's no conflict with ikiwiki's own
+state variables. (Note that `id` and `key` need to be encoded here.)
+
+Plugins are reponsible for deleting old state info, though ikiwiki will
+handle deleting it if a page is removed.
+
+Ikiwiki needs to know when it can drop state for plugins that are no longer
+enabled. This is done via `hook()` -- if a plugin registers a hook
+ikiwiki knows it's still active, and preserves the state for the hook id.
+If not, that state will be dropped.
+
+[[done]]!! Now to use it..