diff options
Diffstat (limited to 'ikiwiki')
47 files changed, 1477 insertions, 0 deletions
diff --git a/ikiwiki/directive/aggregate.mdwn b/ikiwiki/directive/aggregate.mdwn new file mode 100644 index 0000000..ddfcd40 --- /dev/null +++ b/ikiwiki/directive/aggregate.mdwn @@ -0,0 +1,57 @@ +The `aggregate` directive is supplied by the [[!iki plugins/aggregate desc=aggregate]] plugin. +This plugin requires extra setup, specifically, a cron job. See the +plugin's 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 [[inline]] directive to create a blog of one or +more aggregated feeds. For example: + + \[[!inline pages="internal(example/*)"]] + +Note the use of `internal()` in the [[ikiwiki/PageSpec]] to match +aggregated pages. By default, aggregated pages are internal pages, +which prevents them from showing up directly in the wiki, and so this +special [[PageSpec]] is needed to match them. + +## 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/ikiwiki/directive/brokenlinks.mdwn b/ikiwiki/directive/brokenlinks.mdwn new file mode 100644 index 0000000..91bafe5 --- /dev/null +++ b/ikiwiki/directive/brokenlinks.mdwn @@ -0,0 +1,14 @@ +The `brokenlinks` directive is supplied by the [[!iki plugins/brokenlinks desc=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/ikiwiki/directive/calendar.mdwn b/ikiwiki/directive/calendar.mdwn new file mode 100644 index 0000000..cb40f88 --- /dev/null +++ b/ikiwiki/directive/calendar.mdwn @@ -0,0 +1,60 @@ +The `calendar` directive is supplied by the [[!iki plugins/calendar desc=calendar]] plugin. + +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"]] + +## setup + +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). + +While you can insert calendar directives anywhere on your wiki, including +in the sidebar, you'll also need to create these archive pages. They +typically use this directive to display a calendar, and also use [[inline]] +to display or list pages created in the given time frame. + +The `ikiwiki-calendar` command can be used to automatically generate the +archive pages. It also refreshes the wiki, updating the calendars to +highlight the current day. This command is typically run at midnight from +cron. + +An example crontab: + + 0 0 * * * ikiwiki-calendar ~/ikiwiki.setup "posts/* and !*/Discussion" + +## 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. + Calendars link to pages under here, with names like "2010/04" and + "2010". These pages can be automatically created using the + `ikiwiki-calendar` program. +* `year` - The year for which the calendar is requested. Defaults to the + current year. Can also use -1 to refer to last year, and so on. +* `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. Can also use -1 to refer to last month, and so on. +* `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 year calendar, number of months to place in + each row. Defaults to 3. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/color.mdwn b/ikiwiki/directive/color.mdwn new file mode 100644 index 0000000..553767f --- /dev/null +++ b/ikiwiki/directive/color.mdwn @@ -0,0 +1,25 @@ +The `color` directive is supplied by the [[!iki plugins/color desc=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/ikiwiki/directive/comment.mdwn b/ikiwiki/directive/comment.mdwn new file mode 100644 index 0000000..398130e --- /dev/null +++ b/ikiwiki/directive/comment.mdwn @@ -0,0 +1,40 @@ +The `comment` directive is supplied by the +[[!iki plugins/comments desc=comments]] plugin, and is used to add a comment +to a page. Typically, the directive is the only thing on a comment page, +and is filled out by the comment plugin when a user posts a comment. + +Example: + + \[[!comment format=mdwn + username="foo" + subject="Bar" + date="2009-06-02T19:05:01Z" + content=""" + Blah blah. + """ + ]] + +## usage + +The only required parameter is `content`, the others just add or override +metadata of the comment. + +* `content` - Text to display for the comment. + Note that [[directives|ikiwiki/directive]] + may not be allowed, depending on the configuration + of the comment plugin. +* `format` - Specifies the markup used for the content. +* `subject` - Subject for the comment. +* `date` - Date the comment was posted. Can be entered in + nearly any format, since it's parsed by [[!cpan TimeDate]] +* `username` - Used to record the username (or OpenID) + of a logged in commenter. +* `nickname` - Name to display for a logged in commenter. + (Optional; used for OpenIDs.) +* `ip` - Can be used to record the IP address of a commenter, + if they posted anonymously. +* `claimedauthor` - Records the name that the user entered, + if anonymous commenters are allowed to enter their (unverified) + name. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/commentmoderation.mdwn b/ikiwiki/directive/commentmoderation.mdwn new file mode 100644 index 0000000..8553b5b --- /dev/null +++ b/ikiwiki/directive/commentmoderation.mdwn @@ -0,0 +1,9 @@ +The `commentmoderation` directive is supplied by the +[[!iki plugins/comments desc=comments]] plugin, and is used to link +to the comment moderation queue. + +Example: + + \[[!commentmoderation desc="here is the comment moderation queue"]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/copy.mdwn b/ikiwiki/directive/copy.mdwn new file mode 100644 index 0000000..a0aa0ef --- /dev/null +++ b/ikiwiki/directive/copy.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/cutpaste]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/cut.mdwn b/ikiwiki/directive/cut.mdwn new file mode 100644 index 0000000..a0aa0ef --- /dev/null +++ b/ikiwiki/directive/cut.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/cutpaste]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/cutpaste.mdwn b/ikiwiki/directive/cutpaste.mdwn new file mode 100644 index 0000000..ca580e5 --- /dev/null +++ b/ikiwiki/directive/cutpaste.mdwn @@ -0,0 +1,50 @@ +The `copy`, `cut` and `paste` directives are supplied by the +[[!iki plugins/cutpaste desc=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: + + \[[!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/ikiwiki/directive/date.mdwn b/ikiwiki/directive/date.mdwn new file mode 100644 index 0000000..b89241e --- /dev/null +++ b/ikiwiki/directive/date.mdwn @@ -0,0 +1,16 @@ +The `date` directive is supplied by the [[!iki plugins/date desc=date]] plugin. + +This directive can be used to display a date on a page, using the same +display method that is used to display the modification date in the page +footer, and other dates in the wiki. This can be useful for consistency +of display, or if you want to embed parseable dates into the page source. + +Like the dates used by the [[meta]] directive, the date can be entered in +nearly any format, since it's parsed by [[!cpan TimeDate]]. + +For example, an update to a page with an embedded date stamp could look +like: + + Updated \[[!date "Wed, 25 Nov 2009 01:11:55 -0500"]]: mumble mumble + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/edittemplate.mdwn b/ikiwiki/directive/edittemplate.mdwn new file mode 100644 index 0000000..c486e82 --- /dev/null +++ b/ikiwiki/directive/edittemplate.mdwn @@ -0,0 +1,36 @@ +The `edittemplate` directive is supplied by the [[!iki plugins/edittemplate desc=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. To avoid +the directive displaying a note about the template being registered, add +"silent=yes". + +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, +like 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/ikiwiki/directive/flattr.mdwn b/ikiwiki/directive/flattr.mdwn new file mode 100644 index 0000000..5083005 --- /dev/null +++ b/ikiwiki/directive/flattr.mdwn @@ -0,0 +1,45 @@ +The `flattr` directive is supplied by the [[!iki plugins/flattr desc=flattr]] plugin. + +This directive allows easily inserting Flattr buttons onto wiki pages. + +Flattr supports both static buttons and javascript buttons. This directive +only creates dynamic javascript buttons. If you want to insert a static +Flattr button, you can simply copy the html code for it from Flattr, instead. +Note that this directive inserts javascript code into the page, that +loads more javascript code from Flattr.com. So only use it if you feel +comfortable with that. + +The directive can be used to display a button for a thing you have already +manually submitted to Flattr. In this mode, the only parameter you need to +include is the exact url to the thing that was submitted to Flattr. +(If the button is for the current page, you can leave that out.) For +example, this is the Flattr button for ikiwiki. Feel free to add it to all +your pages. ;) + + \[[!flattr url="http://ikiwiki.info/" button=compact]] + +The directive can also be used to create a button that automatically +submits a page to Flattr when a user clicks on it. In this mode you +need to include parameters to specify your uid, and a title, category, tags, +and description for the page. For example, this is a Flattr button for +a blog post: + + \[[!flattr uid=25634 title="my new blog post" category=text + tags="blog,example" description="This is a post on my blog."]] + +Here are all possible parameters you can pass to the Flattr directive. + +* `button` - Set to "compact" for a small button. +* `url` - The url to the thing to be Flattr'd. If omitted, defaults + to the url of the current page. +* `uid` - Your numeric Flattr userid. Not needed if the flattr plugin + has been configured with a global `flattr_userid`. +* `title` - A short title for the thing, to show on its Flattr page. +* `description` - A description of the thing, to show on its Flattr + page. +* `category` - One of: text, images, video, audio, software, rest. +* `tags` - A list of tags separated by a comma. +* `language` - A language code. +* `hidden` - Set to 1 to hide the button from listings on Flattr.com. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/format.mdwn b/ikiwiki/directive/format.mdwn new file mode 100644 index 0000000..7d11d22 --- /dev/null +++ b/ikiwiki/directive/format.mdwn @@ -0,0 +1,29 @@ +The `format` directive is supplied by the [[!iki plugins/format desc=format]] +plugin. + +The directive allows formatting a chunk of text using any available page +format. It takes two parameters. First is the type of format to use, +ie the extension that would be used for a standalone file of this type. +Second is the text to format. + +For example, this will embed an otl outline inside a page using mdwn or +some other format: + + \[[!format otl """ + foo + 1 + 2 + bar + 3 + 4 + """]] + +Note that if the highlight plugin is enabled, this directive can also be +used to display syntax highlighted code. Many languages and formats are +supported. For example: + + \[[!format perl """ + print "hello, world\n"; + """]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/fortune.mdwn b/ikiwiki/directive/fortune.mdwn new file mode 100644 index 0000000..45f533e --- /dev/null +++ b/ikiwiki/directive/fortune.mdwn @@ -0,0 +1,8 @@ +The `fortune` directive is supplied by the [[!iki plugins/fortune desc=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/ikiwiki/directive/graph.mdwn b/ikiwiki/directive/graph.mdwn new file mode 100644 index 0000000..4331872 --- /dev/null +++ b/ikiwiki/directive/graph.mdwn @@ -0,0 +1,23 @@ +The `graph` directive is supplied by the [[!iki plugins/graphviz desc=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/ikiwiki/directive/haiku.mdwn b/ikiwiki/directive/haiku.mdwn new file mode 100644 index 0000000..979f089 --- /dev/null +++ b/ikiwiki/directive/haiku.mdwn @@ -0,0 +1,15 @@ +The `haiku` directive is supplied by the [[!iki plugins/haiku desc=haiku]] plugin. + +This directive 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/ikiwiki/directive/if.mdwn b/ikiwiki/directive/if.mdwn new file mode 100644 index 0000000..2cbf70c --- /dev/null +++ b/ikiwiki/directive/if.mdwn @@ -0,0 +1,48 @@ +The `if` directive is supplied by the [[!iki plugins/conditional desc=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". + +In an `if` directive, 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/ikiwiki/directive/img.mdwn b/ikiwiki/directive/img.mdwn new file mode 100644 index 0000000..cda62b5 --- /dev/null +++ b/ikiwiki/directive/img.mdwn @@ -0,0 +1,39 @@ +The `img` directive is supplied by the [[!iki plugins/img desc=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`, `align`, `id`, `hspace`, and +`vspace` 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 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/ikiwiki/directive/inline.mdwn b/ikiwiki/directive/inline.mdwn new file mode 100644 index 0000000..c6a23ce --- /dev/null +++ b/ikiwiki/directive/inline.mdwn @@ -0,0 +1,121 @@ +The `inline` directive is supplied by the [[!iki plugins/inline desc=inline]] plugin. + +This is a directive that allows including one wiki page inside another. +The most common use of inlining is generating blogs and RSS or Atom feeds. + +Example: + + \[[!inline pages="blog/* and !*/Discussion" show="10" rootpage="blog"]] + +Any pages that match the specified [[PageSpec]] (in the example, any +[[SubPage]] of "blog") will be part of the blog, and the newest 10 +of them will appear in the page. Note that if files that are not pages +match the [[PageSpec]], they will be included in the feed using RSS +enclosures, which is useful for podcasting. + +The optional `rootpage` parameter tells the wiki that new posts to this +blog should default to being [[SubPages|SubPage]] of "blog", and enables a +form at the top of the blog that can be used to add new items. + +If you want your blog to have an archive page listing every post ever made +to it, you can accomplish that like this: + + \[[!inline pages="blog/* and !*/Discussion" archive="yes"]] + +You can even create an automatically generated list of all the pages on the +wiki, with the most recently added at the top, like this: + + \[[!inline pages="* and !*/Discussion" archive="yes"]] + +If you want to be able to add pages to a given blog feed by tagging them, +you can do that too. To tag a page, just make it link to a page or pages +that represent its tags. Then use the special `link()` [[PageSpec]] to match +all pages that have a given tag: + + \[[!inline pages="link(life)"]] + +Or include some tags and exclude others: + + \[[!inline pages="link(debian) and !link(social)"]] + +## usage + +There are many parameters you can use with the `inline` +directive. These are the commonly used ones: + +* `pages` - A [[PageSpec]] of the pages to inline. +* `show` - Specify the maximum number of matching pages to inline. + Default is 10, unless archiving, when the default is to show all. + Set to 0 to show all matching pages. +* `archive` - If set to "yes", only list page titles and some metadata, not + full contents. +* `description` - Sets the description of the rss feed if one is generated. + Defaults to the name of the wiki. +* `skip` - Specify a number of pages to skip displaying. Can be useful + to produce a feed that only shows archived pages. +* `postform` - Set to "yes" to enable a form to post new pages to a + blog. +* `postformtext` - Set to specify text that is displayed in a postform. +* `rootpage` - Enables the postform, and allows controling where + newly posted pages should go, by specifiying the page that + they should be a [[SubPage]] of. + +Here are some less often needed parameters: + +* `actions` - If set to "yes" add links to the bottom of the inlined pages + for editing and discussion (if they would be shown at the top of the page + itself). +* `rss` - controls generation of an rss feed. If the wiki is configured to + generate rss feeds by default, set to "no" to disable. If the wiki is + configured to `allowrss`, set to "yes" to enable. +* `atom` - controls generation of an atom feed. If the wiki is configured to + generate atom feeds by default, set to "no" to disable. If the wiki is + configured to `allowatom`, set to "yes" to enable. +* `feeds` - controls generation of all types of feeds. Set to "no" to + disable generating any feeds. +* `emptyfeeds` - Set to "no" to disable generation of empty feeds. + Has no effect if `rootpage` or `postform` is set. +* `template` - Specifies the template to fill out to display each inlined + page. By default the `inlinepage` template is used, while + the `archivepage` template is used for archives. Set this parameter to + use some other, custom template, such as the `titlepage` template that + only shows post titles or the `microblog` template, optimised for + microblogging. Note that you should still set `archive=yes` if + your custom template does not include the page content. +* `raw` - Rather than the default behavior of creating a blog, + 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. +* `sort` - Controls how inlined pages are [[sorted|pagespec/sorting]]. + The default is to sort the newest created pages first. +* `reverse` - If set to "yes", causes the sort order to be reversed. +* `feedshow` - Specify the maximum number of matching pages to include in + the rss/atom feeds. The default is the same as the `show` value above. +* `feedonly` - Only generate the feed, do not display the pages inline on + the page. +* `quick` - Build archives in quick mode, without reading page contents for + metadata. This also turns off generation of any feeds. +* `timeformat` - Use this to specify how to display the time or date for pages + in the blog. The format string is passed to the strftime(3) function. +* `feedpages` - A [[PageSpec]] of inlined pages to include in the rss/atom + feeds. The default is the same as the `pages` value above, and only pages + matched by that value are included, but some of those can be excluded by + specifying a tighter [[PageSpec]] here. +* `guid` - If a URI is given here (perhaps a UUID prefixed with `urn:uuid:`), + the Atom feed will have this as its `<id>`. The default is to use the URL + of the page containing the `inline` directive. +* `feedfile` - Can be used to change the name of the file generated for the + feed. This is particularly useful if a page contains multiple feeds. + For example, set "feedfile=feed" to cause it to generate `page/feed.atom` + and/or `page/feed.rss`. This option is not supported if the wiki is + configured not to use `usedirs`. +* `pagenames` - If given instead of `pages`, this is interpreted as a + space-separated list of links to pages (with the same + [[SubPage/LinkingRules]] as in a [[ikiwiki/WikiLink]]), and they are inlined + in exactly the order given: the `sort` and `pages` parameters cannot be used + in conjunction with this one. + +[[!meta robots="noindex, follow"]] + +A related directive is the [[ikiwiki/directive/edittemplate]] directive, which allows +default text for a new page to be specified. diff --git a/ikiwiki/directive/linkmap.mdwn b/ikiwiki/directive/linkmap.mdwn new file mode 100644 index 0000000..baa6fff --- /dev/null +++ b/ikiwiki/directive/linkmap.mdwn @@ -0,0 +1,29 @@ +The `linkmap` directive is supplied by the [[!iki plugins/linkmap desc=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. + +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. +* `connected` - Controls whether to include pages on the map that link to + no other pages (connected=no, the default), or to only show pages that + link to others (connected=yes). + +For best results, only a small set of pages should be mapped, since +otherwise the map can become very large, unwieldy, and complicated. +If too many pages are included, the map may get so large that graphviz +cannot render it. Using the `connected` parameter is a good way to prune +out pages that clutter the map. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/listdirectives.mdwn b/ikiwiki/directive/listdirectives.mdwn new file mode 100644 index 0000000..b41d27a --- /dev/null +++ b/ikiwiki/directive/listdirectives.mdwn @@ -0,0 +1,20 @@ +The `listdirectives` directive is supplied by the [[!iki plugins/listdirectives desc=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/ikiwiki/directive/map.mdwn b/ikiwiki/directive/map.mdwn new file mode 100644 index 0000000..4b64995 --- /dev/null +++ b/ikiwiki/directive/map.mdwn @@ -0,0 +1,21 @@ +The `map` directive is supplied by the [[!iki plugins/map desc=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]] directive). For example: + + \[[!map pages="* and !blog/* and !*/Discussion" show=title]] + + \[[!map pages="* and !blog/* and !*/Discussion" show=description]] + +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/ikiwiki/directive/meta.mdwn b/ikiwiki/directive/meta.mdwn new file mode 100644 index 0000000..1f5bde9 --- /dev/null +++ b/ikiwiki/directive/meta.mdwn @@ -0,0 +1,173 @@ +The `meta` directive is supplied by the [[!iki plugins/meta desc=meta]] plugin. + +This directive 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. + + An optional `sortas` parameter will be used preferentially when + [[ikiwiki/pagespec/sorting]] by `meta(title)`: + + \[[!meta title="The Beatles" sortas="Beatles, The"]] + + \[[!meta title="David Bowie" sortas="Bowie, David"]] + +* 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. + + An optional `sortas` parameter will be used preferentially when + [[ikiwiki/pagespec/sorting]] by `meta(author)`: + + \[[!meta author="Joey Hess" sortas="Hess, Joey"]] + +* authorurl + + Specifies an url for the author of a page. + +* description + + Specifies a short description for the page. This will be put in + the html header, and can also be displayed by eg, the [[map]] directive. + +* 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. This lets you use an ikiwiki page as your OpenID. + + By default this will delegate for both `openid` and `openid2`. To only + delegate for one, add a parameter such as `delegate=openid`. + + 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). + + 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 desc=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 desc=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 value is escaped, but its contents are not otherwise checked. + +* 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]]). + +* updated + + Specifies a fake modification time for a page, to be output into RSS and + Atom feeds. This is useful to avoid flooding aggregators that sort by + modification time, like Planet: for instance, when editing an old blog post + to add tags, you could set `updated` to be one second later than the original + value. The date/time can be given in any format that + [[!cpan TimeDate]] can understand, just like the `date` field. + +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 desc=htmlscrubber]] plugin is enabled, +since it can be used to insert unsafe content. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/more.mdwn b/ikiwiki/directive/more.mdwn new file mode 100644 index 0000000..5065519 --- /dev/null +++ b/ikiwiki/directive/more.mdwn @@ -0,0 +1,16 @@ +The `more` directive is supplied by the [[!iki plugins/more desc=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/ikiwiki/directive/orphans.mdwn b/ikiwiki/directive/orphans.mdwn new file mode 100644 index 0000000..b03f5ac --- /dev/null +++ b/ikiwiki/directive/orphans.mdwn @@ -0,0 +1,15 @@ +The `orphans` directive is supplied by the [[!iki plugins/orphans desc=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/ikiwiki/directive/pagecount.mdwn b/ikiwiki/directive/pagecount.mdwn new file mode 100644 index 0000000..0e6ca3c --- /dev/null +++ b/ikiwiki/directive/pagecount.mdwn @@ -0,0 +1,10 @@ +The `pagecount` directive is supplied by the [[!iki plugins/pagecount desc=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/ikiwiki/directive/pagestats.mdwn b/ikiwiki/directive/pagestats.mdwn new file mode 100644 index 0000000..d0e0e7b --- /dev/null +++ b/ikiwiki/directive/pagestats.mdwn @@ -0,0 +1,40 @@ +The `pagestats` directive is supplied by the [[!iki plugins/pagestats desc=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, with tags sized based +on frequency of use: + + \[[!pagestats pages="tags/*"]] + +Here's how to create a list of tags, sized by use as they would be in a +cloud. + + \[[!pagestats style="list" pages="tags/*"]] + +And here's how to create a table of all the pages on the wiki: + + \[[!pagestats style="table"]] + +The optional `among` parameter limits the pages whose outgoing links are +considered. For instance, to display a cloud of tags used on blog +entries, while ignoring other pages that use those tags, you could use: + + \[[!pagestats pages="tags/*" among="blog/posts/*"]] + +Or to display a cloud of tags related to Linux, you could use: + + \[[!pagestats pages="tags/* and not tags/linux" among="tagged(linux)"]] + +The optional `show` parameter limits display to the specified number of +pages. For instance, to show a table of the top ten pages with the most +links: + + \[[!pagestats style="table" show="10"]] + +The optional `class` parameter can be used to control the class +of the generated tag cloud `div` or page stats `table`. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/pagetemplate.mdwn b/ikiwiki/directive/pagetemplate.mdwn new file mode 100644 index 0000000..401b380 --- /dev/null +++ b/ikiwiki/directive/pagetemplate.mdwn @@ -0,0 +1,13 @@ +The `pagetemplate` directive is supplied by the [[!iki plugins/pagetemplate desc=pagetemplate]] plugin. + +This directive allows a page to be displayed using a different +[[template|templates]] than the default `page.tmpl` template. + +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. + + \[[!pagetemplate template="my_fancy.tmpl"]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/paste.mdwn b/ikiwiki/directive/paste.mdwn new file mode 100644 index 0000000..a0aa0ef --- /dev/null +++ b/ikiwiki/directive/paste.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/cutpaste]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/ping.mdwn b/ikiwiki/directive/ping.mdwn new file mode 100644 index 0000000..691c758 --- /dev/null +++ b/ikiwiki/directive/ping.mdwn @@ -0,0 +1,18 @@ +The `ping` directive is supplied by the [[!iki plugins/pinger desc=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 desc=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/ikiwiki/directive/poll.mdwn b/ikiwiki/directive/poll.mdwn new file mode 100644 index 0000000..6aa3d2c --- /dev/null +++ b/ikiwiki/directive/poll.mdwn @@ -0,0 +1,25 @@ +The `poll` directive is supplied by the [[!iki plugins/poll desc=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/ikiwiki/directive/polygen.mdwn b/ikiwiki/directive/polygen.mdwn new file mode 100644 index 0000000..e872634 --- /dev/null +++ b/ikiwiki/directive/polygen.mdwn @@ -0,0 +1,11 @@ +The `polygen` directive is supplied by the [[!iki plugins/polygen desc=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/ikiwiki/directive/postsparkline.mdwn b/ikiwiki/directive/postsparkline.mdwn new file mode 100644 index 0000000..318512e --- /dev/null +++ b/ikiwiki/directive/postsparkline.mdwn @@ -0,0 +1,45 @@ +The `postsparkline` directive is supplied by the [[!iki plugins/postsparkline desc=postsparkline]] plugin. + +This directive uses the [[!iki plugins/sparkline desc=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 from 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 formulae: + +* `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 year; the height represents how + many posts were made that year. + +The `time` parameter has a default value of "ctime", since formulae 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/ikiwiki/directive/progress.mdwn b/ikiwiki/directive/progress.mdwn new file mode 100644 index 0000000..529f1c3 --- /dev/null +++ b/ikiwiki/directive/progress.mdwn @@ -0,0 +1,18 @@ +The `progress` directive is supplied by the [[!iki plugins/progress desc=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 directive 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/ikiwiki/directive/shortcut.mdwn b/ikiwiki/directive/shortcut.mdwn new file mode 100644 index 0000000..29db86c --- /dev/null +++ b/ikiwiki/directive/shortcut.mdwn @@ -0,0 +1,9 @@ +The `shortcut` directive is supplied by the [[!iki plugins/shortcut desc=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/ikiwiki/directive/sidebar.mdwn b/ikiwiki/directive/sidebar.mdwn new file mode 100644 index 0000000..599695d --- /dev/null +++ b/ikiwiki/directive/sidebar.mdwn @@ -0,0 +1,20 @@ +The `sidebar` directive is supplied by the [[!iki plugins/sidebar desc=sidebar]] plugin. + +This directive can specify a custom sidebar to display on the page, +overriding any sidebar that is displayed globally. + +If no custom sidebar content is specified, it forces the sidebar page to +be used as the sidebar, even if the `global_sidebars` setting has been +used to disable use of the sidebar page by default. + +## examples + + \[[!sidebar content=""" + This is my custom sidebar for this page. + + \[[!calendar pages="posts/*"]] + """]] + + \[[!sidebar]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/sparkline.mdwn b/ikiwiki/directive/sparkline.mdwn new file mode 100644 index 0000000..e5a03f8 --- /dev/null +++ b/ikiwiki/directive/sparkline.mdwn @@ -0,0 +1,52 @@ +The `sparkline` directive is supplied by the [[!iki plugins/sparkline desc=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 +displayed 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/ikiwiki/directive/table.mdwn b/ikiwiki/directive/table.mdwn new file mode 100644 index 0000000..a6692f9 --- /dev/null +++ b/ikiwiki/directive/table.mdwn @@ -0,0 +1,50 @@ +The `table` directive is supplied by the [[!iki plugins/table desc=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. + +For tab-delimited tables (often obtained by copying and pasting from HTML +or a spreadsheet), `delimiter` must be set to a literal tab character. These +are difficult to type in most web browsers - copying and pasting one from +the table data is likely to be the easiest way. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/tag.mdwn b/ikiwiki/directive/tag.mdwn new file mode 100644 index 0000000..c8d9b98 --- /dev/null +++ b/ikiwiki/directive/tag.mdwn @@ -0,0 +1,35 @@ +The `tag` and `taglink` directives are supplied by the [[!iki plugins/tag desc=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. Also, since ikiwiki then knows where to put +tags, it will automatically create tag pages when new tags are used. + +Bear in mind that specifying a tagbase means you will need to incorporate it +into the `link()` [[ikiwiki/PageSpec]] you use: e.g., if your tagbase is +`tag`, you would match pages tagged "foo" with `link(tag/foo)`. + +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/ikiwiki/directive/taglink.mdwn b/ikiwiki/directive/taglink.mdwn new file mode 100644 index 0000000..dbfabf8 --- /dev/null +++ b/ikiwiki/directive/taglink.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/tag]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/template.mdwn b/ikiwiki/directive/template.mdwn new file mode 100644 index 0000000..6c50fa3 --- /dev/null +++ b/ikiwiki/directive/template.mdwn @@ -0,0 +1,87 @@ +The `template` directive is supplied by the [[!iki plugins/template desc=template]] plugin. + +The template directive allows wiki pages to be used as templates. +These templates can be filled out and inserted into other pages in the +wiki using the directive. The [[templates]] page lists templates +that can be used with this 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. + +## Using a template + +Generally, a value can include any markup that would be allowed in the wiki +page outside the template. Triple-quoting the value even allows quotes to +be included in it. 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. + * "I want to be an astronaut when I grow up." + * Really 8 and a half. + """]] + +## Creating a template + +The template is a regular wiki page, located in the `templates/` +subdirectory inside the source directory of the wiki. + +(Alternatively, templates can be stored in a directory outside the wiki, +as files with the extension ".tmpl". +By default, these are searched for in `/usr/share/ikiwiki/templates`; +the `templatedir` setting can be used to make another directory be searched +first.) + +The template uses the syntax used by the [[!cpan 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: + +* Each parameter you pass to the template directive will generate a + template variable. There are also some pre-defined variables like PAGE + and BASENAME. +* To insert the value of a variable, use `<TMPL_VAR variable>`. Wiki markup + in the value will first be converted to html. +* To insert the raw value of a variable, with wiki markup not yet converted + to html, use `<TMPL_VAR raw_variable>`. +* To make a block of text conditional on a variable being set use + `<TMPL_IF variable>text</TMPL_IF>`. +* To use one block of text if a variable is set and a second if it's not, + use `<TMPL_IF variable>text<TMPL_ELSE>other text</TMPL_IF>` + +Here's a sample template: + + <span class="infobox"> + Name: \[[<TMPL_VAR raw_name>]]<br /> + Age: <TMPL_VAR age><br /> + <TMPL_IF color> + Favorite color: <TMPL_VAR color><br /> + <TMPL_ELSE> + No favorite color.<br /> + </TMPL_IF> + <TMPL_IF notes> + <hr /> + <TMPL_VAR notes> + </TMPL_IF> + </span> + +The filled out template will be formatted the same as the rest of the page +that contains it, so you can include WikiLinks and all other forms of wiki +markup in the template. Note though that such WikiLinks will not show up as +backlinks to the page that uses the template. + +Note the use of "raw_name" inside the [[ikiwiki/WikiLink]] generator in the +example above. This ensures that if the name contains something that might +be mistaken for wiki markup, it's not converted to html before being +processed as a [[ikiwiki/WikiLink]]. + + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/testpagespec.mdwn b/ikiwiki/directive/testpagespec.mdwn new file mode 100644 index 0000000..dde7d99 --- /dev/null +++ b/ikiwiki/directive/testpagespec.mdwn @@ -0,0 +1,24 @@ +The `testpagespec` directive is supplied by the [[!iki plugins/testpagespec desc=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/ikiwiki/directive/teximg.mdwn b/ikiwiki/directive/teximg.mdwn new file mode 100644 index 0000000..992a3f6 --- /dev/null +++ b/ikiwiki/directive/teximg.mdwn @@ -0,0 +1,23 @@ +The `teximg` directive is supplied by the [[!iki plugins/teximg desc=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 chosen 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/ikiwiki/directive/toc.mdwn b/ikiwiki/directive/toc.mdwn new file mode 100644 index 0000000..bb1afa1 --- /dev/null +++ b/ikiwiki/directive/toc.mdwn @@ -0,0 +1,27 @@ +The `toc` directive is supplied by the [[!iki plugins/toc desc=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. + +To create a table of contents that only shows headers starting with a given +level, use the `startlevel` parameter. For example, to show only h2 and +smaller headers: + + \[[!toc startlevel=2]] + +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/ikiwiki/directive/toggle.mdwn b/ikiwiki/directive/toggle.mdwn new file mode 100644 index 0000000..db11f03 --- /dev/null +++ b/ikiwiki/directive/toggle.mdwn @@ -0,0 +1,34 @@ +The `toggle` and `toggleable` directives are supplied by the [[!iki plugins/toggle desc=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/ikiwiki/directive/toggleable.mdwn b/ikiwiki/directive/toggleable.mdwn new file mode 100644 index 0000000..5536f44 --- /dev/null +++ b/ikiwiki/directive/toggleable.mdwn @@ -0,0 +1,3 @@ +[[!meta redir=/ikiwiki/directive/toggle]] + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/directive/version.mdwn b/ikiwiki/directive/version.mdwn new file mode 100644 index 0000000..f1e2085 --- /dev/null +++ b/ikiwiki/directive/version.mdwn @@ -0,0 +1,12 @@ +The `version` directive is supplied by the [[!iki plugins/version desc=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"]] |