diff options
Diffstat (limited to 'doc/ikiwiki/directive')
26 files changed, 363 insertions, 39 deletions
diff --git a/doc/ikiwiki/directive/aggregate/discussion.mdwn b/doc/ikiwiki/directive/aggregate/discussion.mdwn new file mode 100644 index 000000000..ddece9746 --- /dev/null +++ b/doc/ikiwiki/directive/aggregate/discussion.mdwn @@ -0,0 +1,10 @@ +It would be awesome if table could aggregrate remote CSVs too. I want something like: + + !table file="http://cyclehireapp.com/cyclehirelive/cyclehire.csv" + +> Ok, but that has nothing to do with the aggregate plugin. File a +> [[todo]]? +> +> Anyway, it seems difficult, how would it know when the remote content +> had changed? Aggregate has its cron job support and has time stamps +> in rss feeds to rely on. --[[Joey]] diff --git a/doc/ikiwiki/directive/calendar.mdwn b/doc/ikiwiki/directive/calendar.mdwn index b2ac75b11..cb40f884e 100644 --- a/doc/ikiwiki/directive/calendar.mdwn +++ b/doc/ikiwiki/directive/calendar.mdwn @@ -28,7 +28,7 @@ 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: +cron. An example crontab: @@ -40,18 +40,21 @@ An example crontab: "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 +* `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. + 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. + 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 annual calendar, number of months to place in +* `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/doc/ikiwiki/directive/comment.mdwn b/doc/ikiwiki/directive/comment.mdwn index 21386dfc3..398130e2e 100644 --- a/doc/ikiwiki/directive/comment.mdwn +++ b/doc/ikiwiki/directive/comment.mdwn @@ -29,10 +29,12 @@ metadata of the comment. 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 anonmous commenters are allowed to enter their (unverified) + if anonymous commenters are allowed to enter their (unverified) name. [[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/commentmoderation.mdwn b/doc/ikiwiki/directive/commentmoderation.mdwn new file mode 100644 index 000000000..8553b5b17 --- /dev/null +++ b/doc/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/doc/ikiwiki/directive/date.mdwn b/doc/ikiwiki/directive/date.mdwn new file mode 100644 index 000000000..b89241e4c --- /dev/null +++ b/doc/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/doc/ikiwiki/directive/edittemplate.mdwn b/doc/ikiwiki/directive/edittemplate.mdwn index d731bdb47..c486e821b 100644 --- a/doc/ikiwiki/directive/edittemplate.mdwn +++ b/doc/ikiwiki/directive/edittemplate.mdwn @@ -21,7 +21,7 @@ something like: Details: The template page can also contain [[!cpan HTML::Template]] directives, -similar to other ikiwiki [[templates]]. Currently only one variable is +like other ikiwiki [[templates]]. Currently only one variable is set: `<TMPL_VAR name>` is replaced with the name of the page being created. diff --git a/doc/ikiwiki/directive/flattr.mdwn b/doc/ikiwiki/directive/flattr.mdwn new file mode 100644 index 000000000..5083005ce --- /dev/null +++ b/doc/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/doc/ikiwiki/directive/format.mdwn b/doc/ikiwiki/directive/format.mdwn index 23830e9cd..7d11d225f 100644 --- a/doc/ikiwiki/directive/format.mdwn +++ b/doc/ikiwiki/directive/format.mdwn @@ -22,7 +22,7 @@ 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 """ + \[[!format perl """ print "hello, world\n"; """]] diff --git a/doc/ikiwiki/directive/if.mdwn b/doc/ikiwiki/directive/if.mdwn index 2cbf70cdf..492adf499 100644 --- a/doc/ikiwiki/directive/if.mdwn +++ b/doc/ikiwiki/directive/if.mdwn @@ -43,6 +43,8 @@ with the following additional tests: * included() - Tests whether the page is being included onto another page. + Tests whether the page is being included onto another page, for example + via [[inline]] or [[map]]. Note that pages inserted into other pages + via [[template]] are not matched here. [[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/img.mdwn b/doc/ikiwiki/directive/img.mdwn index 94cc754bd..cda62b58f 100644 --- a/doc/ikiwiki/directive/img.mdwn +++ b/doc/ikiwiki/directive/img.mdwn @@ -18,7 +18,8 @@ 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` and `id` parameters. +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. diff --git a/doc/ikiwiki/directive/inline.mdwn b/doc/ikiwiki/directive/inline.mdwn index c6a23ce3c..22c18d9a1 100644 --- a/doc/ikiwiki/directive/inline.mdwn +++ b/doc/ikiwiki/directive/inline.mdwn @@ -75,6 +75,9 @@ Here are some less often needed parameters: disable generating any feeds. * `emptyfeeds` - Set to "no" to disable generation of empty feeds. Has no effect if `rootpage` or `postform` is set. +* `id` - Set to specify the value of the HTML `id` attribute for the + feed links or the post form. Useful if you have multiple forms in the + same page. * `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 @@ -116,6 +119,3 @@ Here are some less often needed parameters: 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/doc/ikiwiki/directive/inline/discussion.mdwn b/doc/ikiwiki/directive/inline/discussion.mdwn index be0665d04..5489d5f16 100644 --- a/doc/ikiwiki/directive/inline/discussion.mdwn +++ b/doc/ikiwiki/directive/inline/discussion.mdwn @@ -1,3 +1,10 @@ +## Combine inline and toggle + +Is it possible to combine the behaviour of toggle and inline? ie, have it present of list of 'headlines' which are created from seperate subpages which can be clicked to expand to the body of the inlined page. Thanks. + +-- Thiana + +--- ## How do you provide the per post discussion links in your own blog? > That's configured by the "actions" parameter to the inline directive. See @@ -124,3 +131,33 @@ My index page has: Else can you please suggest a smarter way of getting certain data out from pages for a inline index? --[[hendry]] + +## A different idea: smuggling hook routines in through %params. + +The part that fetches the inlined content is quite compact. It's just the if ($needcontent) {} chunk. Would a patch that accepts a perl sub smuggled through something like $params{inliner_} be accepted? If that param exists, call it instead of the current content of that chunk. Pass $page, %params, and $template. Receive $content, possibly seeing $template modified. The custom directives can add inliner_ to %params and call IkiWiki::preprocess_inline. I suppose IkiWiki::Plugin::inline could be modified to strip any *_ out of the directive's arguments to prevent any custom behavior from leaking into the inline directive. + +I'm about to try this for a CV/resume type of thing. I want only one element with a specific id out of the generated content (with a little post-processing). I don't need performance for my case. + +Update: Pretty much works. I need a way to skip sources, but inline shrinks the list of all pages *before* trying to form them. Next little bit... + +--[[JasonRiedy]] + +--- + +## Interaction of `show` and `feedshow` + +Reading the documentation I would think that `feedshow` does not +influence `show`. + + \[[!inline pages="./blog/*" archive=yes quick=yes feedshow=10 sort=title reverse=yes]] + +Only ten pages are listed in this example although `archive` is set to +yes. Removing `feedshow=10` all matching pages are shown. + +Is that behaviour intended? + +> Is something going wrong because `quick="yes"` [[»turns off generation of any feeds«|inline]]? --[[PaulePanter]] + +--[[PaulePanter]] + +>> Bug was that if feedshow was specified without show it limited to it incorrectly. Fixed. --[[Joey]] diff --git a/doc/ikiwiki/directive/linkmap.mdwn b/doc/ikiwiki/directive/linkmap.mdwn index 38cf0fd11..baa6fff61 100644 --- a/doc/ikiwiki/directive/linkmap.mdwn +++ b/doc/ikiwiki/directive/linkmap.mdwn @@ -7,9 +7,7 @@ graph showing the links between a set of pages in the wiki. Example usage: 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, unwieldy, and complicated. +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: @@ -18,5 +16,14 @@ directive: * `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/doc/ikiwiki/directive/map.mdwn b/doc/ikiwiki/directive/map.mdwn index 09c95a0c9..4b6499547 100644 --- a/doc/ikiwiki/directive/map.mdwn +++ b/doc/ikiwiki/directive/map.mdwn @@ -13,6 +13,8 @@ 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 !*/*/*"` diff --git a/doc/ikiwiki/directive/map/discussion.mdwn b/doc/ikiwiki/directive/map/discussion.mdwn index 062b4267a..b7ac17b1a 100644 --- a/doc/ikiwiki/directive/map/discussion.mdwn +++ b/doc/ikiwiki/directive/map/discussion.mdwn @@ -1,3 +1,14 @@ +### Sorting + +Is there a way to have the generated maps sorted by *title* instead of *filename* when show=title is used? +Thanks + +-- Thiana + +> [[bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used]] --[[Joey]] + +---- + Question: Is there a way to generate a listing that shows *both* title and description meta information? Currently, a \[\[!map ...]] shows only one of the two, but I'd like to generate a navigation that looks like a description list. For example: * This is the title meta information. @@ -72,3 +83,15 @@ Is there any way to do that? I don't mind mucking around with `\[[!meta]]` on e >>> I think that the ideas and code in >>> [[todo/tracking_bugs_with_dependencies]] might also handle this case. >>> --[[Joey]] + +---- + +I feel like this should be obvious, but I can't figure out how to sort numerically. + +I have `map pages="./* and !*/Discussion and !*/sidebar"` and a bunch of pages with names like 1, 2, 3, 11, 12, 1/1.1, 12/12.3 etc. I want to sort them numerically. I see lots of conversation implying there's a simple way to do it, but not how. + +> No, you can't: map can't currently use a non-default sort order. If it +> could, then you could use [[plugins/sortnaturally]]. There's a +> [[feature_request|todo/sort_parameter_for_map_plugin_and_directive]]; +> [[a_bug_references_it|bugs/map_sorts_by_pagename_and_not_title_when_show=title_is_used]]. +> --[[smcv]] diff --git a/doc/ikiwiki/directive/meta.mdwn b/doc/ikiwiki/directive/meta.mdwn index 000f461c9..6b381f138 100644 --- a/doc/ikiwiki/directive/meta.mdwn +++ b/doc/ikiwiki/directive/meta.mdwn @@ -7,7 +7,8 @@ Enter the metadata as follows: \[[!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. +also specifies some additional sub-parameters. You can have only one field +per `meta` directive, use more directives if you want to specify more fields. The field values are treated as HTML entity-escaped text, so you can include a quote in the text by writing `"` and so on. @@ -23,6 +24,13 @@ Supported fields: 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 @@ -37,14 +45,19 @@ Supported fields: 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 "description" of the page. You could use this to provide - a summary, for example, to be picked up by the [[map]] directive. + 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 @@ -64,6 +77,21 @@ Supported fields: \[[!meta stylesheet=somestyle rel="alternate stylesheet" title="somestyle"]] + + However, this will be scrubbed away if the + [[!iki plugins/htmlscrubber desc=htmlscrubber]] plugin is enabled, + since it can be used to insert unsafe content. + +* script + + Adds a script to a page. The script is treated as a wiki link to + a `.js` file in the wiki, so it cannot be used to add links to external + scripts. The optional `defer` and `async` keywords can be used to set + the corresponding HTML4 and HTML5 script options. Example: + + \[[!meta script=somescript defer async]] + + The tag is subject to scrubbing as with the stylesheet and link fields. * openid @@ -79,7 +107,7 @@ Supported fields: Example: - \\[[!meta openid="http://joeyh.myopenid.com/" + \[[!meta openid="http://joeyh.myopenid.com/" server="http://www.myopenid.com/server" xrds-location="http://www.myopenid.com/xrds?username=joeyh.myopenid.com""]] @@ -153,6 +181,15 @@ Supported fields: value. The date/time can be given in any format that [[!cpan TimeDate]] can understand, just like the `date` field. +* foaf + + Adds a Friend of a Friend ([FOAF](http://wiki.foaf-project.org/w/Autodiscovery)) + reference to a page. + + Example: + + \[[!meta foaf=foaf.rdf]] + 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, diff --git a/doc/ikiwiki/directive/more.mdwn b/doc/ikiwiki/directive/more.mdwn index 506551910..bda1427f3 100644 --- a/doc/ikiwiki/directive/more.mdwn +++ b/doc/ikiwiki/directive/more.mdwn @@ -11,6 +11,11 @@ leads to the full version of the page. Use it like this: If the `linktext` parameter is omitted it defaults to just "more". +An optional `pages` parameter can be used to specify a +[[ikiwiki/PageSpec]], and then the "more" link will only be displayed +when the page is inlined into a page matching that PageSpec, and otherwise +the full content shown. + Note that you can accomplish something similar using a [[toggle]] instead. [[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/pagestats.mdwn b/doc/ikiwiki/directive/pagestats.mdwn index f14c80b07..8d904f5a3 100644 --- a/doc/ikiwiki/directive/pagestats.mdwn +++ b/doc/ikiwiki/directive/pagestats.mdwn @@ -4,10 +4,16 @@ 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: +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"]] @@ -20,6 +26,15 @@ entries, while ignoring other pages that use those tags, you could use: Or to display a cloud of tags related to Linux, you could use: - \[[!pagestats pages="tags/* and not tags/linux" among="tagged(linux)"]] + \[[!pagestats pages="tags/* and !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/doc/ikiwiki/directive/pagestats/discussion.mdwn b/doc/ikiwiki/directive/pagestats/discussion.mdwn index 3c9dc7104..99029e88e 100644 --- a/doc/ikiwiki/directive/pagestats/discussion.mdwn +++ b/doc/ikiwiki/directive/pagestats/discussion.mdwn @@ -7,4 +7,12 @@ I would rather not find and create a page for every tag I have created or will c Thanks ----- +> Hello unknown person. + +> I think it would require a different approach to what "tags" are, and/or what "pagestats" are. The pagestats plugin gives statistical information about *pages*, so it requires the pages in question to exist before it can get information about them. The tags plugin creates links to tag *pages*, with the expectation that a human being will create said pages and put whatever content they want on them (such as describing what the tag is about, and a map linking back to the tagged pages). + +> The approach that [PmWiki](http://www.pmwiki.org) takes is that it enables the optional auto-creation of (empty) pages which match a particular "group" (set of sub-pages); thus one could set all the "tags/*" pages to be auto-created, creating a new tags/foo page the first time the \[[!tag foo]] directive is used. See [[todo/auto-create_tag_pages_according_to_a_template]] for more discussion on this idea. +> -- [[KathrynAndersen]] + +> Update: Ikiwiki can auto-create tags now, though it only defaults to +> doing so when tagbase is set. --[[Joey]] diff --git a/doc/ikiwiki/directive/pagetemplate.mdwn b/doc/ikiwiki/directive/pagetemplate.mdwn index 8ad901c1a..401b38099 100644 --- a/doc/ikiwiki/directive/pagetemplate.mdwn +++ b/doc/ikiwiki/directive/pagetemplate.mdwn @@ -1,17 +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 than -the default `page.tmpl` template. +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. -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/sidebar.mdwn b/doc/ikiwiki/directive/sidebar.mdwn new file mode 100644 index 000000000..599695d22 --- /dev/null +++ b/doc/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/doc/ikiwiki/directive/table.mdwn b/doc/ikiwiki/directive/table.mdwn index e27a94b7c..a6692f92c 100644 --- a/doc/ikiwiki/directive/table.mdwn +++ b/doc/ikiwiki/directive/table.mdwn @@ -6,8 +6,8 @@ or DSV (delimiter-separated values) format. ## examples \[[!table data=""" - Customer|Amount - Fulanito|134,34 + Customer |Amount + Fulanito |134,34 Menganito|234,56 Menganito|234,56 """]] @@ -42,4 +42,9 @@ cells. For example: 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/doc/ikiwiki/directive/table/discussion.mdwn b/doc/ikiwiki/directive/table/discussion.mdwn new file mode 100644 index 000000000..87d2e0cd1 --- /dev/null +++ b/doc/ikiwiki/directive/table/discussion.mdwn @@ -0,0 +1 @@ +The problem I have in my tables, is that some fields contain example HTML that needs to be escaped. diff --git a/doc/ikiwiki/directive/tag.mdwn b/doc/ikiwiki/directive/tag.mdwn index 64736f8cd..c8d9b9816 100644 --- a/doc/ikiwiki/directive/tag.mdwn +++ b/doc/ikiwiki/directive/tag.mdwn @@ -19,7 +19,8 @@ instead: 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. +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 @@ -28,7 +29,7 @@ into the `link()` [[ikiwiki/PageSpec]] you use: e.g., if your tagbase is If you want to override the tagbase for a particular tag, you can use something like this: - \[[!tag ./foo]] + \[[!tag /foo]] \[[!taglink /foo]] [[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/template.mdwn b/doc/ikiwiki/directive/template.mdwn index d538b69b1..9e3ae54df 100644 --- a/doc/ikiwiki/directive/template.mdwn +++ b/doc/ikiwiki/directive/template.mdwn @@ -1,18 +1,91 @@ The `template` directive is supplied by the [[!iki plugins/template desc=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 +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: +## 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. +## 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. When referring to templates outside the wiki source directory, the "id" +parameter is not interpreted as a pagespec, and you must include the full filename +of the template page, including the ".tmpl" extension. E.g.: + + \[[!template id=blogpost.tmpl]] + +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/doc/ikiwiki/directive/toc.mdwn b/doc/ikiwiki/directive/toc.mdwn index bf504dafc..bb1afa1ac 100644 --- a/doc/ikiwiki/directive/toc.mdwn +++ b/doc/ikiwiki/directive/toc.mdwn @@ -14,6 +14,12 @@ the `levels` parameter: 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. |