summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ikiwiki-transition.mdwn36
-rw-r--r--doc/ikiwiki/directive.mdwn16
-rw-r--r--doc/ikiwiki/pagespec.mdwn19
-rw-r--r--doc/plugins/aggregate.mdwn36
-rw-r--r--doc/plugins/contrib.mdwn2
-rw-r--r--doc/plugins/discussion.mdwn9
-rw-r--r--doc/plugins/embed.mdwn8
-rw-r--r--doc/plugins/googlecalendar.mdwn20
-rw-r--r--doc/plugins/htmlscrubber.mdwn8
-rw-r--r--doc/plugins/lockedit.mdwn2
-rw-r--r--doc/plugins/write.mdwn6
-rw-r--r--doc/plugins/write/tutorial.mdwn2
-rw-r--r--doc/roadmap.mdwn48
-rw-r--r--doc/tips/embedding_content.mdwn35
-rw-r--r--doc/tips/upgrade_to_3.0.mdwn95
-rw-r--r--doc/todo/firm_up_plugin_interface.mdwn2
16 files changed, 214 insertions, 130 deletions
diff --git a/doc/ikiwiki-transition.mdwn b/doc/ikiwiki-transition.mdwn
index 8b7c3579f..18836d5f5 100644
--- a/doc/ikiwiki-transition.mdwn
+++ b/doc/ikiwiki-transition.mdwn
@@ -8,24 +8,23 @@ ikiwiki-transition type ...
# DESCRIPTION
-`ikiwiki-transition` aids in converting wiki pages when
-there's a major change in ikiwiki syntax. It also handles other transitions
-not involving wiki pages.
+`ikiwiki-transition` aids in converting wiki pages when there's a major
+change in ikiwiki syntax. It also handles other transitions not involving
+wiki pages.
-# prefix_directives
+# prefix_directives your.setup
-The `prefix_directives` mode converts the specified ikiwiki page from
-the old preprocessor directive syntax, requiring a space, to the new
-syntax, prefixed by '!'.
+The `prefix_directives` mode converts all pages from the old preprocessor
+directive syntax, requiring a space, to the new syntax, prefixed by '!'.
Preprocessor directives which already use the new syntax will remain
unchanged.
-Note that if the page contains wiki links with spaces, which some
+Note that if a page contains wiki links with spaces, which some
older versions of ikiwiki accepted, the prefix_directives transition will
treat these as preprocessor directives and convert them.
-# setupformat
+# setupformat your.setup
The `setupformat` mode converts a setup file from using a single `wrappers` block
to using `cgi_wrapper`, `git_wrapper`, etc.
@@ -33,25 +32,30 @@ to using `cgi_wrapper`, `git_wrapper`, etc.
Note that all comments and any unusual stuff like perl code in the setup
file will be lost, as it is entirely rewritten by the transition.
-# aggregateinternal
+# aggregateinternal your.setup
The `aggregateinternal` mode moves pages aggregated by the aggregate plugin
so that the `aggregateinternal` option can be enabled.
-# indexdb
+# moveprefs your.setup
+
+Moves values that used to be admin preferences into the setup file.
+
+Note that all comments and any unusual stuff like perl code in the setup
+file will be lost, as it is entirely rewritten by the move.
+
+# indexdb srcdir
The `indexdb` mode handles converting a plain text `.ikiwiki/index` file to
-a binary `.ikiwiki/indexdb`. In this mode, you should specify the srcdir of
-the wiki as the second parameter. You do not normally need to run
+a binary `.ikiwiki/indexdb`. You do not normally need to run
`ikiwiki-transition indexdb`; ikiwiki will automatically run it as
necessary.
-# hashpassword
+# hashpassword srcdir
The `hashpassword` mode forces any plaintext passwords stored in the
`.ikiwiki/userdb` file to be replaced with password hashes. (The
-Authen::Passphrase perl module is needed to do this.) In this mode, you
-should specify the srcdir of the wiki as the second parameter.
+Authen::Passphrase perl module is needed to do this.)
If this is not done explicitly, a user's plaintext password will be
automatically converted to a hash when a user logs in for the first time
diff --git a/doc/ikiwiki/directive.mdwn b/doc/ikiwiki/directive.mdwn
index c4342dee8..fb88aa72d 100644
--- a/doc/ikiwiki/directive.mdwn
+++ b/doc/ikiwiki/directive.mdwn
@@ -28,15 +28,13 @@ of text with triple-quotes:
3. "baz"
"""]]
-ikiwiki also has an older syntax for directives, which requires a
-space in directives to distinguish them from [[wikilinks|ikiwiki/wikilink]].
-This syntax has several disadvantages: it requires a space after directives
-with no parameters (such as `\[[pagecount ]]`), and it prohibits spaces in
-[[wikilinks|ikiwiki/wikilink]]. ikiwiki now provides the `!`-prefixed syntax
-shown above as the preferred alternative. However, ikiwiki still supports
-wikis using the older syntax, if the `prefix_directives` option is not enabled.
-For backward compatibility with existing wikis, this option currently
-defaults to off, so ikiwiki supports the old syntax.
+ikiwiki also has an older syntax for directives, which requires a space in
+directives to distinguish them from [[wikilinks|ikiwiki/wikilink]]. This
+syntax has several disadvantages: it requires a space after directives with
+no parameters (such as `\[[pagecount ]]`), and it prohibits spaces in
+[[wikilinks|ikiwiki/wikilink]]. ikiwiki now provides the `!`-prefixed
+syntax shown above as default. However, ikiwiki still supports wikis using
+the older syntax, if the `prefix_directives` option is disabled.
[[!if test="enabled(listdirectives)" then="""
Here is a list of currently available directives in this wiki:
diff --git a/doc/ikiwiki/pagespec.mdwn b/doc/ikiwiki/pagespec.mdwn
index d4dd265cc..86abe5745 100644
--- a/doc/ikiwiki/pagespec.mdwn
+++ b/doc/ikiwiki/pagespec.mdwn
@@ -72,22 +72,3 @@ filenames of the pages in the wiki, so a pagespec "foo" used on page
"a/b" will not match a page named "a/foo" or "a/b/foo". To match
relative to the directory of the page containing the pagespec, you can
use "./". For example, "./foo" on page "a/b" matches page "a/foo".
-
-## Old syntax
-
-The old PageSpec syntax was called a "GlobList", and worked differently in
-two ways:
-
-1. "and" and "or" were not used; any page matching any item from the list
- matched.
-2. If an item was prefixed with "`!`", then no page matching that item
- matched, even if it matched an earlier list item.
-
-For example, here is the old way to match all pages except for the SandBox
-and Discussion pages:
-
- * !SandBox !*/Discussion
-
-Using this old syntax is still supported. However, the old syntax is
-deprecated and will be removed at some point, and using the new syntax is
-recommended.
diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn
index 6fc87853b..e2efcd83f 100644
--- a/doc/plugins/aggregate.mdwn
+++ b/doc/plugins/aggregate.mdwn
@@ -5,10 +5,6 @@ This plugin allows content from other feeds to be aggregated into the
wiki. To specify feeds to aggregate, use the
[[ikiwiki/directive/aggregate]] [[ikiwiki/directive]].
-New users of aggregate should enable the `aggregateinternal => 1` option in the
-.setup file. If you don't do so, you will need to enable the [[html]] plugin
-as well as aggregate itself, since feed entries will be stored as HTML.
-
The [[meta]] and [[tag]] plugins are also recommended. Either the
[[htmltidy]] or [[htmlbalance]] plugin is suggested, since feeds can easily
contain html problems, some of which these plugins can fix.
@@ -27,37 +23,19 @@ visit is `http://whatever/ikiwiki.cgi?do=aggregate_webtrigger`. Anyone
can visit the url to trigger an aggregation run, but it will only check
each feed if its `updateinterval` has passed.
-## internal pages and `aggregateinternal`
+## aggregated pages
This plugin creates a page for each aggregated item.
If the `aggregateinternal` option is enabled in the setup file (which is
-recommended), aggregated pages are stored in the source directory with a
+the default), aggregated pages are stored in the source directory with a
"._aggregated" extension. These pages cannot be edited by web users, and
do not generate first-class wiki pages. They can still be inlined into a
blog, but you have to use `internal` in [[PageSpecs|IkiWiki/PageSpec]],
like `internal(blog/*)`.
-For backward compatibility, the default is that these pages have the
-".html" extension, and are first-class wiki pages -- each one generates
-a separate HTML page in the output, and they can even be edited.
-
-That turns out to not be ideal for aggregated content, because publishing
-files for each of those pages is a waste of disk space and CPU, and you
-probably don't want to allow them to be edited. So, there is an alternative
-method that can be used (and is recommended), turned on by the
-`aggregateinternal` option in the setup file.
-
-If you are already using aggregate and want to enable `aggregateinternal`,
-you should follow this process:
-
-1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated
- pages -- such as those in inlines. Put "internal()" around globs
- in those PageSpecs. For example, if the PageSpec was `foo/*`, it should
- be changed to `internal(foo/*)`. This has to be done because internal
- pages are not matched by regular globs.
-2. Turn on `aggregateinternal` in the setup file.
-3. Use [[ikiwiki-transition]] to rename all existing aggregated `.html`
- files in the srcdir. The command to run is
- `ikiwiki-transition aggregateinternal $setupfile`,
-4. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`)
+If `aggregateinternal` is disabled, you will need to enable the [[html]]
+plugin as well as aggregate itself, since feed entries will be stored as
+HTML, and as first-class wiki pages -- each one generates
+a separate HTML page in the output, and they can even be edited. This
+option is provided only for backwards compatability.
diff --git a/doc/plugins/contrib.mdwn b/doc/plugins/contrib.mdwn
index 7a28edaba..e22b13f71 100644
--- a/doc/plugins/contrib.mdwn
+++ b/doc/plugins/contrib.mdwn
@@ -2,6 +2,6 @@ Contributed [[plugins]]:
(See [[install]] for installation help.)
-[[!inline pages="plugins/contrib/* !*/Discussion"
+[[!inline pages="plugins/contrib/* and !*/Discussion"
feedpages="created_after(plugins/contrib/navbar)" archive="yes"
rootpage="plugins/contrib" postformtext="Add a new plugin named:" show=0]]
diff --git a/doc/plugins/discussion.mdwn b/doc/plugins/discussion.mdwn
index 70157f1e2..854307a98 100644
--- a/doc/plugins/discussion.mdwn
+++ b/doc/plugins/discussion.mdwn
@@ -34,12 +34,3 @@ Any objections to listing plugins alphabetically rather than by creation date?
>> "recently changed" list with the 10 most recently changed plugins
>> at the top. That would allow what you suggested, but still allow
>> the main list to be alphabetical. -- [[Will]]
-
-How about adding a deprecated tag in order to clean up the plugin list?
-
-> AFAIK it's currently the only one. --[[Joey]]
-
-For instance [[googlecalendar]] is listed as plugin but should probably be removed from Ikiwiki in a future major version (v3?).
-
--- [[AlexandreDupas]]
-
diff --git a/doc/plugins/embed.mdwn b/doc/plugins/embed.mdwn
index 1d43061e0..2baf07da5 100644
--- a/doc/plugins/embed.mdwn
+++ b/doc/plugins/embed.mdwn
@@ -13,6 +13,14 @@ In the examples below, the parts of the html that you can change are denoted
with "XXX"; everything else must appear exactly as shown to be accepted by the
plugin.
+*This plugin is deprecated.* Rather than relying on these complex lists
+of safe content, which constantly fall out of date, you're recommended to
+configure the [[htmlscrubber]] to not scrub some pages, which only trusted
+users can edit. Then you can embed anything from anywhere on those pages.
+See [[tips/embedding_content]] for details and examples.
+This plugin's lists of safe embedded content will not be maintained, and
+the plugin will be removed in a future release.
+
## google maps
Use html like this to embed a map:
diff --git a/doc/plugins/googlecalendar.mdwn b/doc/plugins/googlecalendar.mdwn
deleted file mode 100644
index bca2ae74f..000000000
--- a/doc/plugins/googlecalendar.mdwn
+++ /dev/null
@@ -1,20 +0,0 @@
-[[!template id=plugin name=googlecalendar author="[[Joey]]"]]
-[[!tag type/special-purpose]]
-
-*Note*: This plugin is deprecated. Please switch to the [[embed]] plugin.
-
-This plugin allows embedding a google calendar iframe in the wiki.
-Normally, if the [[htmlscrubber]] is enabled, such iframes are scrubbed out
-of the wiki content since they're not very safe if created by malicious
-users. But some iframes are legitimate, and safe, if you trust the embedded
-content. This plugin is an example of how to deal with this in ikiwiki.
-
-Example use:
-
- \[[!googlecalendar html="""
- <iframe src="http://www.google.com/calendar/embed?src=adkrdken8mupngh13jshlbenoc%40group.calendar.google.com&title=OSEL%20Calendar&chrome=NAVIGATION&bgcolor=%2371d873&height=588" style=" border-width:0 " width="480" frameborder="0" height="588"></iframe>
- """]]
-
-The iframe should be the one provided by google. Note that it's used in a
-way that avoids cross-site scripting attacks, assuming you trust google's
-content.
diff --git a/doc/plugins/htmlscrubber.mdwn b/doc/plugins/htmlscrubber.mdwn
index b9f7e6d22..c59b46e14 100644
--- a/doc/plugins/htmlscrubber.mdwn
+++ b/doc/plugins/htmlscrubber.mdwn
@@ -32,10 +32,10 @@ other HTML-related functionality, such as whether [[meta]] allows
potentially unsafe HTML tags.
The `htmlscrubber_skip` configuration setting can be used to skip scrubbing
-of some pages. Set it to a [[ikiwiki/PageSpec]], such as "!*/Discussion", and pages
-matching that can have all the evil CSS, JavsScript, and unsafe html
-elements you like. One safe way to use this is to use [[lockedit]] to lock
-those pages, so only admins can edit them.
+of some pages. Set it to a [[ikiwiki/PageSpec]], such as "!*/Discussion",
+and pages matching that can have all the evil CSS, JavsScript, and unsafe
+html elements you like. One safe way to use this is to use [[lockedit]] to
+lock those pages, so only admins can edit them.
----
diff --git a/doc/plugins/lockedit.mdwn b/doc/plugins/lockedit.mdwn
index d2e98e07a..c8f64ea47 100644
--- a/doc/plugins/lockedit.mdwn
+++ b/doc/plugins/lockedit.mdwn
@@ -4,7 +4,7 @@
This plugin allows the administrator of a wiki to lock some pages, limiting
who can edit them using the online interface. This doesn't prevent anyone
who can commit to the underlying revision control system from editing the
-pages, however.
+pages, however. (Unless you set up [[tips/untrusted_git_push]].)
The `locked_pages` setting configures what pages are locked. It is a
[[ikiwiki/PageSpec]], so you have lots of control over what kind of pages
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 9b5cf27f7..405876d58 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -19,7 +19,7 @@ that can be fleshed out to make a useful plugin.
`IkiWiki::Plugin::pagecount` is another simple example. All perl plugins
should `use IkiWiki` to import the ikiwiki plugin interface. It's a good
idea to include the version number of the plugin interface that your plugin
-expects: `use IkiWiki 2.00`.
+expects: `use IkiWiki 3.00`.
An external plugin is an executable program. It can be written in any
language. Its interface to ikiwiki is via XML RPC, which it reads from
@@ -431,7 +431,7 @@ describes the plugin as a whole. For example:
To import the ikiwiki plugin interface:
- use IkiWiki '2.00';
+ use IkiWiki '3.00';
This will import several variables and functions into your plugin's
namespace. These variables and functions are the ones most plugins need,
@@ -486,7 +486,7 @@ use the following hashes, using a page name as the key:
destination file.
* `%pagesources` contains the name of the source file for each page.
-Also, the %IkiWiki::version variable contains the version number for the
+Also, the `%IkiWiki::version` variable contains the version number for the
ikiwiki program.
### Library functions
diff --git a/doc/plugins/write/tutorial.mdwn b/doc/plugins/write/tutorial.mdwn
index e1b34b800..5345f71f2 100644
--- a/doc/plugins/write/tutorial.mdwn
+++ b/doc/plugins/write/tutorial.mdwn
@@ -27,7 +27,7 @@ important one is the IkiWiki module.
use warnings;
use strict;
- use IkiWiki 2.00;
+ use IkiWiki 3.00;
Ok, boilerplate is out of the way. Now to add the one function that ikiwiki
expects to find in any module: `import`. The import function is called when
diff --git a/doc/roadmap.mdwn b/doc/roadmap.mdwn
index 9ed5742eb..83c654b5e 100644
--- a/doc/roadmap.mdwn
+++ b/doc/roadmap.mdwn
@@ -7,10 +7,7 @@ This is the roadmap for ikiwiki development.
Released 29 April 2006.
-The 1.x series changed a great deal over the more than 50 releases in its
-lifetime. It is now in maintenance mode, only security issues or really bad
-bugs will be fixed in 1.x going forward. 1.x will stop being supported with
-the release of 3.0.
+The 1.x series is no longer supported.
----
@@ -32,28 +29,43 @@ the release of 3.0.
Released 30 April 2007.
-The 2.x series is expected to undergo continuing development for some time,
-adding improvements and new features, but avoiding changes that break
-backwards compatability.
+The 2.x series is now in maintenance mode. Only security fixes and fixes for
+really bad bugs will be applied going forward.
----
# 3.0
-Version 3.0 will be an opportunity to make significant transitions.
-
-* Default to using `prefix_directives`.
-* Default to using `aggregateinternal`.
-* Remove deprecated prefs form settings for `allowed_attachments` and
- `locked_pages`.
-* Finalise a new version of the plugin API, exporting additional commonly
- used functions from IkiWiki.pm. See [[todo/firm_up_plugin_interface]]
-
-It will include a vast number of new features, bugfixes, and other
-improvements, far too many to list here.
+Version 3.0 is an opportunity to make significant transitions.
+Read [[tips/upgrade_to_3.0]] for the steps you will need to
+follow when upgrading your wiki to this version.
+
+The highlights of the changes in version 3.0 include:
+
+* Blog-style [[plugins/comments]] as an alternative to Discussion pages.
+* Support for uploading [[attachments|plugins/attachment]].
+* Can [[plugins/rename]] and [[plugins/remove]] pages and files via the web.
+* [[Web_based_setup|plugins/websetup]].
+* Many new plugins including [[plugins/htmlbalance]], [[plugins/format]],
+ [[plugins/progress]], [[plugins/color]], [[plugins/autoindex]],
+ [[plugins/cutpaste]], [[plugins/hnb]], [[plugins/creole]], [[plugins/txt]],
+ [[plugins/amazon_s3]], [[plugins/pinger]], [[plugins/pingee]],
+ [[plugins/edittemplate]]
+* The RecentChanges page is compiled statically, not generated from the CGI.
+* Support for additional revision control systems: [[rcs/bzr]],
+ [[rcs/monotone]]
+* Support for [[tips/trusted_git_push]].
+* A new version (3.00) of the plugin API, exporting additional
+ commonly used functions from `IkiWiki.pm`. Nearly everything in ikiwiki is
+ now a plugin, from WikiLinks to page editing, to RecentChanges.
+* Far too many bug fixes, features, and enhancements to list here.
Release is planned for fall^Wlate, 2008.
+The 3.x series is expected to undergo continuing development for some time,
+adding improvements and new features, but avoiding changes that break
+backwards compatability.
+
----
# future goals
diff --git a/doc/tips/embedding_content.mdwn b/doc/tips/embedding_content.mdwn
new file mode 100644
index 000000000..142acd16e
--- /dev/null
+++ b/doc/tips/embedding_content.mdwn
@@ -0,0 +1,35 @@
+Content from sites such as YouTube can be embedded into a web page. Maybe
+you want to do this. But you'll find that the [[plugins/htmlscrubber]]
+doesn't let you. It blocks the tags used to embed such content, because
+they can be abused in many evil ways.
+
+Some plugins have been written to try to work around this problem, by
+whitelisting the html needed to embed things from a few sites like Google
+maps, calendar, videos, and YouTube. The problem with these plugins is that
+they have to be kept up to date to add new sites, and follow changes to the
+html such sites use for embedding.
+
+(Digression: The real problem with the plugins is that they hide the
+underlying trust relationship. If you decide to embed html from a site,
+you'd better trust that site. And if ikiwiki lets you enter such html, it
+needs to trust you.)
+
+The [[plugins/htmlscrubber]] offers a different way around this problem.
+You can configure it to skip scrubbing certian pages, so that content from
+elsewhere can be embedded on those pages. Then use [[plugins/lockedit]]
+to limit who can edit those unscrubbed pages.
+
+For example, suppose your blog is all under `blog/*`, and you want
+only yourself to be able to post there, and you'd like to be able to embed
+youtube videos etc in your blog. Other users can edit some pages in the
+wiki (Discussion pages, say), but not your blog posts. Then you could configure
+ikiwiki as follows:
+
+ htmlscrubber_skip => 'blog/* and !*/Discussion',
+ locked_pages => '!*/Discussion',
+
+More simply, you might want to allow yourself to embed content anywhere
+on the wiki, but scrub content written on Discussion pages:
+
+ htmlscrubber_skip => '!*/Discussion',
+ locked_pages => '!*/Discussion',
diff --git a/doc/tips/upgrade_to_3.0.mdwn b/doc/tips/upgrade_to_3.0.mdwn
new file mode 100644
index 000000000..a9664dfc3
--- /dev/null
+++ b/doc/tips/upgrade_to_3.0.mdwn
@@ -0,0 +1,95 @@
+Version 3.0 of ikiwiki makes some significant changes, which
+you will need to deal with when upgrading from ikiwiki 2.x.
+
+[[!toc ]]
+
+## setup file format change
+
+The layout of the setup file changed in a significant way in version 2.60
+of ikiwiki. If you have not changed yours to the new format, now would be a
+good time to do so. Some new features, like the [[plugins/websetup]]
+interface, need the new format setup file.
+
+You can convert old setup files into the new format by running
+`ikiwiki-transition setupformat your.setup`
+
+# moving settings from Preferences page
+
+The admin preferences page used to have settings for allowed attachments,
+locked pages, and banned users. These three settings have moved to the
+setup file, and will no longer appear on the admin preferences page once
+your wiki is upgraded to 3.0.
+
+You can move these preferences into the setup file by running
+`ikiwiki-transition moveprefs your.setup`
+
+(Make sure you have converted the setup file to the new format first.)
+
+## prefix directives
+
+In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has
+changed, requiring that the directive start with a bang:
+
+ \[[!directive ...]]
+
+If you would like to keep the old syntax, it is still supported, add the
+following to your setup file:
+
+ prefix_directives => 0,
+
+To convert to the new syntax, run
+`ikiwiki-transition prefix_directives your.setup`
+
+(And then commit the changes it makes to pages in your srcdir.)
+
+## GlobLists
+
+In 3.0, the old "GlobList" syntax for [[PageSpecs|ikiwiki/PageSpec]] is no
+longer supported. A GlobList contains multiple term, but does not separate
+them with "and" or "or":
+
+ sandbox !*/Discussion
+
+To convert this to a modern PageSpec, simply add "and" or "or" as
+appropriate between terms:
+
+ sandbox and !*/Discussion
+
+GlobLists have been deprecated for more than two years. If your wiki dates
+to the ikiwiki 1.0 era, you should check it for any that might have lurked
+unnoticed in it since back then. Ikiwiki version 2.72 will print warnings
+about any GlobLists it sees.
+
+## aggregateinternal
+
+If your wiki uses the [[aggregate|plugins/aggregate]] plugin, it will start
+to aggregate feeds to special "internal" pages.
+
+If you don't want this change, you can add the following to your setup
+file:
+
+ aggregateinternal => 0,
+
+Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin:
+
+1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated
+ pages -- such as those in inlines. Put "internal()" around globs
+ in those PageSpecs. For example, if the PageSpec was `foo/*`, it should
+ be changed to `internal(foo/*)`. This has to be done because internal
+ pages are not matched by regular globs.
+2. Use [[ikiwiki-transition]] to rename all existing aggregated `.html`
+ files in the srcdir. The command to run is
+ `ikiwiki-transition aggregateinternal your.setup`,
+3. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`)
+
+## embed / googlecalendar
+
+The googlecalendar plugin has been deprecated for a long time, and is
+removed in 3.0.
+
+The embed plugin is also now deprecated, though not yet removed.
+
+If you use either plugin to embed content from google, youtube, etc,
+into your wiki, you should instead configure the [[plugins/htmlscrubber]]
+to skip sanitising some pages, via the `htmlscrubber_skip` setting.
+See [[embedding_content]] for examples.
diff --git a/doc/todo/firm_up_plugin_interface.mdwn b/doc/todo/firm_up_plugin_interface.mdwn
index c2e190884..c7553f7dd 100644
--- a/doc/todo/firm_up_plugin_interface.mdwn
+++ b/doc/todo/firm_up_plugin_interface.mdwn
@@ -92,3 +92,5 @@ Probably needs to evolve more and be more widely used before being exported.
* %IkiWiki::pagecase (aggregate)
* %IkiWiki::backlinks (pagestats)
+
+[[done]] (until 4.0)..