diff options
Diffstat (limited to 'doc/plugins')
23 files changed, 541 insertions, 176 deletions
diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn index 8dfbbf716..836a98f33 100644 --- a/doc/plugins/contrib/album.mdwn +++ b/doc/plugins/contrib/album.mdwn @@ -1,144 +1,118 @@ [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]] -[[!template id=gitbranch branch=smcv/album2 author="[[Simon_McVittie|smcv]]"]] [[!tag type/chrome]] -Available from [[smcv]]'s git repository, in the `album2` branch. -Older (pre-rebase) versions in `album`, `album-live` (the latter -was used on an actual website and didn't explode too much). +This plugin provides the [[ikiwiki/directive/album]] [[ikiwiki/directive]], +which turns a page into a photo album or image gallery, containing all +images attached to the album or its subpages. It also provides the +[[ikiwiki/directive/albumsection]] and [[ikiwiki/directive/albumimage]] +directives. -This plugin formats a collection of images into a photo album, -in the same way as many websites: good examples include the -PHP application [Gallery](http://gallery.menalto.com/), Flickr, -and Facebook's Photos "application". +This plugin automatically enables the [[filecheck]], [[img]], [[inline]], +[[trail]] and [[transient]] plugins. The [[meta]] plugin is also +recommended. -I've called it `album` to distinguish it from -[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be -a better name for this functionality. - -The web UI I'm trying to achieve consists of one -[HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/) -as an entry point to the album, where each thumbnail links to -[a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/) -with a full size image, next/previous thumbnail links, and -[[plugins/comments]]. - -(The Summer of Code [[plugins/contrib/gallery]] plugin does the -next/previous UI in Javascript using Lightbox, which means that -individual photos can't be bookmarked in a meaningful way, and -the best it can do as a fallback for non-Javascript browsers -is to provide a direct link to the image.) - -<h2 id="album"><code>album</code> directive</h2> +## Changing the templates -Each page containing an `album` directive is treated as a photo album. +When a viewer page is generated or inlined into an album, the template can +contain these extra variables: -Every image attached to an album or its subpages is considered to be part of -the album. A "viewer" page, with the wiki's default page extension, will be -generated in the [[transient underlay|todo/transient_pages]] to display the -image, if there isn't already a page of the same name as the image: for -instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists, -then `debconf/tuesday/p100.mdwn` might be created. +* `<TMPL_VAR ALBUM>` - page name of the album +* `<TMPL_VAR ALBUMURL>` - relative URL to the album +* `<TMPL_VAR ALBUMTITLE>` - title of the album, usually taken from + a [[ikiwiki/directive/meta]] directive +* `<TMPL_VAR CAPTION>` - caption for the image +* `<TMPL_VAR THUMBNAIL>` - a small [[ikiwiki/directive/img]] for the image +* `<TMPL_VAR IMAGEWIDTH>` - width of the full-size image in pixels +* `<TMPL_VAR IMAGEHEIGHT>` - height of the full-size image in pixels +* `<TMPL_VAR IMAGEFILESIZE>` - size of the image, e.g. `1.2 MiB` +* `<TMPL_VAR IMAGEFORMAT>` - format of the image, typically `JPEG` -There's currently a hard-coded list of extensions that are treated as images: -`png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video types could -be added in future. Videos aren't currently handled very well; -ideally, something like totem-video-thumbnailer would be used. +The template for the viewer page can also contain: -The `album` directive also produces an [[ikiwiki/directive/inline]] which -automatically includes all the viewers for this album, except those that -will appear in an <a href="#albumsection">albumsection</a> (if every image -is in a section, then the `album` directive won't have any visible effect). +* `<TMPL_VAR IMG>` - a large [[ikiwiki/directive/img]] to display the image +* `<TMPL_VAR PREV>` - a link to the previous viewer, typically with a + thumbnail +* `<TMPL_VAR NEXT>` - a link to the next viewer, typically with a + thumbnail -The `inline` is in `archive` and `quick` mode, but can include some -extra information about the images, including file size and a thumbnail made -using [[ikiwiki/directive/img]]). The default template is `albumitem.tmpl`, -which takes advantage of these things. +## Including album entries elsewhere -<h2 id="albumsection"><code>albumsection</code> directive</h2> +To display images from elsewhere in the wiki with the same appearance as +an [[ikiwiki/directive/album]] or [[ikiwiki/directive/albumsection]], +you can use an [[ikiwiki/directive/inline]] with the `albumitem` +template: -The `albumsection` directive is used to split an album into sections. It can -only appear on a page that also has the <a href="#album">album</a> directive. + \[[!inline pages="..." sort="-age" template="albumitem"]] -The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages -are matched. The `albumsection` directive displays all the images that match -the filter, and the `album` directive displays any leftover images, like -this: +---- - # Holiday photos +[[!template id=gitbranch branch=smcv/album3 author="[[Simon_McVittie|smcv]]"]] - \[[!album]] - <!-- replaced with a list of any uncategorized photos, which might be - empty --> - - ## People - - \[[!albumsection filter="tagged(people)"]] - <!-- replaced with a list of photos tagged 'people', including - any that are also tagged 'landscapes' --> +Available from [[smcv]]'s git repository, in the `album3` branch. +I've called it `album` to distinguish it from +[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be +a better name for this functionality. - ## Landscapes +(The Summer of Code [[plugins/contrib/gallery]] plugin does the +next/previous UI in Javascript using Lightbox, which means that +individual photos can't be bookmarked in a meaningful way, and +the best it can do as a fallback for non-Javascript browsers +is to provide a direct link to the image.) - \[[!albumsection filter="tagged(landscapes)"]] - <!-- replaced with a list of photos tagged 'landscapes', including - any that are also tagged 'people' --> +Updated, November 2011: rebased onto [[trail]] v3, CSS adjusted. -<h2 id="albumimage"><code>albumimage</code> directive</h2> +## Manual installation -Each viewer page produced by the <a href="#album">album</a> directive -contains an `albumimage` directive, which is replaced by an -[[ikiwiki/directive/img]], wrapped in some formatting using a -template (by default it's `albumviewer.tmpl`). That template can also include -links to the next photo, the previous photo and the album it's in; the default -template has all of these. +If you don't want to use a branch of ikiwiki, manual installation requires +these files (use the "raw" link in gitweb to download), in addition to the +ones needed by [[trail]]: -The next/previous links are themselves implemented by evaluating a template, -either `albumnext.tmpl` or `albumprev.tmpl` by default. +* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/IkiWiki/Plugin/album.pm) + in an `IkiWiki/Plugin` subdirectory of your configured `plugindir` +* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumviewer.tmpl), + [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumitem.tmpl), + [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumnext.tmpl) and + [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumprev.tmpl), + in your configured `templatedir`, or a `templates` subdirectory of your wiki repository +* the album-related bits from the end of the + [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/doc/style.css) + (put them in your local.css) -The directive can also have parameters: +## Demo -* `title`, `copyright` and `date` are short-cuts for the corresponding - [[ikiwiki/directive/meta]] directives +* [HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/) + as an entry point to the album +* Each thumbnail links to + [a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/) + with a full size image, optional next/previous thumbnail links, and + optional [[plugins/comments]] -* `caption` sets a caption which is displayed in the album and viewer - pages +## Bugs -The viewer page can also have other contents before or after the actual -image viewer. +* There's currently a hard-coded list of extensions that are treated as + images: `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video + types could be added in future. -## Bugs +* Videos aren't currently handled very well; ideally, something like + totem-video-thumbnailer would be used. * The plugin doesn't do anything special to handle albums that are subpages of each other. If, say, `debconf` and `debconf/monday` are both albums, then `debconf/monday/p100.jpg` will currently be assigned to one or the other, arbitrarily. It should probably pick the closest (longest) album name. + (I'm not sure that it can do this reliably, though, since the scan stage + runs in an undefined order.) * The plugin doesn't do anything special to handle photos with similar names. If you have `p100.jpg` and `p100.png`, one will get a viewer page called - `p100` and the other will be ignored. + `p100` and the other will be ignored. (I'm not sure what we could do better, + though.) * If there's no `albumimage` in a viewer page, one should probably be appended automatically. -* When editing a viewer page, rebuilding it seems to fail at the moment. - Probably related to: - -* Integration with [[plugins/contrib/trail]] is new, untested and not - very well implemented. In particular, the prev/up/next links are - redundant with the ones from `trail`. - ## TODO -* The documentation should mention how to replicate the appearance of - `album` and `albumsection` using an `inline` of viewer pages, - elsewhere on the site. - -* The documentation should mention all the template variables and - all the parameters. - -* The generated viewer page should include most or all of the possible - parameters to the `albumimage` directive, with empty values, as a - template for editing. - * The generated viewer page should extract as much metadata as possible from the photo's EXIF tags (creation/modification dates, author, title, caption, copyright). [[smcv]] has a half-written implementation which runs diff --git a/doc/plugins/contrib/ikiwiki/directive/album.mdwn b/doc/plugins/contrib/ikiwiki/directive/album.mdwn new file mode 100644 index 000000000..433eec8bd --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/album.mdwn @@ -0,0 +1,56 @@ +The `album` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +Each page containing an `album` directive is treated as a photo album +or image gallery. Example usage is as simple as: + + \[[!album]] + +Every image attached to an album or its [[subpages|ikiwiki/subpage]] is +considered to be part of the album. A "viewer" page, with the wiki's default +page extension, will be generated in the +[[transient underlay|plugins/transient]] to display the +image, if there isn't already a page of the same name as the image: for +instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists, +then `debconf/tuesday/p100.mdwn` might be created. + +The album is treated as a [[!iki plugins/contrib/trail desc=trail]], which +gives each viewer page a link back to the album, and a link to the previous +and next viewer in the album. + +The `album` directive also produces an [[ikiwiki/directive/inline]] which +automatically includes all the viewers for this album, except those that +will appear in an [[albumsection]]. If every image in the album is in a +section, then the `album` directive is still required, but won't produce +any output in the page. + +The `inline` can include some extra information about the images, including +file size and a thumbnail made using [[ikiwiki/directive/img]]). The +default template is `albumitem.tmpl`, which takes advantage of these things. + +## Options + +The directive can have some options for the entire album. The defaults are: + + \[[!album + sort="-age" + size="full" + thumbnailsize="96x96" + viewertemplate="albumviewer" + prevtemplate="albumprev" + nexttemplate="albumnext" + +* `sort` - sets the order in which images appear, defaulting to earliest + creation date first +* `size` - if not `full`, the [[ikiwiki/directive/img]] in the viewer page + will be resized to be no larger than this +* `thumbnailsize` - the [[ikiwiki/directive/img]] in the album page, + which can also be used in the previous/next links, will be no larger than + this +* `viewertemplate` - the template used for the [[albumimage]] in each + viewer page +* `prevtemplate` - the template used to replace `<TMPL_VAR PREV>` if used in + the viewer page +* `nexttemplate` - the template used to replace `<TMPL_VAR NEXT>` if used in + the viewer page + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn new file mode 100644 index 000000000..2385bb535 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn @@ -0,0 +1,26 @@ +The `albumimage` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +Each viewer page produced by the [[album]] directive +contains an `albumimage` directive, which is replaced by an +[[ikiwiki/directive/img]], wrapped in some formatting using a +template (by default it's `albumviewer.tmpl`). That template can also include +links to the next and previous photos, in addition to those provided by the +[[!iki plugins/contrib/trail desc=trail]] plugin. + +The next/previous links are themselves implemented by evaluating a template, +either `albumnext.tmpl` or `albumprev.tmpl` by default. + +The directive can also have parameters: + +* `title`, `date`, `updated`, `author`, `authorurl`, `copyright`, `license` + and `description` are short-cuts for the corresponding + [[ikiwiki/directive/meta]] directives + +* `caption` sets a caption which is displayed near this image in the album + and viewer pages + +The viewer page can also contain any text and markup before or after the +`albumimage` directive, which will appear before or after the image in the +viewer page. + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn new file mode 100644 index 000000000..7e5749e05 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn @@ -0,0 +1,29 @@ +The `albumsection` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin. + +The `albumsection` directive is used to split an album into sections. It can +only appear on a page that also has the [[album]] directive. + +The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages +are matched. The `albumsection` directive displays all the images that match +the filter, and the `album` directive displays any leftover images, like +this: + + # Holiday photos + + \[[!album]] + <!-- replaced with a list of any uncategorized photos; it will be + empty if they're all tagged as 'people' and/or 'landscapes' --> + + ## People + + \[[!albumsection filter="tagged(people)"]] + <!-- replaced with a list of photos tagged 'people', including + any that are also tagged 'landscapes' --> + + ## Landscapes + + \[[!albumsection filter="tagged(landscapes)"]] + <!-- replaced with a list of photos tagged 'landscapes', including + any that are also tagged 'people' --> + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/jssearchfield.mdwn b/doc/plugins/contrib/ikiwiki/directive/jssearchfield.mdwn new file mode 100644 index 000000000..5d338901d --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/jssearchfield.mdwn @@ -0,0 +1,42 @@ +The `jssearchfield` directive is supplied by the [[!iki plugins/contrib/jssearchfield desc=jssearchfield]] plugin. + +This enables one to search the structured data ("field" values) of +multiple pages. A search form is constructed, and the searching is +done with Javascript, which means that the entire thing is self-contained. +This depends on the [[!iki plugins/contrib/field]] plugin. + +The pages to search are selected by a PageSpec given by the "pages" +parameter. +The fields to search are given by the "fields" parameter. By default, +the field name is given, and the user can type the search parameter for +that field into a text input field. + +## OPTIONS + +**pages**: A PageSpec to determine the pages to search through. + +**fields**: The fields to put into the search form, and to display +in the results. + +**tagfields**: Display the given fields as a list of tags that can +be selected from, rather than having a text input field. Every distinct +value of that field will be listed, so it is best used for things with +short values, like "Author" rather than long ones like "Description". +Note that "tagfields" must be a subset of "fields". + +**sort**: A SortSpec to determine how the matching pages should be sorted; this is the "default" sort order that the results will be displayed in. +The search form also gives the option of "random" sort, which will +display the search results in random order. + +## SEARCHING + +The search form that is created by this directive contains the following: + +* for each search field, a label, plus either a text input field, or a list of checkboxes with values next to them if the field is also a tagfield. Note that the lists of checkboxes are initially hidden; one must click on the triangle next to the label to display them. +* a "sort" toggle. One can select either "default" or "random". +* A "Search!" button, to trigger the search if needed (see below) +* A "Reset" button, which will clear all the values. + +The searching is dynamic. As soon as a value is changed, either by tabbing out of the text field, or by selecting or de-selecting a checkbox, the search +results are updated. Furthermore, for tagfields, the tagfield lists +themselves are updated to reflect the current search results. diff --git a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn new file mode 100644 index 000000000..91d8a4edf --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn @@ -0,0 +1,11 @@ +The `trailinline` directive is provided by the +[[!iki plugins/contrib/trail desc=trail]] +plugin. It is equivalent to combining [[ikiwiki/directive/trailitems]] and +[[ikiwiki/directive/inline]] directives with the same options. + +A typical use is to navigate through all posts in a blog: + + \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes + feedshow=10 quick=yes]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn new file mode 100644 index 000000000..73b1985a5 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn @@ -0,0 +1,9 @@ +The `trailitem` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] plugin. It is used like this: + + \[[!trailitem some_other_page]] + +to add `some_other_page` to the trail represented by this page, without +generating a visible hyperlink. + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn new file mode 100644 index 000000000..4106ed33b --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn @@ -0,0 +1,24 @@ +The `trailitems` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] plugin. It adds pages +to the trail represented by the current page, without producing any output +on that page. + + \[[!trailitems pages="posts/*" sort="age"]] + + \[[!trailitems pagenames="a b c"]] + +Options are similar to [[!iki ikiwiki/directive/inline desc=inline]]: + +* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail + (cannot be used with `pagenames`) + +* `pagenames`: adds a space-separated list of pages to the trail, + with the same [[ikiwiki/SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]] + (cannot be used with `pages`) + +* `sort`: add the pages matched by `pages` to the trail in this + [[ikiwiki/pagespec/sorting]] order (cannot be used with `pagenames`) + +* `reverse`: reverse the order of `sort` (cannot be used with `pagenames`) + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn new file mode 100644 index 000000000..0e40e2411 --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn @@ -0,0 +1,16 @@ +The `traillink` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] +plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the +linked page to the trail represented by the page containing the directive. + +In its simplest form, the first parameter is like the content of a WikiLink: + + \[[!traillink some_other_page]] + +The displayed text can also be overridden, either with a `|` symbol or with +a `text` parameter: + + \[[!traillink Click_here_to_start_the_trail|some_other_page]] + \[[!traillink some_other_page text="Click here to start the trail"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn new file mode 100644 index 000000000..e1603f11b --- /dev/null +++ b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn @@ -0,0 +1,18 @@ +The `trailoptions` directive is supplied by the +[[!iki plugins/contrib/trail desc=trail]] plugin. It sets options for the +trail represented by this page. + + \[[!trailoptions sort="meta(title)" circular="no"]] + +Options available: + +* `sort`: sets a [[ikiwiki/pagespec/sorting]] order for the entire trail, + overriding the order in which they were added + +* `reverse`: reverses the order of the trail + +* `circular`: if set to `yes` or `1`, the trail is made into a loop by + making the last page's "next" link point to the first page, and the first + page's "previous" link point to the last page + +[[!meta robots="noindex, follow"]] diff --git a/doc/plugins/contrib/jssearchfield.mdwn b/doc/plugins/contrib/jssearchfield.mdwn new file mode 100644 index 000000000..2d41ee24f --- /dev/null +++ b/doc/plugins/contrib/jssearchfield.mdwn @@ -0,0 +1,35 @@ +[[!template id=plugin name=jssearchfield author="[[rubykat]]"]] +[[!tag type/search]] +IkiWiki::Plugin::jssearchfield - Create a search form to search page field data. + +This plugin provides the [[ikiwiki/directive/jssearchfield]] directive. This +enables one to search the structured data ("field" values) of multiple pages. +This uses Javascript for the searching, which means that the entire thing +is self-contained and does not require a server or CGI access, unlike +the default IkiWiki search. This means that it can be used in places such +as ebook readers. The disadvantage is that because Javascript runs +in the browser, the searching is only as fast as the machine your browser +is running on. + +Because this uses Javascript, the htmlscrubber must be turned off for any page where the directive is used. + +This plugin depends on the [[!iki plugins/contrib/field]] plugin. + +## Activate the plugin + + # activate the plugin + add_plugins => [qw{goodstuff field jssearchfield ....}], + + # disable scrubbing for search page + htmlscrubber_skip => 'mysearchpage', + +## PREREQUISITES + + IkiWiki + IkiWiki::Plugin::field + HTML::Template + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/jssearchfield.pm> +* git repo at git://github.com/rubykat/ikiplugins.git diff --git a/doc/plugins/contrib/mandoc.mdwn b/doc/plugins/contrib/mandoc.mdwn index 15d2826ed..672a268cc 100644 --- a/doc/plugins/contrib/mandoc.mdwn +++ b/doc/plugins/contrib/mandoc.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=mandoc author="[[schmonz]]"]] -[[!template id=gitbranch branch=schmonz/master author="[[schmonz]]"]] +[[!template id=gitbranch branch=schmonz/mandoc author="[[schmonz]]"]] [[!tag type/format]] This plugin lets ikiwiki convert Unix man pages to HTML. It uses diff --git a/doc/plugins/contrib/mscgen.mdwn b/doc/plugins/contrib/mscgen.mdwn index 63d6512c3..792aaa4e3 100644 --- a/doc/plugins/contrib/mscgen.mdwn +++ b/doc/plugins/contrib/mscgen.mdwn @@ -1,4 +1,4 @@ -[[!template id=plugin name=mscgen author="[[users/Terry_Golubiewski]]"]] +[[!template id=plugin name=mscgen author="[[users/Tjgolubi]]"]] [[!tag type/widget]] ## NAME diff --git a/doc/plugins/contrib/newpage.mdwn b/doc/plugins/contrib/newpage.mdwn new file mode 100644 index 000000000..54c2f53d0 --- /dev/null +++ b/doc/plugins/contrib/newpage.mdwn @@ -0,0 +1,29 @@ +[[!template id=plugin name=newpage author="[[rubykat]]"]] +[[!tag type/web]] +[[!toc]] +## NAME + +IkiWiki::Plugin::newpage - add a "create new page" form to actions + +## SYNOPSIS + + # activate the plugin + add_plugins => [qw{goodstuff newpage ....}], + +## DESCRIPTION + +This plugin adds a new action to the "ACTIONS" section of a page; +a button labelled "create" and an input field next to it. + +The common way of creating a new page is to edit a different page +and add a link to the new page. However, there are some situations +where that is a nuisance; for example, where pages are listed using +a [[plugins/map]] directive. The newpage plugin enables +one to simply type the name of the new page, click the "create" button, +and one is then taken to the standard IkiWiki create-page form. + +## DOWNLOAD + +* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/newpage.pm> +* git repo at git://github.com/rubykat/ikiplugins.git + diff --git a/doc/plugins/contrib/newpage/discussion.mdwn b/doc/plugins/contrib/newpage/discussion.mdwn new file mode 100644 index 000000000..fb186463d --- /dev/null +++ b/doc/plugins/contrib/newpage/discussion.mdwn @@ -0,0 +1,10 @@ +How is this better than creating an inline with `rootpage` set, +which creates a similar new page form? I sometimes make the inline match +nothing, while still creating pages, in the odd cases where I have a map +or such displaying the pages. --[[Joey]] + +> I wanted something that would automatically be available on every page, but only when editing was enabled. +> One of the sites I maintain as webmaster (<http://www.constrainttec.com/>) has a two-stage publication process. The "working" site is on an internal server, where it is set up as a wiki that authorized users in the company can edit. When they're satisfied with the changes they've made, the "working" site gets pushed (with git) to the "production" site, which is on a different server. The ikiwiki setup for the production site has editing completely disabled, because it is the site which is exposed to the outside world. +> For that site, I want all sign that it's a wiki to be hidden. Therefore using an inline directive would be unsuitable. + +> --[[KathrynAndersen]] diff --git a/doc/plugins/contrib/pagespec_alias.mdwn b/doc/plugins/contrib/pagespec_alias.mdwn new file mode 100644 index 000000000..cb642ad33 --- /dev/null +++ b/doc/plugins/contrib/pagespec_alias.mdwn @@ -0,0 +1,28 @@ +[[!template id=plugin name=pagespec_alias author="[[Jon]]"]] +[[!tag type/meta]] + +The pagespec_alias plugin allows the administrator(s) of a wiki to define +[[PageSpec]] aliases: short names for PageSpecs to ease re-use. + +Within the setup file, the `pagespec_aliases` value is treated as a list +of key/value pairs. The keys define alias names, the values the pagespecs +to which they refer. + +For example: + + pagespec_aliases: + image: "*.png or *.jpg or *.jpeg or *.gif or *.ico" + helper: "*.css or *.js" + boring: "image() or helper() or internal(*)" + +With the above, you could use the pagespec aliases such as + + \[[!map pages="!boring()"]] + +To define a site map which excluded various page names which might be +uninteresting to include in a site map. + + +## Download + + * <https://github.com/jmtd/ikiwiki/blob/pagespec-alias/IkiWiki/Plugin/pagespec_alias.pm> diff --git a/doc/plugins/contrib/pandoc.mdwn b/doc/plugins/contrib/pandoc.mdwn index c8e2e9a94..264aafd95 100644 --- a/doc/plugins/contrib/pandoc.mdwn +++ b/doc/plugins/contrib/pandoc.mdwn @@ -2,5 +2,5 @@ This plugin enables Markdown processing using [Pandoc](http://johnmacfarlane.net/pandoc/). You can configure it for Pandoc to take over processing of all .mkdn files, or only files with a different extension. Given the features Pandoc has added over the past 6-12 months, this makes for a very powerful combination, e.g. with code block syntax highlighting and lots of options for how to process and display inline TeX. -This is an expanded and updated version of [[Jason Blevin|users/jasonblevins]]'s pandoc plugin. Get it and see further details at <https://github.com/profjim/pandoc-iki>. +This is an expanded and updated version of [[Jason Blevin|users/jasonblevins]]'s pandoc plugin. Get it and see further details at <https://github.com/dubiousjim/pandoc-iki>. diff --git a/doc/plugins/contrib/trail.mdwn b/doc/plugins/contrib/trail.mdwn index def91d85a..bfd4d3d0b 100644 --- a/doc/plugins/contrib/trail.mdwn +++ b/doc/plugins/contrib/trail.mdwn @@ -1,95 +1,133 @@ -[[!tag type/chrome patch]] -[[!template id=gitbranch branch=smcv/trail author="[[smcv]]"]] +[[!tag patch]] +[[!template id=gitbranch branch=smcv/trail3 author="[[smcv]]"]] -Available from [[smcv]]'s git repository, in the `trail` branch. This -plugin aims to solve [[todo/wikitrails]] in a simpler way. +Available from [[smcv]]'s git repository, in the `trail3` branch. This +plugin aims to solve [[todo/wikitrails]] in a simpler way; it can also be +used for [[navigation through blog posts|todo/Pagination_next_prev_links]]. -Updated, June 2011: +If you don't want to use a branch of ikiwiki, manual installation requires +these files (use the "raw" link in gitweb to download): -* removed `inline` integration for now +* [trail.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/IkiWiki/Plugin/trail.pm) + in an `IkiWiki/Plugin` subdirectory of your configured `plugindir` +* [page.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/templates/page.tmpl) + and + [trails.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/templates/trails.tmpl) + in your configured `templatedir`, or a `templates` subdirectory of your wiki repository +* the trail-related bits from the end of the + [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/doc/style.css) + (put them in your local.css) +* the trail-related bits at the end of the + [actiontabs](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/themes/actiontabs/style.css) + or [blueview/goldtype](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/themes/blueview/style.css) + stylesheets, if you use one of those themes (again, put them in your local.css) -* added `<link>` tags +The branch also includes [[todo/test_coverage]] machinery. -* switched from a custom data structure to using typed links +Demo: ----- +* [in use on entries in my blog](http://smcv.pseudorandom.co.uk/) +* [a demo trail based on links](http://demo.hosted.pseudorandom.co.uk/trail/) +* [a demo hybrid trail/inline](http://demo.hosted.pseudorandom.co.uk/trail2/) -[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]] +The page `e` is in both demo trails, to demonstrate how a page in more than +one trail looks. -It's sometimes useful to have "trails" of pages in a wiki, as a guided -tour, sequence of chapters etc. In this plugin, a trail is represented -by a page, and the pages in the trail are indicated by specially marked -links within that page. +The `smcv/trail2` branch is an older version of `trail3` which used typed links +as its data structure, resulting in timing-related limitations (it couldn't +select pages for the trail by using pagespecs, because pagespecs can't be +evaluated correctly until the scan stage has finished). -If using the default `page.tmpl`, each page automatically displays the -trails that it's a member of (if any), with links to the trail and to -the next and previous members. HTML `<link>` tags with the `prev`, -`next` and `up` relations are also generated. +Updated, November 2011: -The `traillink` [[ikiwiki/directive]] is used to record which pages -are in a trail, and simultaneously link to them. Alternatively, the -[[ikiwiki/directive/trailitem]] directive can be used to make an -invisible `traillink`. +* reinstated `inline` integration ([[report]] integration would probably be + pretty easy too, if this gets merged) +* switched from typed links back to a custom data structure to avoid + chicken/egg problems with ordering +* create typed links too, as a side-effect, but not when using an inline +* regression test with nearly full coverage +* CSS for the default anti-theme and all built-in themes (it looks nicest + in the default anti-theme and in actiontabs - the demo uses actiontabs) -## Directives +Known bugs: -(These will go to the appropriate pages in [[ikiwiki/directive]] if this -plugin is included in ikiwiki.) +* the blueview and goldtype CSS nearly work, but the alignment is a bit off -### trailitem +---- -The `trailitem` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]] -plugin. It is used like this: +[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]] +[[!tag type/chrome]] - \[[!trailitem some_other_page]] +This plugin provides the [[ikiwiki/directive/trailoptions]], +[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]], +[[ikiwiki/directive/trailitems]] +and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]]. -to add `some_other_page` to the trail represented by this page, without -generating a visible hyperlink. +It's sometimes useful to have "trails" of pages in a wiki where each +page links to the next and/or previous page. For instance, you could use +this for a guided tour, sequence of chapters, or sequence of blog posts. -### traillink +In this plugin, a trail is represented by a page, and the pages in the +trail are indicated by specially marked links within that page, or by +including groups of pages with a [[ikiwiki/directive]]. -The `traillink` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]] -plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the linked page to -the trail represented by the page containing the directive. +If using the default `page.tmpl`, each page automatically displays the +trails that it's a member of (if any), with links to the trail and to +the next and previous members. HTML `<link>` tags with the `prev`, +`next` and `up` relations are also generated. -In its simplest form, the first parameter is like the content of a WikiLink: +The [[ikiwiki/directive/trailoptions]] directive sets options for the +entire trail. - \[[!traillink some_other_page]] +Pages can be included in a trail in various ways: -The displayed text can also be overridden, either with a `|` symbol or with -a `text` parameter: +* The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]], + and at the same time adds the matching pages (from `pages` or `pagenames`) + to the trail. One use is to navigate through all posts in a blog: - \[[!traillink Click_here_to_start_the_trail|some_other_page]] - \[[!traillink some_other_page text="Click here to start the trail"]] + \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes + feedshow=10 quick=yes]] -### trailoptions + This directive only works if the [[!iki plugins/inline desc=inline]] + plugin is also enabled. -The `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]] -plugin. It sets options for the trail represented by this page. Example usage: +* The [[ikiwiki/directive/trailitems]] directive has optional `pages` and + `pagenames` options which behave the same as in [[inline]], but don't + produce any output in the page, so you can have trails that don't list + all their pages. - \[[!trailoptions sort="meta(title)" circular="no"]] +* The [[ikiwiki/directive/traillink]] directive makes a visible link + and also adds the linked page to the trail. This will typically be + used in a bullet list, but could also be in paragraph text: -The available options are: + * [[!traillink Introduction]] + * [[!traillink "Chapter 1"]] + * [[!traillink Chapter_2]] + * [[!traillink Appendix_A]] -* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the - items of the trail are ordered according to the first link to each item - found on the trail page + or -* `circular`: if set to `yes` or `1`, the trail is made into a loop by - making the last page's "next" link point to the first page, and the first - page's "previous" link point to the last page + To use this software you must \[[!traillink install]] it, + \[[!traillink configuration text="configure it"]], + and finally \[[!traillink running|run_it]]. ----- + This also counts as a [[ikiwiki/WikiLink]] for things like the `link()` + [[ikiwiki/PageSpec]] item. -## Future directions +* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail + like `traillink`, but produces an invisible link, rather like `\[[!tag]]`: -The current version of this plugin doesn't implement inline-based or -otherwise [[ikiwiki/PageSpec]]-based trails. This is difficult because -there's a circular dependency: + To use this software you must \[[!traillink install]] it, + \[[!trailitem installing_from_packages]] + \[[!trailitem installing_from_source]] + \[[!traillink configuration text="configure it"]], + and finally \[[!traillink running|run_it]]. + \[[!trailitem troubleshooting]] -* adding typed links should happen *before* scanning has finished, to - guarantee that they're available before the first page is rendered + Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though + there's no visible link. -* evaluating pagespecs should only happen *after* scanning has finished, - to guarantee that everything you might want to base a pagespec on - (`meta`, etc.) has been gathered by scanning +You can mix several of these directives in one page. The resulting +trail will contain all of the pages matched by any of the directives, +in the same order that the directives appear (unless you use the `sort` or +`reverse` options on `\[[!trailoptions]]`). diff --git a/doc/plugins/htmlscrubber.mdwn b/doc/plugins/htmlscrubber.mdwn index 98933d99e..08c81212b 100644 --- a/doc/plugins/htmlscrubber.mdwn +++ b/doc/plugins/htmlscrubber.mdwn @@ -10,9 +10,9 @@ Parser, documented at <http://web.archive.org/web/20110726052341/http://feedparser.org/docs/html-sanitization.html>. Notably it strips `style` and `link` tags, and the `style` attribute. -All attributes that can be used to specify an url are checked to make sure -that the url is in a known, safe scheme, and to block embedded javascript -in such urls. +Any attributes that could be used to specify a URL are checked to ensure +that they are known, safe schemes. It will also block embedded javascript +in such URLs. It uses the [[!cpan HTML::Scrubber]] perl module to perform its html sanitisation, and this perl module also deals with various entity encoding diff --git a/doc/plugins/mdwn.mdwn b/doc/plugins/mdwn.mdwn index ce1b6097a..8a7308305 100644 --- a/doc/plugins/mdwn.mdwn +++ b/doc/plugins/mdwn.mdwn @@ -8,9 +8,12 @@ This is the standard markup language used by ikiwiki, although some others are also available in other plugins. There are several implementations of markdown support that can be used by -this plugin. The [original version of -markdown](http://daringfireball.net/projects/markdown/) can be used, or the -[[!cpan Text::Markdown]] perl module. +this plugin. In order of preference: + +* [Discount](http://www.pell.portland.or.us/~orc/Code/discount/), + via the [[!cpan Text::Markdown::Discount]] perl module. +* The [[!cpan Text::Markdown]] perl module. +* The [original version of markdown](http://daringfireball.net/projects/markdown/). [[!cpan Text::MultiMarkdown]] can be used in order to use tables, footnotes, and other new features from the markdown variant called diff --git a/doc/plugins/theme.mdwn b/doc/plugins/theme.mdwn index ebbb0be8e..d2c62062b 100644 --- a/doc/plugins/theme.mdwn +++ b/doc/plugins/theme.mdwn @@ -9,3 +9,10 @@ of the themes included in ikiwiki. You can set the theme via the **theme** option in your config file (after enabling the plugin). Refresh the wiki after changing it to see the changes. + +Hints for theme builders +------------------------ + + * Start from an existing [[CSS file|css]], see also the [[css market]] for examples + * You can override the [[templates]] files by dropping them in a `templates` subdirectory + * Try to stick with modifying the CSS however, maintaining custom templates is harder diff --git a/doc/plugins/wmd/discussion.mdwn b/doc/plugins/wmd/discussion.mdwn index 42af97ec3..b57ef4057 100644 --- a/doc/plugins/wmd/discussion.mdwn +++ b/doc/plugins/wmd/discussion.mdwn @@ -59,3 +59,15 @@ copy [...] > It does not, however, have a markdown to html converter -- for > previewing it has to talk to the server with AJAX. > --[[Joey]] + +>> I've got pagedown working on my personal site (simon.kisikew.org) but I'm not sure how +>> I can inject the relevant <div>'s in the right place. They need to go **above** +>> the editing <textarea> . (Too bad about the licensing, it's rather nice.) +>> I had to do one minor change to it to have it inject itself into the page properly, +>> and that was to make this change in `Markdown.Editor.js`: +>> +>> `this.input = doc.getElementById("editcontent" + postfix);` +>> +>> on line 247. --[[simonraven]] + +>>> Well, I re-figured out that I needed a TMPL_VAR FOO in the template(s). --[[simonraven]] diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 9a5ca60a0..dcab041dc 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -1110,9 +1110,7 @@ to version control; the subdir can be added if so. Remove a file. The filename is relative to the root of the srcdir. Note that this should not commit the removal, it should only prepare for it -to be committed when `rcs_commit` (or `rcs_commit_staged`) is called. Note -that the new file may be in a new subdir that is not yet in version -control; the subdir can be added if so. +to be committed when `rcs_commit` (or `rcs_commit_staged`) is called. #### `rcs_rename($$)` |