From 9d7375c3b263e77da29a5db22af480db8b99d990 Mon Sep 17 00:00:00 2001 From: joey Date: Wed, 23 Aug 2006 05:41:07 +0000 Subject: [PATCH] * 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. --- IkiWiki/Plugin/template.pm | 52 +++++++++++++++++++++++++++++ IkiWiki/Render.pm | 8 ++--- Makefile.PL | 3 +- basewiki/preprocessordirective.mdwn | 21 +++++++----- basewiki/style.css | 9 +++++ debian/changelog | 5 +++ doc/download.mdwn | 3 +- doc/index.mdwn | 7 ++-- doc/plugins/aggregate.mdwn | 11 +++--- doc/plugins/brokenlinks.mdwn | 8 ++--- doc/plugins/camelcase.mdwn | 4 +-- doc/plugins/contrib/linguas.mdwn | 2 ++ doc/plugins/fortune.mdwn | 7 ++-- doc/plugins/haiku.mdwn | 10 +++--- doc/plugins/html.mdwn | 5 +-- doc/plugins/htmlscrubber.mdwn | 6 ++-- doc/plugins/htmltidy.mdwn | 9 ++--- doc/plugins/inline.mdwn | 7 ++-- doc/plugins/map.mdwn | 5 +-- doc/plugins/mdwn.mdwn | 11 +++--- doc/plugins/meta.mdwn | 8 ++--- doc/plugins/orphans.mdwn | 8 ++--- doc/plugins/otl.mdwn | 7 ++-- doc/plugins/pagecount.mdwn | 5 +-- doc/plugins/pagestats.mdwn | 8 ++--- doc/plugins/polygen.mdwn | 8 ++--- doc/plugins/rst.mdwn | 8 ++--- doc/plugins/search.mdwn | 5 +-- doc/plugins/sidebar.mdwn | 8 ++--- doc/plugins/smiley.mdwn | 5 +-- doc/plugins/tag.mdwn | 10 +++--- doc/plugins/template.mdwn | 49 +++++++++++++++++++++++++++ doc/plugins/wikitext.mdwn | 7 ++-- doc/security.mdwn | 7 ++++ doc/templates/note.mdwn | 3 ++ doc/templates/plugin.mdwn | 6 ++++ doc/todo/infoboxes.mdwn | 50 --------------------------- 37 files changed, 243 insertions(+), 152 deletions(-) create mode 100644 IkiWiki/Plugin/template.pm create mode 100644 doc/plugins/template.mdwn create mode 100644 doc/templates/note.mdwn create mode 100644 doc/templates/plugin.mdwn delete mode 100644 doc/todo/infoboxes.mdwn diff --git a/IkiWiki/Plugin/template.pm b/IkiWiki/Plugin/template.pm new file mode 100644 index 000000000..5b4eeb3a8 --- /dev/null +++ b/IkiWiki/Plugin/template.pm @@ -0,0 +1,52 @@ +#!/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 diff --git a/IkiWiki/Render.pm b/IkiWiki/Render.pm index 8657dc380..38bfcdfcb 100644 --- a/IkiWiki/Render.pm +++ b/IkiWiki/Render.pm @@ -104,12 +104,12 @@ sub preprocess ($$$;$) { #{{{ # 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}->( @@ -123,7 +123,7 @@ sub preprocess ($$$;$) { #{{{ } }; - $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; } #}}} diff --git a/Makefile.PL b/Makefile.PL index 2ef99fa80..f2f5ba4a1 100755 --- a/Makefile.PL +++ b/Makefile.PL @@ -23,7 +23,8 @@ extra_build: --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 diff --git a/basewiki/preprocessordirective.mdwn b/basewiki/preprocessordirective.mdwn index 31731af66..1e2332c09 100644 --- a/basewiki/preprocessordirective.mdwn +++ b/basewiki/preprocessordirective.mdwn @@ -16,15 +16,18 @@ be put after its name, to avoid confusion with a [[WikiLink]]. For example: \[[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" + """]] diff --git a/basewiki/style.css b/basewiki/style.css index 7bb9bb9f5..abedf5805 100644 --- a/basewiki/style.css +++ b/basewiki/style.css @@ -139,6 +139,15 @@ td.changelog { 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; diff --git a/debian/changelog b/debian/changelog index ba8b6d4f4..73a1dc18e 100644 --- a/debian/changelog +++ b/debian/changelog @@ -8,6 +8,11 @@ ikiwiki (1.22) UNRELEASED; urgency=low * 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 Tue, 22 Aug 2006 23:09:46 -0400 diff --git a/doc/download.mdwn b/doc/download.mdwn index 55c280984..27152d056 100644 --- a/doc/download.mdwn +++ b/doc/download.mdwn @@ -1,4 +1,5 @@ -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 diff --git a/doc/index.mdwn b/doc/index.mdwn index ae11842d0..c79aa8f8a 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -11,9 +11,12 @@ Instead it can use [[Subversion]] (or [[Git]]). 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 diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn index a21d291d3..dc943dd10 100644 --- a/doc/plugins/aggregate.mdwn +++ b/doc/plugins/aggregate.mdwn @@ -1,7 +1,12 @@ +[[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 @@ -50,7 +55,3 @@ directive: 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]] diff --git a/doc/plugins/brokenlinks.mdwn b/doc/plugins/brokenlinks.mdwn index e3f6357b7..2c6d9b4c7 100644 --- a/doc/plugins/brokenlinks.mdwn +++ b/doc/plugins/brokenlinks.mdwn @@ -1,3 +1,6 @@ +[[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. @@ -5,9 +8,6 @@ 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]] diff --git a/doc/plugins/camelcase.mdwn b/doc/plugins/camelcase.mdwn index a5006f9bf..f8d8b39ab 100644 --- a/doc/plugins/camelcase.mdwn +++ b/doc/plugins/camelcase.mdwn @@ -1,9 +1,9 @@ +[[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]] diff --git a/doc/plugins/contrib/linguas.mdwn b/doc/plugins/contrib/linguas.mdwn index 3c194d59b..90ccb14d5 100644 --- a/doc/plugins/contrib/linguas.mdwn +++ b/doc/plugins/contrib/linguas.mdwn @@ -1,3 +1,5 @@ +[[template id=plugin name=linguas author="""Jorda Polo"""]] + Linguas ======= diff --git a/doc/plugins/fortune.mdwn b/doc/plugins/fortune.mdwn index f4c45a921..65aa355cd 100644 --- a/doc/plugins/fortune.mdwn +++ b/doc/plugins/fortune.mdwn @@ -1,14 +1,13 @@ +[[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]] diff --git a/doc/plugins/haiku.mdwn b/doc/plugins/haiku.mdwn index d78e609da..1ea5eb4d9 100644 --- a/doc/plugins/haiku.mdwn +++ b/doc/plugins/haiku.mdwn @@ -1,3 +1,6 @@ +[[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: @@ -10,11 +13,8 @@ what to write the haiku about. If no hint is given, it might base it on the 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]] diff --git a/doc/plugins/html.mdwn b/doc/plugins/html.mdwn index 400adb9ee..5d300e5ff 100644 --- a/doc/plugins/html.mdwn +++ b/doc/plugins/html.mdwn @@ -1,3 +1,6 @@ +[[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 @@ -6,5 +9,3 @@ sanitised like any other page. You can also use standard [[WikiLink]]s etc in the html pages. This plugin is included in ikiwiki, but is not enabled by default. - -[[tag type/html type/format]] diff --git a/doc/plugins/htmlscrubber.mdwn b/doc/plugins/htmlscrubber.mdwn index 770031650..252fcd5d2 100644 --- a/doc/plugins/htmlscrubber.mdwn +++ b/doc/plugins/htmlscrubber.mdwn @@ -1,3 +1,7 @@ +[[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. @@ -28,5 +32,3 @@ plugin is active: * test * test * test - -[[tag type/html type/core]] diff --git a/doc/plugins/htmltidy.mdwn b/doc/plugins/htmltidy.mdwn index 9da9c4d98..c16c7bc71 100644 --- a/doc/plugins/htmltidy.mdwn +++ b/doc/plugins/htmltidy.mdwn @@ -1,8 +1,9 @@ +[[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. diff --git a/doc/plugins/inline.mdwn b/doc/plugins/inline.mdwn index a142df154..fa8e0c334 100644 --- a/doc/plugins/inline.mdwn +++ b/doc/plugins/inline.mdwn @@ -1,3 +1,6 @@ +[[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: @@ -24,7 +27,3 @@ directive: 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]] diff --git a/doc/plugins/map.mdwn b/doc/plugins/map.mdwn index cd2ef1bc5..7780c3306 100644 --- a/doc/plugins/map.mdwn +++ b/doc/plugins/map.mdwn @@ -1,3 +1,6 @@ +[[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"]] @@ -15,5 +18,3 @@ If this plugin is enabled, here is a page map for the plugins section of this wiki: [[map pages="(plugins or plugins/*) and !*/*/*"]] - -[[tag type/meta]] diff --git a/doc/plugins/mdwn.mdwn b/doc/plugins/mdwn.mdwn index 25e46cd01..34c688ce1 100644 --- a/doc/plugins/mdwn.mdwn +++ b/doc/plugins/mdwn.mdwn @@ -1,5 +1,8 @@ -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. diff --git a/doc/plugins/meta.mdwn b/doc/plugins/meta.mdwn index 19262f86b..84d48d8ef 100644 --- a/doc/plugins/meta.mdwn +++ b/doc/plugins/meta.mdwn @@ -1,3 +1,6 @@ +[[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: @@ -52,8 +55,5 @@ header. 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]] diff --git a/doc/plugins/orphans.mdwn b/doc/plugins/orphans.mdwn index 4591ebf59..1eab368f9 100644 --- a/doc/plugins/orphans.mdwn +++ b/doc/plugins/orphans.mdwn @@ -1,3 +1,6 @@ +[[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. @@ -8,9 +11,6 @@ Note that it takes [[BackLinks]] into account, but does not count inlining a 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]] diff --git a/doc/plugins/otl.mdwn b/doc/plugins/otl.mdwn index fd3ac23ec..4d45125f5 100644 --- a/doc/plugins/otl.mdwn +++ b/doc/plugins/otl.mdwn @@ -1,7 +1,6 @@ +[[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]] diff --git a/doc/plugins/pagecount.mdwn b/doc/plugins/pagecount.mdwn index 8fc04ff76..9aae91a1e 100644 --- a/doc/plugins/pagecount.mdwn +++ b/doc/plugins/pagecount.mdwn @@ -1,3 +1,6 @@ +[[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. @@ -9,5 +12,3 @@ This plugin is included in ikiwiki, but is not enabled by default. 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]] diff --git a/doc/plugins/pagestats.mdwn b/doc/plugins/pagestats.mdwn index 93e9f5694..4e194f84a 100644 --- a/doc/plugins/pagestats.mdwn +++ b/doc/plugins/pagestats.mdwn @@ -1,3 +1,6 @@ +[[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. @@ -9,8 +12,3 @@ Here's how to use it to create a [[tag]] cloud: 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]] diff --git a/doc/plugins/polygen.mdwn b/doc/plugins/polygen.mdwn index d04708e2a..b49eeda0e 100644 --- a/doc/plugins/polygen.mdwn +++ b/doc/plugins/polygen.mdwn @@ -1,3 +1,6 @@ +[[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: @@ -6,9 +9,6 @@ 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 @@ -25,5 +25,3 @@ Ikiwiki reviews:
  • [[polygen grammar="reviews"]]
  • [[polygen grammar="reviews"]]
    • - -[[tag type/fun]] diff --git a/doc/plugins/rst.mdwn b/doc/plugins/rst.mdwn index 0f0d6f96c..f7cbf57bb 100644 --- a/doc/plugins/rst.mdwn +++ b/doc/plugins/rst.mdwn @@ -1,3 +1,6 @@ +[[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 @@ -17,8 +20,3 @@ ikiwiki. Limitations include: 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]] diff --git a/doc/plugins/search.mdwn b/doc/plugins/search.mdwn index 78088aed8..a95302fcc 100644 --- a/doc/plugins/search.mdwn +++ b/doc/plugins/search.mdwn @@ -1,8 +1,9 @@ +[[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]] diff --git a/doc/plugins/sidebar.mdwn b/doc/plugins/sidebar.mdwn index 8ab416f6f..4be012e39 100644 --- a/doc/plugins/sidebar.mdwn +++ b/doc/plugins/sidebar.mdwn @@ -1,3 +1,6 @@ +[[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"). @@ -10,8 +13,3 @@ SubPages, if the plugin is enabled. 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]] diff --git a/doc/plugins/smiley.mdwn b/doc/plugins/smiley.mdwn index 29a038786..b0f65f4af 100644 --- a/doc/plugins/smiley.mdwn +++ b/doc/plugins/smiley.mdwn @@ -1,8 +1,9 @@ +[[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]] diff --git a/doc/plugins/tag.mdwn b/doc/plugins/tag.mdwn index f24accafa..8df139c0b 100644 --- a/doc/plugins/tag.mdwn +++ b/doc/plugins/tag.mdwn @@ -1,3 +1,6 @@ +[[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]] @@ -14,8 +17,5 @@ tags/tech, tags/life, and tags/linux. This is a useful way to avoid 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. diff --git a/doc/plugins/template.mdwn b/doc/plugins/template.mdwn new file mode 100644 index 000000000..9e2ab0891 --- /dev/null +++ b/doc/plugins/template.mdwn @@ -0,0 +1,49 @@ +[[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 ``. +* To make a block of text conditional on a variable being set use + `text`. + +Here's a sample template: + + + Name:
    + Age:
    + + Favorite color:
    + + No favorite color.
    +     + +
    + +     +     diff --git a/doc/plugins/wikitext.mdwn b/doc/plugins/wikitext.mdwn index 603dda4ca..195e8251c 100644 --- a/doc/plugins/wikitext.mdwn +++ b/doc/plugins/wikitext.mdwn @@ -1,3 +1,6 @@ +[[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 @@ -18,7 +21,3 @@ asterisk and space. Ordered lists consist of items marked with combination 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]] diff --git a/doc/security.mdwn b/doc/security.mdwn index f3567d155..dc763ef40 100644 --- a/doc/security.mdwn +++ b/doc/security.mdwn @@ -145,6 +145,13 @@ with a username containing html code (anymore). 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 diff --git a/doc/templates/note.mdwn b/doc/templates/note.mdwn new file mode 100644 index 000000000..29dca8f0a --- /dev/null +++ b/doc/templates/note.mdwn @@ -0,0 +1,3 @@ + + + diff --git a/doc/templates/plugin.mdwn b/doc/templates/plugin.mdwn new file mode 100644 index 000000000..ca69efd23 --- /dev/null +++ b/doc/templates/plugin.mdwn @@ -0,0 +1,6 @@ + +Plugin:
    +Author:
    +Enabled by default: yesno
    +Included in ikiwiki: yesno
    +     diff --git a/doc/todo/infoboxes.mdwn b/doc/todo/infoboxes.mdwn deleted file mode 100644 index 293cd66b8..000000000 --- a/doc/todo/infoboxes.mdwn +++ /dev/null @@ -1,50 +0,0 @@ -# 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: - - - text here - - -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..) -- 2.26.2