text blocks, for easy nesting of quotes inside.
* Add a template plugin.
* Use the template plugin to add infoboxes to each plugin page listing basic
info about the plugin.
--- /dev/null
+#!/usr/bin/perl
+# Structured template plugin.
+package IkiWiki::Plugin::template;
+
+use warnings;
+use strict;
+use IkiWiki;
+use HTML::Template;
+use Encode;
+
+sub import { #{{{
+ IkiWiki::hook(type => "preprocess", id => "template",
+ call => \&preprocess);
+} # }}}
+
+sub preprocess (@) { #{{{
+ my %params=@_;
+
+ if (! exists $params{id}) {
+ return "[[template missing id parameter]]"
+ }
+
+ my $template_page="templates/$params{id}";
+ IkiWiki::add_depends($params{page}, $template_page);
+
+ my $template_file=$IkiWiki::pagesources{$template_page};
+ return "[[template ".
+ IkiWiki::htmllink($params{page}, $params{destpage}, $template_page).
+ " not found]]"
+ unless defined $template_file;
+
+ my $template=HTML::Template->new(
+ filter => sub {
+ my $text_ref = shift;
+ $$text_ref=&Encode::decode_utf8($$text_ref);
+ },
+ filename => IkiWiki::srcfile($template_file),
+ die_on_bad_params => 0,
+ no_includes => 1,
+ blind_cache => 1,
+ );
+
+ foreach my $param (keys %params) {
+ $template->param($param => $params{$param});
+ }
+
+
+ return IkiWiki::preprocess($params{page}, $params{destpage},
+ $template->output);
+} # }}}
+
+1
# Note: preserve order of params, some plugins may
# consider it significant.
my @params;
- while ($params =~ /(?:(\w+)=)?(?:"([^"]+)"|(\S+))(?:\s+|$)/g) {
+ while ($params =~ /(?:(\w+)=)?(?:"""(.+)"""|"([^"]+)"|(\S+))(?:\s+|$)/g) {
if (defined $1) {
- push @params, $1, (defined $2 ? $2 : $3);
+ push @params, $1, (defined $2 ? $2 : (defined $3 ? $3 : $4));
}
else {
- push @params, (defined $2 ? $2 : $3), '';
+ push @params, (defined $2 ? $2 : (defined $3 ? $3 : $4)), '';
}
}
return $hooks{preprocess}{$command}{call}->(
}
};
- $content =~ s{(\\?)\[\[(\w+)\s+((?:(?:\w+=)?(?:"[^"]+"|[^\s\]]+)\s*)*)\]\]}{$handle->($1, $2, $3)}eg;
+ $content =~ s{(\\?)\[\[(\w+)\s+((?:(?:\w+=)?(?:""".+"""|"[^"]+"|[^\s\]]+)\s*)*)\]\]}{$handle->($1, $2, $3)}eg;
return $content;
} #}}}
--plugin=brokenlinks --plugin=pagecount \
--plugin=orphans --plugin=haiku --plugin=meta \
--plugin=tag --plugin=polygen --plugin=pagestats \
- --plugin=fortune --plugin=aggregate --plugin=map
+ --plugin=fortune --plugin=aggregate --plugin=map \
+ --plugin=template
./mdwn2man ikiwiki 1 doc/usage.mdwn > ikiwiki.man
./mdwn2man ikiwiki-mass-rebuild 8 doc/ikiwiki-mass-rebuild.mdwn > ikiwiki-mass-rebuild.man
\[[pagecount ]]
-A preprocessor directive does not need to all be on one line. Also,
-multiple lines of *quoted* text can be used for a value. Examples:
-
+A preprocessor directive does not need to all be on one line, it can be
+wrapped to multiple lines if you like:
+
\[[directive foo="baldersnatch"
bar="supercalifragalisticexpealadocious" baz=11]]
- \[[directive text="
- 1. foo
- 2. bar
- 3. baz
- more lines
- "]]
+Also, multiple lines of *quoted* text can be used for a value.
+To allow quote marks inside the quoted text, delimit the block
+of text with triple-quotes:
+
+ \[[directive text="""
+ 1. "foo"
+ 2. "bar"
+ 3. "baz"
+ """]]
padding: 2ex 2ex;
}
+.infobox {
+ float: right;
+ margin-left: 2ex;
+ margin-top: 1ex;
+ margin-bottom: 1ex;
+ padding: 2ex 2ex;
+ border: 1px solid #aaa;
+}
+
/* outlines */
li.L1 {
list-style: upper-roman;
* Allow preprocessor directives to span multiple lines, both to make
long ones with lots of values easier to write, and to allow for ones with
multi-line quoted values.
+ * Allow preprocessor directives to contain python-like triple-quoted
+ text blocks, for easy nesting of quotes inside.
+ * Add a template plugin.
+ * Use the template plugin to add infoboxes to each plugin page listing basic
+ info about the plugin.
-- Joey Hess <joeyh@debian.org> Tue, 22 Aug 2006 23:09:46 -0400
-Here's how to get ikiwiki. See [[setup]] for how to use it, and be sure to add your wiki to [[IkiwikiUsers]] if you use ikiwiki.
+Here's how to get ikiwiki. See [[setup]] for how to use it, and be sure to
+add your wiki to [[IkiwikiUsers]] if you use ikiwiki.
# tarball
and [[bugs]] might also be of interest. Feel free to post your questions
and thoughts about ikiwiki to [[Discussion]].
+[[template type=note text="""
+If you use ikiwiki, please list your wiki in [[IkiWikiUsers]]. Thanks!
+"""]]
+
* [[Setup]] has a tutorial for setting up ikiwiki, and [[Usage]] documents
- the parameters and usage of the ikiwiki program. If you use ikiwiki,
- please add your wiki to [[IkiWikiUsers]].
+ the parameters and usage of the ikiwiki program.
* [[Security]] lists potential security problems. ikiwiki is still being
developed, and is being written with security as a priority, so don't
+[[template id=plugin name=aggregate included=1 author="""[[Joey]]"""]]
+[[tag type/useful]]
+
This plugin allows content from other blogs to be aggregated into the wiki.
Aggregate a blog as follows:
- \[[aggregate name="example blog" feedurl="http://example.com/index.rss" url="http://example.com/" updateinterval="15"]]
+ \[[aggregate name="example blog"
+ feedurl="http://example.com/index.rss"
+ url="http://example.com/" updateinterval="15"]]
That example aggregates posts from the expecified RSS feed, updating no
more frequently than once every 15 minutes, and puts a page per post under
Note that even if you are using subversion or another revision control
system, pages created by aggregation will *not* be checked into revision
control.
-
-This plugin is not enabled by default.
-
-[[tag type/useful]]
+[[template id=plugin name=brokenlinks included=1 author="""[[Joey]]"""]]
+[[tag type/link type/meta]]
+
This plugin generates a list of broken links on pages in the wiki. This is
a useful way to find pages that still need to be written, or links that
are written wrong.
The optional parameter "pages" can be a [[PageSpec]] specifying the pages
to search for broken links, default is search them all.
-This plugin is included in ikiwiki, but is not enabled by default.
-If it is turned on, here's a list of broken links on this wiki:
+If this plugin is turned on, here's a list of broken links on this wiki:
[[brokenlinks ]]
-
-[[tag type/link type/meta]]
+[[template id=plugin name=camelcase included=1 author="""[[Joey]]"""]]
+
This plugin makes words in CamelCase be treated as a [[WikiLink]]. That is
to say, any two or more words capitalised and mashed together are assumed
to be the name of some other page on the wiki, and so become a link.
-This plugin is included in ikiwiki, but is not enabled by default.
-
If this plugin is enabled, here is a link: SandBox
[[tag type/link]]
+[[template id=plugin name=linguas author="""Jorda Polo"""]]
+
Linguas
=======
+[[template id=plugin name=fortune included=1 author="""[[Joey]]"""]]
+[[tag type/fun]]
+
This just uses the `fortune` program to insert a fortune into the page.
Usage:
\[[fortune ]]
-This plugin is included in ikiwiki, but not enabled by default.
-
If this plugin is enabled, here's a fortune for you:
----
[[fortune ]]
-
-[[tag type/fun]]
+[[template id=plugin name=haiku included=1 author="""[[Joey]]"""]]
+[[tag type/fun]]
+
This plugin allows inserting a randomly generated haiku into a wiki page.
Just type:
page name. Since the vocabulary it knows is very small, many hints won't
affect the result at all.
-This plugin is included in ikiwiki, but is not enabled by default. As a
-special bonus, enabling this plugin makes any error messages ikiwiki should
-display be written in haiku.
+As a special bonus, enabling this plugin makes any error messages ikiwiki
+should display be written in haiku.
You need to have the Coy module installed for this plugin to do anything
interesting. That does all the heavy lifting.
-
-[[tag type/fun]]
+[[template id=plugin name=html included=1 author="""[[Joey]]"""]]
+[[tag type/html type/format]]
+
This plugin lets raw html pages be used as source pages for the wiki. The
html pages will still be wrapped in the same html template as any other
page, so for best results you should include only the page body in the html
in the html pages.
This plugin is included in ikiwiki, but is not enabled by default.
-
-[[tag type/html type/format]]
+[[template id=plugin name=htmlscrubber core=1 included=1
+author="""[[Joey]]"""]]
+[[tag type/html type/core]]
+
This plugin is enabled by default. It sanitizes the html on pages it renders
to avoid XSS attacks and the like.
* <span style="background: url(javascript:window.location='http://example.org/')">test</span>
* <span style="any: expression(window.location='http://example.org/')">test</span>
* <span style="any: expression(window.location='http://example.org/')">test</span>
-
-[[tag type/html type/core]]
+[[template id=plugin name=htmltidy included=1 author="""Faidon Liambotis"""]]
+[[tag type/html]]
+
This plugin uses [tidy](http://tidy.sourceforge.net/) to tidy up the html
emitted by ikiwiki. Besides being nicely formatted, this helps ensure that
even if users enter suboptimal html, your wiki generates valid html.
-This plugin is included in ikiwiki, but is not enabled by default.
-It was contributed by Faidon Liambotis.
-
-[[tag type/html]]
+Note that since tidy is an external program, that is run each time a page
+is built, this plugin will slow ikiwiki down somewhat.
+[[template id=plugin name=inline core=1 included=1 author="""[[Joey]]"""]]
+[[tag type/core]]
+
This is a [[PreProcessorDirective]] that allows including one wiki page
inside another. For example:
if raw is set to "yes", the page will be included raw, without additional
markup around it, as if it were a literal part of the source of the
inlining page.
-
-This plugin is enabled by default.
-
-[[tag type/core]]
+[[template id=plugin name=map included=1 author="""Alessandro Dotti Contra"""]]
+[[tag type/meta]]
+
This plugin generates a hierarchical page map for the wiki. Example usage:
\[[map pages="* and !blog/* and !*/Discussion"]]
of this wiki:
[[map pages="(plugins or plugins/*) and !*/*/*"]]
-
-[[tag type/meta]]
-This plugin, which is enabled by default, lets ikwiki convert files with
-names ending in ".mdwn" to html. It uses the [[markdown]] minimal markup
-language.
-
+[[template id=plugin name=mdwn core=1 included=1 author="""[[Joey]]"""]]
[[tag type/format type/core]]
+
+This plugin lets ikwiki convert files with names ending in ".mdwn" to html.
+It uses the [[markdown]] minimal markup language.
+
+This is the standard markup language used by ikiwiki, although some others
+are also available in other plugins.
+[[template id=plugin name=meta included=1 author="""[[Joey]]"""]]
+[[tag type/meta]]
+
This plugin allows inserting arbitrary metadata into the source of a page.
Enter the metadata as follows:
The field value is treated as HTML entity-escaped text, so you can include
a quote in the text by writing `"` and so on.
-This plugin is included in ikiwiki, but it is not enabled by default. If
-it is enabled, the title of this page will say it is.
+If this plugin is enabled, the title of this page will say that it is.
[[meta title="meta plugin (enabled)"]]
-
-[[tag type/meta]]
+[[template id=plugin name=orphans included=1 author="""[[Joey]]"""]]
+[[tag type/meta]]
+
This plugin generates a list of possibly orphaned pages -- pages that no
other page links to.
page as linking to it, so will generally count many blog-type pages as
orphans.
-This plugin is included in ikiwiki, but is not enabled by default.
-If it is turned on, here's a list of orphaned pages on this wiki:
+If it is enabled, here's a list of orphaned pages on this wiki:
[[orphans ]]
-
-[[tag type/meta]]
+[[template id=plugin name=otl included=1 author="""[[Joey]]"""]]
+[[tag type/format]]
+
This plugin allows ikiwiki to process `.otl` outline files, as created by
[vimoutliner](http://www.vimoutliner.org/). To use it, you need to have
vimoutliner installed, since it uses the `otl2html` program.
-
-This plugin is included in ikiwiki, but is not enabled by default.
-
-[[tag type/format]]
+[[template id=plugin name=pagecount included=1 author="""[[Joey]]"""]]
+[[tag type/meta]]
+
Provides a \\[[pagecount ]] [[PreProcessorDirective]] that is replaced with
the total number of pages currently in the wiki.
If it is turned on it can tell us that this wiki includes
[[pagecount ]] pages, of which [[pagecount pages="*/Discussion"]] are
discussion pages.
-
-[[tag type/meta]]
+[[template id=plugin name=pagestate included=1 author="""Enrico Zini"""]]
+[[tag type/meta type/tags]]
+
This plugin can generate stats about how pages link to each other. It can
produce either a del.icio.us style cloud, or a table counting the number of
links to each page.
And here's how to create a table of all the pages on the wiki:
\[[pagestats style="table"]]
-
-This plugin is included in ikiwiki, but is not enabled by default.
-It was contributed by Enrico Zini
-
-[[tag type/meta type/tags]]
+[[template id=plugin name=polygen included=1 author="""Enrico Zini"""]]
+[[tag type/fun]]
+
This plugin allows inserting text generated by polygen into a wiki page.
For example:
It's also possible to specify a starting nonterminal for the grammar by
including `symbol="text"` in the directive.
-This plugin is included in ikiwiki, but not enabled by default.
-It was contributed by Enrico Zini.
-
----
If this plugin is enabled, and polygen is installed, here are a few notes
<li>[[polygen grammar="reviews"]]</li>
<li>[[polygen grammar="reviews"]]</li>
</ul>
-
-[[tag type/fun]]
+[[template id=plugin name=rst included=1 author="""Sergio Talens-Oliag"""]]
+[[tag type/format]]
+
This plugin lets ikwiki convert files with names ending in ".rst" to html.
It uses the [reStructuredText](http://docutils.sourceforge.net/rst.html)
markup syntax. You need to have the python-docutils module installed to use
So while you may find this useful for importing old files into your wiki,
using this as your main markup language in ikiwiki isn't recommended at
this time.
-
-This plugin is included in ikiwiki, but not enabled by default.
-It was contributed by Sergio Talens-Oliag.
-
-[[tag type/format]]
+[[template id=plugin name=search included=1 author="""[[Joey]]"""]]
+[[tag type/useful]]
+
This plugin is included in ikiwiki, but is not enabled by default. It adds
full text search to ikiwiki, using the [[HyperEstraier]] engine.
It's possible to configure HyperEstraier via one of ikiwiki's
[[templates]], but for most users, no configuration should be needed aside
from enabling the plugin.
-
-[[tag type/useful]]
+[[template id=plugin name=sidebar included=1 author="""Tuomo Valkonen"""]]
+[[tag type/chrome]]
+
If this plugin is enabled, then a sidebar is added to pages in the wiki.
The content of the sidebar is simply the content of a page named
"sidebar" (ie, create a "sidebar.mdwn").
Note that to disable a sidebar for a [[SubPage]] of a page that has a sidebar,
you can create a sidebar page that is completely empty. This will turn off
the sidebar altogether.
-
-This plugin is included in ikiwiki, but is not enabled by default.
-It was contributed by Tuomo Valkonen.
-
-[[tag type/chrome]]
+[[template id=plugin name=smiley included=1 author="""[[Joey]]"""]]
+[[tag type/chrome]]
+
This plugin makes it easy to insert smileys and other special symbols into
pages in the wiki. The symbols are all listed on the [[smileys]] page,
which serves as both configuration for the plugin and a list of available
smileys.
This plugin is included in ikiwiki, but is not enabled by default. :-)
-
-[[tag type/format]]
+[[template id=plugin name=tag included=1 author="""[[Joey]]"""]]
+[[tag type/tags type/link]]
+
This plugin allows tagging pages. List tags as follows:
\[[tag tech life linux]]
having to write the full path to tags, if you want to keep them grouped
together out of the way.
-This plugin is included in ikiwiki, but is not enabled by default. If it is
-enabled, you'll see a note below that this page is tagged with the "tags"
-tag.
-
-[[tag type/tags type/link]]
+If this plugin is enabled, you'll see a note below that this page is tagged
+with the "tags" tag.
--- /dev/null
+[[template id=plugin name=template included=1 author="""[[Joey]]"""]]
+[[tag type/format]]
+
+With this plugin, you can set up templates, and cause them to be filled out
+and inserted into pages in the wiki. Using a template works like this:
+
+ \[[template id=foo name="Charley" color="red" age=11]]
+
+This fills out the template `templates/foo`, filling in the `color` and `age`
+fields on it with the specified values, and inserts the result into the page.
+
+If a value is triple-quoted, it can include any markup that would be
+allowed in the wiki page outside the template. Combined with multi-line
+quoted values, this allows for large chunks of marked up text to be
+embedded into a template:
+
+ \[[template id=foo name="Sally" color="green" age=8 notes="""
+ * \[[Charley]]'s sister.
+ * Really 8 and a half.
+ * Wants to be an astronaut when she grows up.
+ """]]
+
+To create a template, make a page in the wiki named `template/foo`. Note
+that this is a different location than the directory used for the
+[[templates]] used to build the wiki itself, which is not inside the wiki.
+
+The template uses the syntax used by the HTML::Template perl module, which
+allows for some fairly complex things to be done. Consult its documentation
+for the full syntax, but all you really need to know are a few things:
+
+* To insert the value of a variable, use `<TMPL_VAR variable>`.
+* To make a block of text conditional on a variable being set use
+ `<TMPL_IF NAME="variable">text</TMPL_IF>`.
+
+Here's a sample template:
+
+ <span class="infobox">
+ Name: <TMPL_VAR name><br />
+ Age: <TMPL_VAR age><br />
+ <TMPL_IF NAME="color">
+ Favorite color: <TMPL_VAR color><br />
+ <TMPL_ELSE>
+ No favorite color.<br />
+ </TMPL_IF>
+ <TMPL_IF NAME="notes">
+ <hr />
+ <TMPL_VAR notes>
+ </TMPL_IF>
+ </span>
+[[template id=plugin name=wikitext included=1 author="""[[Joey]]"""]]
+[[tag type/format]]
+
This plugin allows ikiwiki to process pages written in the original wiki
text format. To use it, you need to have the Text::WikiFormat perl module
installed, enable the plugin, then files with the extention `.wiki` will be
of one or more alphanumeric characters followed by a period and an optional
space. Any indented text without either marking is code, handled literally.
You can nest lists.
-
-This plugin is included in ikiwiki, but is not enabled by default.
-
-[[tag type/format]]
It's difficult to know for sure if all such avenues have really been
closed though.
+## HTML::Template security
+
+If the [[plugins/template]] plugin is enabled, users can modify templates
+like any other part of the wiki. This assumes that HTML::Template is secure
+when used with untrusted/malicious templates. (Note that includes are not
+allowed, so that's not a problem.)
+
----
# Fixed holes
--- /dev/null
+<span class="infobox">
+<TMPL_VAR content>
+</span>
--- /dev/null
+<span class="infobox">
+Plugin: <TMPL_VAR name><br />
+Author: <TMPL_VAR author><br />
+Enabled by default: <TMPL_IF core>yes<TMPL_ELSE>no</TMPL_IF><br />
+Included in ikiwiki: <TMPL_IF included>yes<TMPL_ELSE>no</TMPL_IF><br />
+</span>
+++ /dev/null
-# thoughts on infoboxes
-
-I was thinking about adding a [[preprocessordirective]] to make it easy to
-add an info box. Something like:
-
- \[[infobox "text here"]]
-
-But it seems it would be better if multi-line text could be put inside,
-maybe expanding the syntax a bit:
-
- \[[infobox "
- text here
- and here
- etc.
- "]]
-
-This would just wrap the text up in a span element that was styled to float
-to the right, with a border, the way info boxes do on some wikis.
-
-However, as I thought about it some more, I realized that this would be
-just as easy to type:
-
- <span id=infobox>
- text here
- </span>
-
-Why invent new syntax, after all? I see no reason to for something this
-simple.
-
-However, maybe in the more complex case, this would be useful. If the
-infobox filled in a kind of template:
-
- \[[infobox type=person name="Joey Hess" email=joey@kitenet.net url="http://kitenet.net/~joey/" description="
- Joey is the author of ikiwiki and some other stuff. *Yay*!
- "]]
-
-That might be a lot more useful. Or here's one to use to describe ikiwiki's
-own plugins:
-
- \[[infobox type=plugin name="sidebar" author="Tuomo Valkonen" core=no]]
-
-This would expand by filling out the template page, which would be
-infobox/person or infobox/plugin, or whatever, and would have some syntax
-(possibly HTML::Template, if it's secure) for testing for values and
-embedding variables. Of course it would register a dependency on its
-template so changes to the template update all the pages.
-
-(Since it's a preprocessor directive, the big multiline blocks of text can
-mix markdown (or whatever) with html, wikilinks, etc, in a natural way,
-which is nice..)
projects / ikiwiki.git / commitdiff