diff options
Diffstat (limited to 'doc/ikiwiki')
41 files changed, 1055 insertions, 0 deletions
diff --git a/doc/ikiwiki/directive/aggregate.mdwn b/doc/ikiwiki/directive/aggregate.mdwn new file mode 100644 index 000000000..f132c9746 --- /dev/null +++ b/doc/ikiwiki/directive/aggregate.mdwn @@ -0,0 +1,53 @@ +The `aggregate` directive is supplied by the [[!iki plugins/aggregate]] plugin. + +This plugin requires extra setup, specifically, a cron job. +See the plugin documentation for details. + +This directive allows content from other feeds to be aggregated into the wiki. +Aggregate a feed as follows: + + \[[!aggregate name="example blog" dir="example" + feedurl="http://example.com/index.rss" + url="http://example.com/" updateinterval="15"]] + +That example aggregates posts from the specified RSS feed, updating no +more frequently than once every 15 minutes (though possibly less +frequently, if the cron job runs less frequently than that), and puts a +page per post under the example/ directory in the wiki. + +You can then use ikiwiki's [[ikiwiki/blog]] support to create a blog of one or +more aggregated feeds. For example: + + \[[!inline pages="internal(example/*)"]] + +## usage + +Here are descriptions of all the supported parameters to the `aggregate` +directive: + +* `name` - A name for the feed. Each feed must have a unique name. + Required. +* `url` - The url to the web page for the feed that's being aggregated. + Required. +* `dir` - The directory in the wiki where pages should be saved. Optional, + if not specified, the directory is based on the name of the feed. +* `feedurl` - The url to the feed. Optional, if it's not specified ikiwiki + will look for feeds on the `url`. RSS and atom feeds are supported. +* `updateinterval` - How often to check for new posts, in minutes. Default + is 15 minutes. +* `expireage` - Expire old items from this feed if they are older than + a specified number of days. Default is to never expire on age. +* `expirecount` - Expire old items from this feed if there are more than + the specified number total. Oldest items will be expired first. Default + is to never expire on count. +* `tag` - A tag to tag each post from the feed with. A good tag to use is + the name of the feed. Can be repeated multiple times. The [[tag]] plugin + must be enabled for this to work. +* `template` - Template to use for creating the aggregated pages. Defaults to + aggregatepost. + +Note that even if you are using subversion or another revision control +system, pages created by aggregation will *not* be checked into revision +control. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/brokenlinks.mdwn b/doc/ikiwiki/directive/brokenlinks.mdwn new file mode 100644 index 000000000..2cde5b64a --- /dev/null +++ b/doc/ikiwiki/directive/brokenlinks.mdwn @@ -0,0 +1,14 @@ +The `brokenlinks` directive is supplied by the [[!iki plugins/brokenlinks]] plugin. + +This directive 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 [[ikiwiki/PageSpec]] specifying the +pages to search for broken links, default is search them all. + +Example: + + \[[!brokenlinks pages="* and !recentchanges"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/calendar.mdwn b/doc/ikiwiki/directive/calendar.mdwn new file mode 100644 index 000000000..5cbfa2dc6 --- /dev/null +++ b/doc/ikiwiki/directive/calendar.mdwn @@ -0,0 +1,46 @@ +The `calendar` directive is supplied by the [[!iki plugins/calendar]] plugin. +This plugin requires extra setup. See the plugin documentation for details. + +This directive displays a calendar, similar to the typical calendars shown on +some blogs. + +# examples + + \[[!calendar ]] + + \[[!calendar type="month" pages="blog/* and !*/Discussion"]] + + \[[!calendar type="year" year="2005" pages="blog/* and !*/Discussion"]] + +The calendar is essentially a fancy front end to archives of previous +pages, usually used for blogs. It can produce a calendar for a given month, +or a list of months for a given year. + +The month format calendar simply links to any page posted on each +day of the month. The year format calendar links to archive pages, with +names like `archives/2007` (for all of 2007) and `archives/2007/01` +(for January, 2007). For this to work, you'll need to create these archive +pages. They typically use [[inline]] to display or list pages created in +the given time frame. + +## usage + +* `type` - Used to specify the type of calendar wanted. Can be one of + "month" or "year". The default is a month view calendar. +* `pages` - Specifies the [[ikiwiki/PageSpec]] of pages to link to from the + month calendar. Defaults to "*". +* `archivebase` - Configures the base of the archives hierarchy. The + default is "archives". Note that this default can also be overridden + for the whole wiki by setting `archivebase` in ikiwiki's setup file. +* `year` - The year for which the calendar is requested. Defaults to the + current year. +* `month` - The numeric month for which the calendar is requested, in the + range 1..12. Used only for the month view calendar, and defaults to the + current month. +* `week_start_day` - A number, in the range 0..6, which represents the day + of the week that the month calendar starts with. 0 is Sunday, 1 is Monday, + and so on. Defaults to 0, which is Sunday. +* `months_per_row` - In the annual calendar, number of months to place in + each row. Defaults to 3. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/color.mdwn b/doc/ikiwiki/directive/color.mdwn new file mode 100644 index 000000000..be8907099 --- /dev/null +++ b/doc/ikiwiki/directive/color.mdwn @@ -0,0 +1,25 @@ +The `color` directive is supplied by the [[!iki plugins/color]] plugin. + +This directive can be used to color a piece of text on a page. +It can be used to set the foreground and/or background color of the text. + +You can use a color name (e.g. `white`) or HTML code (e.g. `#ffffff`) +to define colors. + +## examples + +Here the foreground color is defined as a word, while the background color +is defined as a HTML color code: + + \[[!color foreground=white background=#ff0000 text="White text on red background"]] + +The background color is missing, so the text is displayed on default +background: + + \[[!color foreground=white text="White text on default color background"]] + +The foreground is missing, so the text has the default foreground color: + + \[[!color background=#ff0000 text="Default color text on red background"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/copy.mdwn b/doc/ikiwiki/directive/copy.mdwn new file mode 100644 index 000000000..a0aa0ef7f --- /dev/null +++ b/doc/ikiwiki/directive/copy.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/cutpaste]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/cut.mdwn b/doc/ikiwiki/directive/cut.mdwn new file mode 100644 index 000000000..a0aa0ef7f --- /dev/null +++ b/doc/ikiwiki/directive/cut.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/cutpaste]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/cutpaste.mdwn b/doc/ikiwiki/directive/cutpaste.mdwn new file mode 100644 index 000000000..7c1d5b6cb --- /dev/null +++ b/doc/ikiwiki/directive/cutpaste.mdwn @@ -0,0 +1,56 @@ +The `copy`, `cut` and `paste` directives are supplied by the +[[!iki plugins/cutpaste]] plugin. + +With these directives you can store and recall pieces of text in a page: + + * `\[[!cut id=name text="text"]]` memorizes the text allowing to recall it + using the given ID. The text being cut is not included in the output. + * `\[[!copy id=name text="text"]]` memorizes the text allowing to recall it + using the given ID. The text being cut *is* included in the output. + * `\[[!paste id=name]]` is replaced by the previously memorized text. + +The text being cut, copied and pasted can freely include wiki markup, including +more calls to cut, copy and paste. + +You do not need to memorize the text before using it: a cut directive can +follow the paste directive that uses its text. In fact, this is quite useful +to postpone big blocks of text like long annotations and have a more natural +flow. For example: + + This plugin provides three directives: + + * \[[!toggle id="cut" text="cut"]] that cuts text + * \[[!toggle id="copy" text="copy"]] that copies text + * \[[!toggle id="paste" text="paste"]] that pastes text + + \[[!toggleable id="cut" text="\[[!paste id=cutlongdesc]]"]] + \[[!toggleable id="copy" text="\[[!paste id=copylongdesc]]"]] + \[[!toggleable id="paste" text="\[[!paste id=pastelongdesc]]"]] + + \[...some time later...] + + \[[!cut id=cutlongdesc text=""" + blah blah blah + """]] + \[[!cut id=copylongdesc text=""" + blah blah blah + """]] + \[[!cut id=pastelongdesc text=""" + blah blah blah + """]] + +This can potentially be used to create loops, but ikiwiki is clever and breaks +them. + +Since you can paste without using double quotes, copy and paste can be used to +nest directives that require multiline parameters inside each other: + + \[[!toggleable id=foo text=""" + \[[!toggleable id=bar text="\[[!paste id=baz]]"]] + """]] + + \[[!cut id=baz text=""" + multiline parameter! + """]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/edittemplate.mdwn b/doc/ikiwiki/directive/edittemplate.mdwn new file mode 100644 index 000000000..b3187ea66 --- /dev/null +++ b/doc/ikiwiki/directive/edittemplate.mdwn @@ -0,0 +1,34 @@ +The `edittemplate` directive is supplied by the [[!iki plugins/edittemplate]] plugin. + +This directive allows registering template pages, that provide default +content for new pages created using the web frontend. To register a +template, insert a [[ikiwiki/directive/template]] directive on some other page. + + \[[!edittemplate template="bugtemplate" match="bugs/*"]] + +In the above example, the page named "bugtemplate" is registered as a +template to be used when any page named "bugs/*" is created. + +Often the template page contains a simple skeleton for a particular type of +page. For the bug report pages in the above example, it might look +something like: + + Package: + Version: + Reproducible: y/n + Details: + +The template page can also contain [[!cpan HTML::Template]] directives, +similar to other ikiwiki [[templates]]. Currently only one variable is +set: `<TMPL_VAR name>` is replaced with the name of the page being +created. + +---- + +It's generally not a good idea to put the `edittemplate` directive in +the template page itself, since the directive would then be included as +part of the template on new pages, which would then in turn be registered +as templates. If multiple pages are registered as templates for a new page, +an arbitrary one is chosen, so that could get confusing. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/fortune.mdwn b/doc/ikiwiki/directive/fortune.mdwn new file mode 100644 index 000000000..5ba704b66 --- /dev/null +++ b/doc/ikiwiki/directive/fortune.mdwn @@ -0,0 +1,8 @@ +The `fortune` directive is supplied by the [[!iki plugins/fortune]] plugin. + +This just uses the `fortune` program to insert a fortune cookie into the page. +Usage: + + \[[!fortune ]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/graph.mdwn b/doc/ikiwiki/directive/graph.mdwn new file mode 100644 index 000000000..48eb7e340 --- /dev/null +++ b/doc/ikiwiki/directive/graph.mdwn @@ -0,0 +1,23 @@ +The `graph` directive is supplied by the [[!iki plugins/graphviz]] plugin. + +This directive allows embedding [graphviz](http://www.graphviz.org/) graphs in a +page. Example usage: + + \[[!graph src="a -> b -> c; a -> c;"]] + +Note that graphs will only show up in previews if your browser has +[[!wikipedia data: URI]] support, or if the same graph already exists on that +page. + +The `graph` directive supports the following parameters: + +- `src` - The graphviz source to render. +- `type` - The type of graph to render: `graph` or `digraph`. Defaults to + `digraph`. +- `prog` - The graphviz program to render with: `dot`, `neato`, `fdp`, `twopi`, + or `circo`. Defaults to `dot`. +- `height`, `width` - Limit the size of the graph to a given height and width, + in inches. You must specify both to limit the size; otherwise, graphviz will + choose a size, without any limit. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/haiku.mdwn b/doc/ikiwiki/directive/haiku.mdwn new file mode 100644 index 000000000..15d303bb7 --- /dev/null +++ b/doc/ikiwiki/directive/haiku.mdwn @@ -0,0 +1,15 @@ +The `haiku` directive is supplied by the [[!iki plugins/haiku]] plugin. + +This plugin allows inserting a randomly generated haiku into a wiki page. +Just type: + + \[[!haiku hint="argument"]] + +[[!haiku hint="argument test"]] + +The hint parameter can be omitted, it only provides the generator a hint of +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. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/if.mdwn b/doc/ikiwiki/directive/if.mdwn new file mode 100644 index 000000000..d6419b18b --- /dev/null +++ b/doc/ikiwiki/directive/if.mdwn @@ -0,0 +1,48 @@ +The `if` directive is supplied by the [[!iki plugins/conditional]] plugin. + +With this directive, you can make text be conditionally displayed on a page. +For example: + + \[[!if test="enabled(smiley)" + then="The smiley plugin is enabled :-)" + else="No smiley plugin here.."]] + +If the specified `test` succeeds, the `then` text will be displayed, +otherwise the `else` text will be displayed. The `else` part is optional. + +The `then` and `else` values can include any markup that would be allowed +in the wiki page outside the template. Triple-quoting the values even allows +quotes to be included. + +The `test` is a [[ikiwiki/PageSpec]]; if it matches any page in the wiki +then it succeeds. So you can do things like testing for the existence of a +page or pages, testing to see if any pages were created in a given month, +and so on. + +If you want the [[ikiwiki/PageSpec]] to only match against the page that +contains the conditional, rather than matching against all pages in the +wiki, set the "all" parameter to "no". + +The regular [[ikiwiki/PageSpec]] syntax is expanded with the following +additional tests: + +* enabled(plugin) + + Tests whether the specified plugin is enabled. + +* sourcepage(glob) + + Tests whether the glob matches the name of the page that contains the + conditional. + +* destpage(glob) + + Tests whether the glob matches the name of the page that is being built. + That might be different than the name of the page that contains the + conditional, if it's being inlined into another page. + +* included() + + Tests whether the page is being included onto another page. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/img.mdwn b/doc/ikiwiki/directive/img.mdwn new file mode 100644 index 000000000..ab3c07bfd --- /dev/null +++ b/doc/ikiwiki/directive/img.mdwn @@ -0,0 +1,38 @@ +The `img` directive is supplied by the [[!iki plugins/img]] plugin. + +This is an image handling directive. While ikiwiki supports inlining full-size +images by making a [[ikiwiki/WikiLink]] that points to the image, using +this directive you can easily scale down an image for inclusion onto a page, +providing a link to a full-size version. + +## usage + + \[[!img image1.jpg size="200x200" alt="clouds"]] + +The image file will be searched for using the same rules as used to find +the file pointed to by a [[ikiwiki/WikiLink]]. + +The `size` parameter is optional, defaulting to full size. Note that the +original image's aspect ratio is always preserved, even if this means +making the image smaller than the specified size. You can also specify only +the width or the height, and the other value will be calculated based on +it: "200x", "x200" + +You can also pass `alt`, `title`, `class` and `id` parameters. These are +passed through unchanged to the html img tag. If you include a `caption` +parameter, the caption will be displayed centered beneath the image. + +The `link` parameter is used to control whether the scaled down image links +to the full size version. By default it does; set "link=somepage" to link +to another page instead, or "link=no" to disable the link, or +"link=http://url" to link to a given url. + +You can also set default values that will be applied to all later images on +the page, unless overridden. Useful when including many images on a page. + + \[[!img defaults size=200x200 alt="wedding photo"]] + \[[!img photo1.jpg]] + \[[!img photo2.jpg]] + \[[!img photo3.jpg size=200x600]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/inline.mdwn b/doc/ikiwiki/directive/inline.mdwn new file mode 100644 index 000000000..4bf0de13d --- /dev/null +++ b/doc/ikiwiki/directive/inline.mdwn @@ -0,0 +1,12 @@ +The `inline` directive is supplied by the [[!iki plugins/inline]] plugin. + +This is a [[ikiwiki/directive]] that allows including one wiki page +inside another. For example: + + \[[!inline pages="blog/*"]] + +The most common use of inlining is generating blogs and RSS or Atom feeds. +See [[ikiwiki/blog]] for details. + + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/linkmap.mdwn b/doc/ikiwiki/directive/linkmap.mdwn new file mode 100644 index 000000000..ecc12bd77 --- /dev/null +++ b/doc/ikiwiki/directive/linkmap.mdwn @@ -0,0 +1,24 @@ +The `linkmap` directive is supplied by the [[!iki plugins/linkmap]] plugin. + +This directive uses [graphviz](http://www.graphviz.org/) to generate a +graph showing the links between a set of pages in the wiki. Example usage: + + \[[!linkmap pages="* and !blog/* and !*/Discussion"]] + +Only links between mapped pages will be shown; links pointing to or from +unmapped pages will be omitted. If the pages to include are not specified, +the links between all pages (and other files) in the wiki are mapped. For +best results, only a small set of pages should be mapped, since otherwise +the map can become very large, unweildy, and complicated. Also, the map is +rebuilt whenever one of the mapped pages is changed, which can make the +wiki a bit slow. + +Here are descriptions of all the supported parameters to the `linkmap` +directive: + +* `pages` - A [[ikiwiki/PageSpec]] of the pages to map. +* `height`, `width` - Limit the size of the map to a given height and width, + in inches. Both must be specified for the limiting to take effect, otherwise + the map's size is not limited. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/listdirectives.mdwn b/doc/ikiwiki/directive/listdirectives.mdwn new file mode 100644 index 000000000..0564159e0 --- /dev/null +++ b/doc/ikiwiki/directive/listdirectives.mdwn @@ -0,0 +1,20 @@ +The `listdirectives` directive is supplied by the [[!iki plugins/listdirectives]] plugin. + +This directive generates a list of available +[[directives|ikiwiki/directive]]. + + \[[!listdirectives]] + +There is one optional keyword argument, `generated`. Normally the +`listdirectives` directive will list all built in directives and directives +directly registered by plugins. With this keyword, `listdirectives` will +also list directives generated later. For example, all [[shortcuts]] are +directives generated in turn by the `shortcut` directive. They will only +be listed if the `generated` argument is supplied. + + \[[!listdirectives generated]] + +This extended list is often quite long, and often contains many +undocumented directives. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/map.mdwn b/doc/ikiwiki/directive/map.mdwn new file mode 100644 index 000000000..543470864 --- /dev/null +++ b/doc/ikiwiki/directive/map.mdwn @@ -0,0 +1,19 @@ +The `map` directive is supplied by the [[!iki plugins/map]] plugin. + +This directive generates a hierarchical page map for the wiki. Example usage: + + \[[!map pages="* and !blog/* and !*/Discussion"]] + +If the pages to include are not specified, all pages (and other files) in +the wiki are mapped. + +By default, the names of pages are shown in the map. The `show` parameter +can be used to show the titles or descriptions of pages instead (as set by +the [[meta]] plugin). For example: + + \[[!map pages="* and !blog/* and !*/Discussion" show=title]] + +Hint: To limit the map to displaying pages less than a certain level deep, +use a [[ikiwiki/PageSpec]] like this: `pages="* and !*/*/*"` + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/meta.mdwn b/doc/ikiwiki/directive/meta.mdwn new file mode 100644 index 000000000..b01dbfe76 --- /dev/null +++ b/doc/ikiwiki/directive/meta.mdwn @@ -0,0 +1,149 @@ +The `meta` directive is supplied by the [[!iki plugins/meta]] plugin. + +This plugin allows inserting arbitrary metadata into the source of a page. +Enter the metadata as follows: + + \[[!meta field="value"]] + \[[!meta field="value" param="value" param="value"]] + +The first form sets a given field to a given value, while the second form +also specifies some additional sub-parameters. + +The field values are treated as HTML entity-escaped text, so you can include +a quote in the text by writing `"` and so on. + +Supported fields: + +* title + + Overrides the title of the page, which is generally the same as the + page name. + + Note that if the title is overridden, a "title_overridden" variable will + be set to a true value in the template; this can be used to format things + differently in this case. + +* license + + Specifies a license for the page, for example, "GPL". Can contain + WikiLinks and arbitrary markup. + +* copyright + + Specifies the copyright of the page, for example, "Copyright 2007 by + Joey Hess". Can contain WikiLinks and arbitrary markup. + +* author + + Specifies the author of a page. + +* authorurl + + Specifies an url for the author of a page. + +* description + + Specifies a "description" of the page. You could use this to provide + a summary, for example, to be picked up by the [[map]] plugin. + +* permalink + + Specifies a permanent link to the page, if different than the page + generated by ikiwiki. + +* date + + Specifies the creation date of the page. The date can be entered in + nearly any format, since it's parsed by [[!cpan TimeDate]]. + +* stylesheet + + Adds a stylesheet to a page. The stylesheet is treated as a wiki link to + a `.css` file in the wiki, so it cannot be used to add links to external + stylesheets. Example: + + \[[!meta stylesheet=somestyle rel="alternate stylesheet" + title="somestyle"]] + +* openid + + Adds html <link> tags to perform OpenID delegation to an external + OpenID server (for `openid` and `openid2`). An optional `xrds-location` + parameter lets you specify the location of any [eXtensible Resource + DescriptorS](http://www.windley.com/archives/2007/05/using_xrds.shtml). + + This lets you use an ikiwiki page as your OpenID. Example: + + \\[[!meta openid="http://joeyh.myopenid.com/" + server="http://www.myopenid.com/server" + xrds-location="http://www.myopenid.com/xrds?username=joeyh.myopenid.com""]] + +* link + + Specifies a link to another page. This can be used as a way to make the + wiki treat one page as linking to another without displaying a user-visible + [[ikiwiki/WikiLink]]: + + \[[!meta link=otherpage]] + + It can also be used to insert a html <link> tag. For example: + + \[[!meta link="http://joeyh.myopenid.com/" rel="openid.delegate"]] + + However, this latter syntax won't be allowed if the + [[!iki plugins/htmlscrubber]] plugin is enabled, since it can be used to + insert unsafe content. + +* redir + + Causes the page to redirect to another page in the wiki. + + \[[!meta redir=otherpage]] + + Optionally, a delay (in seconds) can be specified. The default is to + redirect without delay. + + It can also be used to redirect to an external url. For example: + + \[[!meta redir="http://example.com/"]] + + However, this latter syntax won't be allowed if the + [[!iki plugins/htmlscrubber]] plugin is enabled, since it can be used to + insert unsafe content. + + For both cases, an anchor to jump to inside the destination page may also be + specified using the common `#ANCHOR` syntax. + +* robots + + Causes the robots meta tag to be written: + + \[[!meta robots="index, nofollow"]] + + Valid values for the attribute are: "index", "noindex", "follow", and + "nofollow". Multiple comma-separated values are allowed, but obviously only + some combinations make sense. If there is no robots meta tag, "index, + follow" is used as the default. + + The plugin escapes the value, but otherwise does not care about its + contents. In particular, it does not check the values against the set of + valid values but serves whatever you pass it. + +* guid + + Specifies a globally unique ID for a page. This guid should be a URI + (in particular, it can be `urn:uuid:` followed by a UUID, as per + [[!rfc 4122]]), and it will be used to identify the page's entry in RSS + and Atom feeds. If not given, the default is to use the page's URL as its + guid. + + This is mostly useful when a page has moved, to keep the guids for + pages unchanged and avoid_flooding_aggregators + (see [[!iki tips/howto_avoid_flooding_aggregators]]). + +If the field is not one of the above predefined fields, the metadata will be +written to the generated html page as a <meta> header. However, this +won't be allowed if the [[!iki plugins/htmlscrubber]] plugin is enabled, +since it can be used to insert unsafe content. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/more.mdwn b/doc/ikiwiki/directive/more.mdwn new file mode 100644 index 000000000..68c2cd39a --- /dev/null +++ b/doc/ikiwiki/directive/more.mdwn @@ -0,0 +1,16 @@ +The `more` directive is supplied by the [[!iki plugins/more]] plugin. + +This directive provides a way to have a "more" link on a post in a blog, that +leads to the full version of the page. Use it like this: + + \[[!more linktext="click for more" text=""" + This is the rest of my post. Not intended for people catching up on + their blogs at 30,000 feet. Because I like to make things + difficult. + """]] + +If the `linktext` parameter is omitted it defaults to just "more". + +Note that you can accomplish something similar using a [[toggle]] instead. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/orphans.mdwn b/doc/ikiwiki/directive/orphans.mdwn new file mode 100644 index 000000000..19b00f0ca --- /dev/null +++ b/doc/ikiwiki/directive/orphans.mdwn @@ -0,0 +1,15 @@ +The `orphans` directive is supplied by the [[!iki plugins/orphans]] plugin. + +This directive generates a list of possibly orphaned pages -- pages that no +other page links to. Example: + + \[[!orphans pages="* and !blog/*"]] + +The optional parameter "pages" can be a [[ikiwiki/PageSpec]] specifying the +pages to check for orphans, default is search them all. + +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. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/pagecount.mdwn b/doc/ikiwiki/directive/pagecount.mdwn new file mode 100644 index 000000000..f799a5d7f --- /dev/null +++ b/doc/ikiwiki/directive/pagecount.mdwn @@ -0,0 +1,10 @@ +The `pagecount` directive is supplied by the [[!iki plugins/pagecount]] plugin. + +This directive counts pages currently in the wiki. Example: + + \[[!pagecount pages="*"]] + +The optional parameter "pages" can be a [[ikiwiki/PageSpec]] specifying the +pages to count, default is to count them all. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/pagestats.mdwn b/doc/ikiwiki/directive/pagestats.mdwn new file mode 100644 index 000000000..de0419a03 --- /dev/null +++ b/doc/ikiwiki/directive/pagestats.mdwn @@ -0,0 +1,15 @@ +The `pagestats` directive is supplied by the [[!iki plugins/pagestats]] plugin. + +This directive can generate stats about how pages link to each other. It can +produce either a tag cloud, or a table counting the number of links to each +page. + +Here's how to use it to create a [[tag]] cloud: + + \[[!pagestats pages="tags/*"]] + +And here's how to create a table of all the pages on the wiki: + + \[[!pagestats style="table"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/pagetemplate.mdwn b/doc/ikiwiki/directive/pagetemplate.mdwn new file mode 100644 index 000000000..9c8e43962 --- /dev/null +++ b/doc/ikiwiki/directive/pagetemplate.mdwn @@ -0,0 +1,15 @@ +The `pagetemplate` directive is supplied by the [[!iki plugins/pagetemplate]] plugin. + +This directive allows a page to be created using a different wikitemplates. +The page text is inserted into the template, so the template controls the +overall look and feel of the wiki page. This is in contrast to the +[[ikiwiki/directive/template]] directive, which allows inserting templates +_into_ the body of a page. + +This directive can only reference templates that are already installed +by the system administrator, typically into the +`/usr/share/ikiwiki/templates` directory. Example: + + \[[!pagetemplate template="my_fancy.tmpl"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/paste.mdwn b/doc/ikiwiki/directive/paste.mdwn new file mode 100644 index 000000000..a0aa0ef7f --- /dev/null +++ b/doc/ikiwiki/directive/paste.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/cutpaste]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/ping.mdwn b/doc/ikiwiki/directive/ping.mdwn new file mode 100644 index 000000000..9eac60fd5 --- /dev/null +++ b/doc/ikiwiki/directive/ping.mdwn @@ -0,0 +1,18 @@ +The `ping` directive is supplied by the [[!iki plugins/pinger]] plugin. + +This directive allows ikiwiki to be configured to hit a URL each time it +updates the wiki. One way to use this is in conjunction with the [[!iki plugins/pingee]] +plugin to set up a loosely coupled mirror network, or a branched version of +a wiki. By pinging the mirror or branch each time the main wiki changes, it +can be kept up-to-date. + + \[[!ping from="http://mywiki.com/" + to="http://otherwiki.com/ikiwiki.cgi?do=ping"]] + +The "from" parameter must be identical to the url of the wiki that is doing +the pinging. This is used to prevent ping loops. + +The "to" parameter is the url to ping. The example shows how to ping +another ikiwiki instance. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/poll.mdwn b/doc/ikiwiki/directive/poll.mdwn new file mode 100644 index 000000000..e991dfaa9 --- /dev/null +++ b/doc/ikiwiki/directive/poll.mdwn @@ -0,0 +1,25 @@ +The `poll` directive is supplied by the [[!iki plugins/poll]] plugin. + +This directive allows you to create online polls in the wiki. Here's an +example use: + + \[[!poll 0 "red" 0 "green" 0 "blue"]] + +The numbers indicate how many users voted for that choice. When a user +votes for a choice in the poll, the page is modified and the number +incremented. + +While some basic precautions are taken to prevent users from accidentially +voting twice, this sort of poll should not be counted on to be very +accurate; all the usual concerns about web based polling apply. Unless the +page that the poll is in is locked, users can even edit the page and change +the numbers! + +Parameters: + +* `open` - Whether voting is still open. Set to "no" to close the poll to + voting. +* `total` - Show total number of votes at bottom of poll. Default is "yes". +* `percent` - Whether to display percents. Default is "yes". + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/polygen.mdwn b/doc/ikiwiki/directive/polygen.mdwn new file mode 100644 index 000000000..3facc131d --- /dev/null +++ b/doc/ikiwiki/directive/polygen.mdwn @@ -0,0 +1,11 @@ +The `polygen` directive is supplied by the [[!iki plugins/polygen]] plugin. + +This directive allows inserting text generated by polygen into a wiki page. +For example: + + \[[!polygen grammar="genius"]] + +It's also possible to specify a starting nonterminal for the grammar by +including `symbol="text"` in the directive. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/postsparkline.mdwn b/doc/ikiwiki/directive/postsparkline.mdwn new file mode 100644 index 000000000..398b48ef1 --- /dev/null +++ b/doc/ikiwiki/directive/postsparkline.mdwn @@ -0,0 +1,45 @@ +The `postsparkline` directive is supplied by the [[!iki plugins/postsparkline]] plugin. + +This directive uses the [[!iki plugins/sparkline]] plugin to create a +[[sparkline]] of statistics about a set of pages, such as posts to a blog. + +# examples + + Post interval: + \[[!postsparkline pages="blog/* and !*/Discussion" max=100 + formula=interval style=bar barwidth=2 barspacing=1 height=13]] + + Posts per month this year: + \[[!postsparkline pages="blog/* and !*/Discussion" max=12 + formula=permonth style=bar barwidth=2 barspacing=1 height=13]] + +# usage + +All options aside fron the `pages`, `max`, `formula`, `time`, and `color` +options are the same as in [[sparkline]] directive. + +You don't need to specify any data points (though you can if you want to). +Instead, data points are automatically generated based on the creation +times of pages matched by the specified `pages` [[ikiwiki/PageSpec]]. A +maximum of `max` data points will be generated. + +The `formula` parameter controls the formula used to generate data points. +Available forumlae: + +* `interval` - The height of each point represents how long it has been + since the previous post. +* `perday` - Each point represents a day; the height represents how + many posts were made that day. +* `permonth` - Each point represents a month; the height represents how + many posts were made that month. +* `peryear` - Each point represents a day; the height represents how + many posts were made that year. + +The `time` parameter has a default value of "ctime", since forumae use +the creation times of pages by default. If you instead want +them to use the modification times of pages, set it to "mtime". + +To change the color used to draw the sparkline, use the `color` parameter. +For example, "color=red". + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/progress.mdwn b/doc/ikiwiki/directive/progress.mdwn new file mode 100644 index 000000000..c477c435a --- /dev/null +++ b/doc/ikiwiki/directive/progress.mdwn @@ -0,0 +1,18 @@ +The `progress` directive is supplied by the [[!iki plugins/progress]] plugin. + +This directive generates a progress bar. + +There are two possible parameter sets. The first is a single parameter +"percent" which holds a percentage figure of how complete the progress bar is. + +The second possible set of parameters is a pair of [[ikiwiki/PageSpec]]s, +`totalpages` and `donepages`. The progress plugin counts the number of +pages in each pagespec and shows the percentage of the total pages that are +done. + +For example, to show what percentage of pages have +discussion pages: + + \[[!progress totalpages="* and !*/Discussion" donepages="*/Discussion"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/shortcut.mdwn b/doc/ikiwiki/directive/shortcut.mdwn new file mode 100644 index 000000000..14cdbdce7 --- /dev/null +++ b/doc/ikiwiki/directive/shortcut.mdwn @@ -0,0 +1,9 @@ +The `shortcut` directive is supplied by the [[!iki plugins/shortcut]] plugin. + +This directive allows external links to commonly linked to sites to be made +more easily using shortcuts. + +The available shortcuts are defined on the [[shortcuts]] page in +the wiki. The `shortcut` directive can only be used on that page. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/sparkline.mdwn b/doc/ikiwiki/directive/sparkline.mdwn new file mode 100644 index 000000000..d6eee7287 --- /dev/null +++ b/doc/ikiwiki/directive/sparkline.mdwn @@ -0,0 +1,52 @@ +The `sparkline` directive is supplied by the [[!iki plugins/sparkline]] plugin. + +This directive allows for embedding sparklines into wiki pages. A +sparkline is a small word-size graphic chart, that is designed to be +displayes alongside text. + +# examples + + \[[!sparkline 1 3 5 -3 10 0 width=40 height=16 + featurepoint="4,-3,red,3" featurepoint="5,10,green,3"]] + +This creates a simple line graph, graphing several points. +It will be drawn 40 pixels wide and 16 pixels high. The high point in the +line has a green marker, and the low point has a red marker. + + \[[!sparkline 1 -1(red) 1 -1(red) 1 1 1 -1(red) -1(red) style=bar barwidth=2 + barspacing=1 height=13]] + +This more complex example generates a bar graph. +The bars are 2 pixels wide, and separated by one pixel, and the graph is 13 +pixels tall. Width is determined automatically for bar graphs. The points +with negative values are colored red, instead of the default black. + +# usage + +The form for the data points is "x,y", or just "y" if the x values don't +matter. Bar graphs can also add "(color)" to specify a color for that bar. + +The following named parameters are recognised. Most of these are the same +as those used by the underlying sparkline library, which is documented in +more detail in [its wiki](http://sparkline.wikispaces.com/usage). + +* `style` - Either "line" (the default) or "bar". +* `width` - Width of the graph in pixels. Only needed for line graphs. +* `height` - Height of the graph in pixels. Defaults to 16. +* `barwidth` - Width of bars in a bar graph. Default is 1 pixel. +* `barspacing` - Spacing between bars in a bar graph, in pixels. Default is + 1 pixel. +* `ymin`, `ymax` - Minimum and maximum values for the Y axis. This is + normally calculated automatically, but can be explicitly specified to get + the same values for multiple related graphs. +* `featurepoint` - Adds a circular marker to a line graph, with optional + text. This can be used to label significant points. + + The value is a comma-delimited list of parameters specifying the feature + point: X value, Y value, color name, circle diameter, text (optional), + and text location (optional). Example: `featurepoint="3,5,blue,3"` + + Available values for the text location are: "top", "right", "bottom", and + "left". + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/table.mdwn b/doc/ikiwiki/directive/table.mdwn new file mode 100644 index 000000000..0d1af1249 --- /dev/null +++ b/doc/ikiwiki/directive/table.mdwn @@ -0,0 +1,45 @@ +The `table` directive is supplied by the [[!iki plugins/table]] plugin. + +This directive can build HTML tables from data in CSV (comma-separated values) +or DSV (delimiter-separated values) format. + +## examples + + \[[!table data=""" + Customer|Amount + Fulanito|134,34 + Menganito|234,56 + Menganito|234,56 + """]] + + \[[!table class="book_record" format=csv file="data/books/record1"]] + +In this second example the `record1` page should be similar to: + + "Title","Perl Best Practices" + "Author","Damian Conway" + "Publisher","O’Reilly" + +To make a cell span multiple columns, follow it with one or more empty +cells. For example: + + \[[!table data=""" + left||right| + a|b|c|d + this cell spans 4 columns||| + """]] + +## usage + +* `data` - Values for the table. +* `file` - A file in the wiki containing the data. +* `format` - The format of the data, either "csv", "dsv", or "auto" + (the default). +* `delimiter` - The character used to separate fields. By default, + DSV format uses a pipe (`|`), and CSV uses a comma (`,`). +* `class` - A CSS class for the table html element. +* `header` - By default, or if set to "row", the first data line is used + as the table header. Set it to "no" to make a table without a header, or + "column" to make the first column be the header. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/tag.mdwn b/doc/ikiwiki/directive/tag.mdwn new file mode 100644 index 000000000..a6e1833a4 --- /dev/null +++ b/doc/ikiwiki/directive/tag.mdwn @@ -0,0 +1,30 @@ +The `tag` and `taglink` directives are supplied by the [[!iki plugins/tag]] plugin. + +These directives allow tagging pages. List tags as follows: + + \[[!tag tech life linux]] + +The tags work the same as if you had put a (hidden) [[ikiwiki/WikiLink]] on +the page for each tag, so you can use a [[ikiwiki/PageSpec]] match all +pages that are tagged with a given tag, for example. The tags will also +show up on blog entries and at the bottom of the tagged pages, as well as +in RSS and Atom feeds. + +If you want a visible [[ikiwiki/WikiLink]] along with the tag, use taglink +instead: + + \[[!taglink foo]] + \[[!taglink tagged_as_foo|foo]] + +Note that if the wiki is configured to use a tagbase, then the tags will be +located under a base directory, such as "tags/". 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. + +If you want to override the tagbase for a particular tag, you can use +something like this: + + \[[!tag ./foo]] + \[[!taglink /foo]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/taglink.mdwn b/doc/ikiwiki/directive/taglink.mdwn new file mode 100644 index 000000000..dbfabf8e1 --- /dev/null +++ b/doc/ikiwiki/directive/taglink.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/tag]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/template.mdwn b/doc/ikiwiki/directive/template.mdwn new file mode 100644 index 000000000..38b7e3c5e --- /dev/null +++ b/doc/ikiwiki/directive/template.mdwn @@ -0,0 +1,18 @@ +The `template` directive is supplied by the [[!iki plugins/template]] plugin. + +[[Templates]] are files that can be filled out and inserted into pages in the +wiki, by using the template directive. The directive has an `id` parameter +that identifies the template to use. The remaining parameters are used to +fill out the template. + +Example: + + \[[!template id=note text="""Here is the text to insert into my note."""]] + +This fills out the `note` template, filling in the `text` field with +the specified value, and inserts the result into the page. + +For a list of available templates, and details about how to create more, +see the [[templates]] page. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/testpagespec.mdwn b/doc/ikiwiki/directive/testpagespec.mdwn new file mode 100644 index 000000000..401353e89 --- /dev/null +++ b/doc/ikiwiki/directive/testpagespec.mdwn @@ -0,0 +1,24 @@ +The `testpagespec` directive is supplied by the [[!iki plugins/testpagespec]] plugin. + +This directive allows testing a [[ikiwiki/PageSpec]] to see if it matches a +page, and to see the part that matches, or causes the match to fail. + +Example uses: + + \[[!testpagespec pagespec="foopage and barpage" match="foopage"]] + +This will print out something like "no match: barpage does not match +foopage", highlighting which part of the [[ikiwiki/PageSpec]] is causing +the match to fail. + + \[[!testpagespec pagespec="foopage or !bar*" match="barpage"]] + +This will print out something like "no match: bar* matches barpage", since +the part of the [[ikiwiki/PageSpec]] that fails is this negated match. + + \[[!testpagespec pagespec="foopage or barpage" match="barpage"]] + +This will print out something like "match: barpage matches barpage", +indicating the part of the [[ikiwiki/PageSpec]] that caused it to match. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/teximg.mdwn b/doc/ikiwiki/directive/teximg.mdwn new file mode 100644 index 000000000..bd040c9cf --- /dev/null +++ b/doc/ikiwiki/directive/teximg.mdwn @@ -0,0 +1,23 @@ +The `teximg` directive is supplied by the [[!iki plugins/teximg]] plugin. + +This directive renders LaTeX formulas into images. + +## examples + + \[[!teximg code="\frac{1}{2}"]] + \[[!teximg code="E = - \frac{Z^2 \cdot \mu \cdot e^4}{32\pi^2 \epsilon_0^2 \hbar^2 n^2}" ]] + +To scale the image, use height=x: + + \[[!teximg code="\frac{1}{2}" height="17"]] + \[[!teximg code="\frac{1}{2}" height="8"]] + +If no height is choosen the default height 12 is used. Valid heights are: 8, 9, +10, 11, 12, 14, 17, 20. If another height is entered, the closest available +height is used. + +To add an alt text to the image, use alt="text": + + \[[!teximg code="\frac{1}{2}" alt="1/2"]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/toc.mdwn b/doc/ikiwiki/directive/toc.mdwn new file mode 100644 index 000000000..94b0fe1af --- /dev/null +++ b/doc/ikiwiki/directive/toc.mdwn @@ -0,0 +1,21 @@ +The `toc` directive is supplied by the [[!iki plugins/toc]] plugin. + +Add a table of contents to a page: + + \[[!toc ]] + +The table of contents will be automatically generated based on the +headers of the page. By default only the largest headers present on the +page will be shown; to control how many levels of headers are shown, use +the `levels` parameter: + + \[[!toc levels=2]] + +The toc directive will take the level of the first header as the topmost +level, even if there are higher levels seen later in the file. + +The table of contents will be created as an ordered list. If you want +an unordered list instead, you can change the list-style in your local +style sheet. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/toggle.mdwn b/doc/ikiwiki/directive/toggle.mdwn new file mode 100644 index 000000000..5729fca11 --- /dev/null +++ b/doc/ikiwiki/directive/toggle.mdwn @@ -0,0 +1,34 @@ +The `toggle` and `toggleable` directives are supplied by the [[!iki plugins/toggle]] plugin. + +With these directives you can create links on pages that, when clicked, toggle +display of other parts of the page. + +It uses javascript to accomplish this; browsers without javascript will +always see the full page content. + +Example use: + + \[[!toggle id="ipsum" text="show"]] + + \[[!toggleable id="ipsum" text=""" + Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do + eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim + ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut + aliquip ex ea commodo consequat. + + [[!toggle id="ipsum" text="hide"]] + """]] + +Note that you can include wiki markup in the toggleable text, +including even additional toggles, as shown in the above example. + +Also, the toggle and the togglable definitions do not need to be next to +each other, but can be located anywhere on the page. There can also be +mutiple toggles that all toggle a single togglable. + +The id has a default value of "default", so can be omitted in simple cases. + +If you'd like a toggleable to be displayed by default, and toggle to +hidden, then pass a parameter "open=yes" when setting up the toggleable. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/toggleable.mdwn b/doc/ikiwiki/directive/toggleable.mdwn new file mode 100644 index 000000000..5536f4489 --- /dev/null +++ b/doc/ikiwiki/directive/toggleable.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/toggle]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/version.mdwn b/doc/ikiwiki/directive/version.mdwn new file mode 100644 index 000000000..8ab96d045 --- /dev/null +++ b/doc/ikiwiki/directive/version.mdwn @@ -0,0 +1,12 @@ +The `version` directive is supplied by the [[!iki plugins/version]] plugin. + +This directive allows inserting the version of ikiwiki onto a page. + +Whenever ikiwiki is upgraded to a new version, the page will be rebuilt, +updating the version number. + +Use is simple: + + \[[!version ]] + +[[!meta robots="noindex, follow"]] |