template docu reorg
Remove wikitemplates page; fold its contents into templates page. Update all backlinks. Document new ability to put templates inside srcdir.master
parent
83703d2f4a
commit
7e79da7633
|
@ -10,7 +10,7 @@ If I have a <--#include virtual="foo" --> in some file, it gets stripped,
|
|||
> Anyway, it makes sense for the htmlscrubber to strip server-side
|
||||
> includes because otherwise your wiki could be attacked
|
||||
> by them being added to it. If you want to use both the htmlscrubber and
|
||||
> SSI together, I'd suggest you modify the [[wikitemplates]]
|
||||
> SSI together, I'd suggest you modify the [[templates]]
|
||||
> and put the SSI on there.
|
||||
>
|
||||
> Ie, `page.tmpl` has a
|
||||
|
|
|
@ -36,7 +36,7 @@ If you want to keep it as one form, then perhaps using some javascript to disabl
|
|||
> that allows modifying that form, but does not allow creating a separate
|
||||
> form. The best way to make it obvious how to use it currently is to just
|
||||
> disable password auth, then it's nice and simple. :-) Javascript is an
|
||||
> interesting idea. It's also possible to write a custom [[signin.tmpl wikitemplates]] that
|
||||
> interesting idea. It's also possible to write a custom [[templates]] that
|
||||
> is displayed instead of the regular signin form, and it should be
|
||||
> possible to use that to manually lay it out better than FormBuilder
|
||||
> manages with its automatic layout. --[[Joey]]
|
||||
|
@ -44,4 +44,4 @@ If you want to keep it as one form, then perhaps using some javascript to disabl
|
|||
> I've improved the form, I think it's more obvious now that the openid
|
||||
> stuff is separate. Good enough to call this [[done]]. I think. --[[Joey]]
|
||||
|
||||
>> Looks good, thanks! :-) -- [[AdamShand]]
|
||||
>> Looks good, thanks! :-) -- [[AdamShand]]
|
||||
|
|
|
@ -72,7 +72,7 @@ you would care to syndicate.
|
|||
|
||||
Ikiwiki aims to produce
|
||||
[valid XHTML 1.0](http://validator.w3.org/check?url=referer). Ikiwiki
|
||||
generates html using [[templates|wikitemplates]], and uses [[css]], so you
|
||||
generates html using [[templates]], and uses [[css]], so you
|
||||
can change the look and layout of all pages in any way you would like.
|
||||
|
||||
## [[Plugins]]
|
||||
|
|
|
@ -4,7 +4,7 @@ ikiwiki, and this documentation wiki, are licensed under the terms of the
|
|||
GNU [[GPL]], version 2 or later.
|
||||
|
||||
The parts of ikiwiki that become part of your own wiki (the [[basewiki]]
|
||||
pages (but not the smilies) and the [[templates|wikitemplates]]) are licensed
|
||||
pages (but not the smilies) and the [[templates]]) are licensed
|
||||
as follows:
|
||||
|
||||
> Redistribution and use in source and compiled forms, with or without
|
||||
|
|
|
@ -43,7 +43,7 @@ An example crontab:
|
|||
|
||||
# TEMPLATES
|
||||
|
||||
This command uses two [[template|wikitemplates]] to generate
|
||||
This command uses two [[templates]] to generate
|
||||
the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`.
|
||||
|
||||
# AUTHOR
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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"]]
|
||||
|
|
|
@ -1,7 +1,11 @@
|
|||
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.
|
||||
|
||||
|
|
|
@ -3,5 +3,5 @@
|
|||
|
||||
This plugin searches for [[SubPages|ikiwiki/subpage]] with a missing parent
|
||||
page, and generates the parent pages. The generated page content is
|
||||
controlled by the `autoindex.tmpl` [[template|wikitemplates]], which by
|
||||
controlled by the `autoindex.tmpl` [[template|templates]], which by
|
||||
default, uses a [[map]] to list the SubPages.
|
||||
|
|
|
@ -1,7 +1,7 @@
|
|||
I'm wanting a [[map]] (with indentation levels) showing page _titles_
|
||||
instead of page 'names'. As far as I can see, this is not an option with
|
||||
existing plugins - I can get a list of pages using [[inline]] and
|
||||
appropriate [[wikitemplates]], but that has no indentation and therefore
|
||||
appropriate [[templates]], but that has no indentation and therefore
|
||||
doesn't show structure well.
|
||||
|
||||
The quick way is to modify the map plugin to have a 'titles' option. The
|
||||
|
|
|
@ -3,8 +3,4 @@
|
|||
|
||||
This plugin provides the [[ikiwiki/directive/pagetemplate]]
|
||||
[[ikiwiki/directive]], which allows a page to be displayed
|
||||
using a different [[template|wikitemplates]] than the default.
|
||||
|
||||
This plugin can only use templates that are already installed in
|
||||
`/usr/share/ikiwiki/templates` (or wherever ikiwiki is configured to look for
|
||||
them). You can choose to use any .tmpl files in that directory.
|
||||
using a different [[template|templates]] than the default.
|
||||
|
|
|
@ -3,5 +3,5 @@
|
|||
|
||||
This plugin provides the [[ikiwiki/directive/template]] [[ikiwiki/directive]].
|
||||
With this plugin, you can set up templates, and cause them to be filled out
|
||||
and inserted into pages in the wiki. It's documented and existing templates
|
||||
are listed in the [[templates]] page.
|
||||
and inserted into pages in the wiki. Existing templates are listed in the
|
||||
[[templates]] page.
|
||||
|
|
|
@ -297,7 +297,7 @@ value is ignored.
|
|||
|
||||
hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
|
||||
|
||||
[[Templates|wikitemplates]] are filled out for many different things in
|
||||
[[Templates]] are filled out for many different things in
|
||||
ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
|
||||
a cgi. This hook allows modifying the variables available on those
|
||||
templates. The function is passed named parameters. The "page" and
|
||||
|
@ -313,7 +313,7 @@ a new custom parameter to the template.
|
|||
|
||||
hook(type => "templatefile", id => "foo", call => \&templatefile);
|
||||
|
||||
This hook allows plugins to change the [[template|wikitemplates]] that is
|
||||
This hook allows plugins to change the [[template|templates]] that is
|
||||
used for a page in the wiki. The hook is passed a "page" parameter, and
|
||||
should return the name of the template file to use (relative to the
|
||||
template directory), or undef if it doesn't want to change the default
|
||||
|
|
|
@ -1,17 +1,88 @@
|
|||
[[!meta robots="noindex, follow"]]
|
||||
[[!if test="enabled(template)"
|
||||
then="This wiki has templates **enabled**."
|
||||
else="This wiki has templates **disabled**."
|
||||
]]
|
||||
[[Ikiwiki]] uses many templates for many purposes. By editing its templates,
|
||||
you can fully customise this site.
|
||||
|
||||
Templates are files that can be filled out and inserted into pages in the
|
||||
wiki.
|
||||
[[!if test="enabled(template)" then="""
|
||||
## The template directive
|
||||
|
||||
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.
|
||||
"""]]
|
||||
[[!if test="enabled(template) and enabled(inline)" then="""
|
||||
|
||||
These templates are available for use with the template directive.
|
||||
|
||||
[[!inline pages="templates/* and !*/discussion" feeds=no archive=yes
|
||||
sort=title template=titlepage
|
||||
rootpage=templates postformtext="Add a new template named:"]]
|
||||
"""]]
|
||||
|
||||
[[!if test="enabled(edittemplate)" then="""
|
||||
## The edittemplate directive
|
||||
|
||||
The edittemplate directive can be used to make new pages default to
|
||||
containing text from a template, which can be filled as out the page is
|
||||
edited.
|
||||
"""]]
|
||||
|
||||
## Wiki templates
|
||||
|
||||
These templates are used to build the wiki. The aim is to keep almost all
|
||||
html out of ikiwiki and in the templates.
|
||||
|
||||
* `page.tmpl` - Used for displaying all regular wiki pages.
|
||||
* `misc.tmpl` - Generic template used for any page that doesn't
|
||||
have a custom template.
|
||||
* `editpage.tmpl` - Create/edit page.
|
||||
* `change.tmpl` - Used to create a page describing a change made to the wiki.
|
||||
* `passwordmail.tmpl` - Not a html template, this is used to
|
||||
generate a mail with an url the user can use to reset their password.
|
||||
* `rsspage.tmpl` - Used for generating rss feeds for [[blogs|blog]].
|
||||
* `rssitem.tmpl` - Used for generating individual items on rss feeds.
|
||||
* `atompage.tmpl` - Used for generating atom feeds for blogs.
|
||||
* `atomitem.tmpl` - Used for generating individual items on atom feeds.
|
||||
* `inlinepage.tmpl` - Used for adding a page inline in a blog
|
||||
page.
|
||||
* `archivepage.tmpl` - Used for listing a page in a blog archive page.
|
||||
* `microblog.tmpl` - Used for showing a microblogging post inline.
|
||||
* `blogpost.tmpl` - Used for a form to add a post to a blog (and a rss/atom links)
|
||||
* `feedlink.tmpl` - Used to add rss/atom links if blogpost.tmpl is not used.
|
||||
* `aggregatepost.tmpl` - Used by the [[plugins/aggregate]] plugin to create
|
||||
a page for a post.
|
||||
* `searchform.tmpl` - Used by the [[plugins/search]] plugin to add a search
|
||||
form to wiki pages.
|
||||
* `searchquery.tmpl` - This is an omega template, used by the
|
||||
[[plugins/search]] plugin.
|
||||
* `comment.tmpl` - This template is used to display a comment
|
||||
by the [[plugins/comments]] plugin.
|
||||
* `editcomment.tmpl` - This template is the comment post form for the
|
||||
[[plugins/comments]] plugin.
|
||||
* `commentmoderation.tmpl` - This template is used to produce the comment
|
||||
moderation form.
|
||||
* `recentchanges.tmpl` - This template is used for listing a change
|
||||
on the RecentChanges page.
|
||||
|
||||
[[!if test="enabled(pagetemplate)" then="""
|
||||
## The pagetemplate directive
|
||||
|
||||
The pagetemplate directive can allow individual pages to use a
|
||||
different template than `page.tmpl`.
|
||||
"""]]
|
||||
|
||||
## Template locations
|
||||
|
||||
Templates are located in `/usr/share/ikiwiki/templates` by default;
|
||||
the `templatedir` setting can be used to make another directory be
|
||||
searched first. Customized templates can also be placed inside the
|
||||
"templates/" directory in your wiki's source.
|
||||
|
||||
## Template syntax
|
||||
|
||||
Ikiwiki uses the HTML::Template module as its template engine. This
|
||||
supports things like conditionals and loops in templates and is pretty easy
|
||||
to learn. All you really need to know are a few things:
|
||||
|
||||
* To insert the value of a template variable, use `<TMPL_VAR variable>`.
|
||||
* To make a block of text conditional on a variable being set use
|
||||
`<TMPL_IF NAME="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 NAME="variable">text<TMPL_ELSE>other text</TMPL_IF>`
|
||||
|
||||
[[!meta robots="noindex, follow"]]
|
||||
|
|
|
@ -6,5 +6,5 @@ add a feed that contains all the comments posted to any page. Here's how:
|
|||
\[[!inline pages="internal(*/comment_*)" template=comment]]
|
||||
|
||||
The special [[ikiwiki/PageSpec]] matches all comments. The
|
||||
[[template|wikitemplates]] causes the comments to be displayed formatted
|
||||
[[template|templates]] causes the comments to be displayed formatted
|
||||
nicely.
|
||||
|
|
|
@ -17,7 +17,7 @@ The new tag file is then complied during the change phase.
|
|||
|
||||
*see git history of this page if you want the patch --[[smcv]]*
|
||||
|
||||
This uses a [[template|wikitemplates]] called `autotagpage.tmpl`, here is my template file:
|
||||
This uses a [[template|templates]] called `autotagpage.tmpl`, here is my template file:
|
||||
|
||||
\[[!inline pages="link(<TMPL_VAR TAG>)" archive="yes"]]
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@ This would allow setting:
|
|||
|
||||
templatedir => "$srcdir/templates",
|
||||
|
||||
.. and then the [[wikitemplates]] are managed like other wiki files; and
|
||||
.. and then the [[templates]] are managed like other wiki files; and
|
||||
like other wiki files, a change to them automatically updates dependent
|
||||
pages.
|
||||
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
Create some nice(r) stylesheets.
|
||||
|
||||
Should be doable w/o touching a single line of code, just
|
||||
editing the [[wikitemplates]] and/or editing [[style.css]].
|
||||
editing the [[templates]] and/or editing [[style.css]].
|
||||
|
||||
[[done]] ([[css_market]] ..)
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
> Another useful feature might be to be able to choose a different [[template|wikitemplates]]
|
||||
> Another useful feature might be to be able to choose a different [[template|templates]]
|
||||
> file for some pages; [[blog]] pages would use a template different from the
|
||||
> home page, even if both are managed in the same repository, etc.
|
||||
|
||||
|
|
|
@ -120,10 +120,11 @@ also be configured using a setup file.
|
|||
|
||||
* --templatedir dir
|
||||
|
||||
Specify the directory that the page [[templates|wikitemplates]] are stored in.
|
||||
Specify the directory that [[templates|templates]] are stored in.
|
||||
Default is `/usr/share/ikiwiki/templates`, or another location as configured at
|
||||
build time. If the templatedir is changed, missing templates will still
|
||||
be searched for in the default location as a fallback.
|
||||
be searched for in the default location as a fallback. Templates can also be
|
||||
placed in the "templates/" subdirectory of the srcdir.
|
||||
|
||||
Note that if you choose to copy and modify ikiwiki's templates, you will need
|
||||
to be careful to keep them up to date when upgrading to new versions of
|
||||
|
|
|
@ -1,52 +0,0 @@
|
|||
ikiwiki uses the HTML::Template module as its template engine. This
|
||||
supports things like conditionals and loops in templates and is pretty easy
|
||||
to learn.
|
||||
|
||||
The aim is to keep almost all html out of ikiwiki and in the templates.
|
||||
|
||||
It ships with some basic templates which can be customised. These are
|
||||
located in `/usr/share/ikiwiki/templates` by default; the `templatedir`
|
||||
setting can be used to make another directory be searched first.
|
||||
|
||||
* `page.tmpl` - Used for displaying all regular wiki pages.
|
||||
* `misc.tmpl` - Generic template used for any page that doesn't
|
||||
have a custom template.
|
||||
* `editpage.tmpl` - Create/edit page.
|
||||
* `change.tmpl` - Used to create a page describing a change made to the wiki.
|
||||
* `passwordmail.tmpl` - Not a html template, this is used to
|
||||
generate a mail with an url the user can use to reset their password.
|
||||
* `rsspage.tmpl` - Used for generating rss feeds for [[blogs|blog]].
|
||||
* `rssitem.tmpl` - Used for generating individual items on rss feeds.
|
||||
* `atompage.tmpl` - Used for generating atom feeds for blogs.
|
||||
* `atomitem.tmpl` - Used for generating individual items on atom feeds.
|
||||
* `inlinepage.tmpl` - Used for adding a page inline in a blog
|
||||
page.
|
||||
* `archivepage.tmpl` - Used for listing a page in a blog archive page.
|
||||
* `microblog.tmpl` - Used for showing a microblogging post inline.
|
||||
* `blogpost.tmpl` - Used for a form to add a post to a blog (and a rss/atom links)
|
||||
* `feedlink.tmpl` - Used to add rss/atom links if blogpost.tmpl is not used.
|
||||
* `aggregatepost.tmpl` - Used by the [[plugins/aggregate]] plugin to create
|
||||
a page for a post.
|
||||
* `searchform.tmpl` - Used by the [[plugins/search]] plugin to add a search
|
||||
form to wiki pages.
|
||||
* `searchquery.tmpl` - This is an omega template, used by the
|
||||
[[plugins/search]] plugin.
|
||||
* `comment.tmpl` - This template is used to display a comment
|
||||
by the [[plugins/comments]] plugin.
|
||||
* `editcomment.tmpl` - This template is the comment post form for the
|
||||
[[plugins/comments]] plugin.
|
||||
* `commentmoderation.tmpl` - This template is used to produce the comment
|
||||
moderation form.
|
||||
* `recentchanges.tmpl` - This template is used for listing a change
|
||||
on the RecentChanges page.
|
||||
|
||||
The [[plugins/pagetemplate]] plugin can allow individual pages to use a
|
||||
different template than `page.tmpl`.
|
||||
|
||||
The [[plugins/template]] plugin also uses templates, though those
|
||||
[[templates]] are typically stored as pages in the wiki, and are inserted
|
||||
into pages.
|
||||
|
||||
The [[plugins/edittemplate]] plugin is used to make new pages default to
|
||||
containing text from a template, which can be filled as out the page is
|
||||
edited.
|
|
@ -1,46 +0,0 @@
|
|||
## Place for local templates
|
||||
Where does one put any locally modified templates for an individual ikiwiki? --Ivan Z.
|
||||
|
||||
> You can put them whereever you like; the `templatedir` controls
|
||||
> where ikiwiki looks for them. --[[Joey]]
|
||||
|
||||
Thank you for your response! My question arose out of my intention to make
|
||||
custom templates for a wiki--specifically suited for the kind of content
|
||||
it will have--so, that would mean I would want to distribute them through
|
||||
git together with other content of the wiki. So, for this case the
|
||||
separation of conceptually ONE thing (the content, the templates, and the
|
||||
config option which orders to use these templates) into THREE separate
|
||||
files/repos (the main content repo, the repo with templates, and the config
|
||||
file) is not convenient: instead of distributing a single repo, I have to
|
||||
tell people to take three things if they want to replicate this wiki. How
|
||||
would you solve this inconvenience? Perhaps, a default location of the
|
||||
templates *inside* the source repo would do?--Ivan Z.
|
||||
|
||||
> I would avoid putting the templates in a subdirectory of the ikiwiki srcdir.
|
||||
> (I'd also avoid putting the ikiwiki setup file there.)
|
||||
> While it's safe to do either in some cases, there are configurations where
|
||||
> it's unsafe. For example, a malicious user could use attachment handling to
|
||||
> replace those files with their own, bad versions.
|
||||
>
|
||||
> So, two ideas for where to put the templatedir and ikiwiki setup.
|
||||
|
||||
> * The easiest option is to put your wiki content in a subdirectory
|
||||
> ("wiki", say) and point `srcdir` at that.
|
||||
> then you can have another subdirectory for the wikitemplates,
|
||||
> and put the setup file at the top.
|
||||
> * Another option if using git would be to have a separate branch,
|
||||
> in the same git repository, that holds wikitemplates and the setup file.
|
||||
> Then you check out the repository once to make the `srcdir` available,
|
||||
> and have a second checkout, of the other branch, to make the other stuff
|
||||
> available.
|
||||
>
|
||||
> Note that with either of these methods, you have to watch out if
|
||||
> giving other direct commit access to the repository. They could
|
||||
> still edit the setup file and templates, so only trusted users should
|
||||
> be given access. (It is, however, perfectly safe to let people edit
|
||||
> the wiki via the web, and is even safe to configure
|
||||
> [[tips/untrusted_git_push]] to such a repository.) --[[Joey]]
|
||||
|
||||
Thanks, that's a nice and simple idea: to have a subdirectory! I'll try it. --Ivan Z.
|
||||
|
||||
A [[!taglink wish|wishlist]]: the ikiwiki program could be improved so that it follows the same logic as git in looking for its config: it could ascend directories until it finds an `.ikiwiki/` directory with `.ikiwiki/setup` and then uses that configuration. Now I'm tired to always type `ikiwiki --setup path/to/the/setup --refresh` when working in my working clone of the sources; I'd like to simply type `ikiwiki` instead, and let it find the setup file. The default location to look for templates could also be made to be a sibling of the setup file: `.ikiwiki/templates/`. --Ivan Z.
|
Loading…
Reference in New Issue