path: root/doc/templates.mdwn

[[Ikiwiki]] uses many templates for many purposes. By editing its templates,
you can fully customise its appearance, and avoid duplicate content.

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 to modify templates is this:

* 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 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>`

[[!if test="enabled(template) or enabled(edittemplate)" then="""
## template pages

Template pages are regular wiki pages that are used as templates for other
pages.
"""]]

[[!if test="enabled(template)" then="""
The [[!iki ikiwiki/directive/template desc="template directive"]] allows
template pages to be filled out and inserted into other pages in the wiki.
"""]]

[[!if test="enabled(edittemplate)" then="""
The [[!iki ikiwiki/directive/edittemplate desc="edittemplate directive"]] can
be used to make new pages default to containing text from a template
page, which can be filled out as the page is edited.
"""]]

[[!if test="(enabled(template) or enabled(edittemplate))
and enabled(inline)" then="""
These template pages are currently available:

[[!inline pages="templates/* and !*.tmpl and !templates/*/* and !*/discussion"
feeds=no archive=yes sort=title template=titlepage
rootpage=templates postformtext="Add a new template page named:"]]
"""]]

## template files

Template files are unlike template pages in that they have the extension
`.tmpl`. Template files are used extensively by Ikiwiki to generate html.
They can contain html that would not normally be allowed on a wiki page.

Template files are located in `/usr/share/ikiwiki/templates` by default;
the `templatedir` setting can be used to make another directory be
searched first. Customised template files can also be placed inside the
"templates/" directory in your wiki's source -- files placed there override
ones in the `templatedir`.

Here is a full list of the template files used:

* `page.tmpl` - Used for displaying all regular wiki pages. This is the
  key template to customise to change the look and feel of Ikiwiki.
  [[!if test="enabled(pagetemplate)" then="""
  (The [[!iki ikiwiki/directive/pagetemplate desc="pagetemplate directive"]]
  can be used to make a page use a different template than `page.tmpl`.)"""]]
* `rsspage.tmpl` - Used for generating rss feeds for blogs.
* `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 displaying a post in a blog.
* `archivepage.tmpl` - Used for listing a page in a blog archive page.
* `titlepage.tmpl` - Used for listing a page by title 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 rss/atom links)
* `feedlink.tmpl` - Used to add rss/atom links if `blogpost.tmpl` is not used.
* `aggregatepost.tmpl` - Used by the aggregate plugin to create
  a page for a post.
* `searchform.tmpl`, `googleform.tmpl` - Used by the search plugin 
  and google plugin to add search forms to wiki pages.
* `searchquery.tmpl` - This is a Omega template, used by the
  search plugin.
* `comment.tmpl` - Used by the comments plugin to display a comment.
* `change.tmpl` - Used to create a page describing a change made to the wiki.
* `recentchanges.tmpl` - Used for listing a change on the RecentChanges page.
* `autoindex.tmpl` - Filled in by the autoindex plugin to make index pages.
* `autotag.tmpl` - Filled in by the tag plugin to make tag pages.
* `calendarmonth.tmpl`, `calendaryear.tmpl` - Used by ikiwiki-calendar to
  make calendar archive pages.
* `editpage.tmpl`, `editconflict.tmpl`, `editcreationconflict.tmpl`,
  `editfailedsave.tmpl`, `editpagegone.tmpl`, `pocreatepage.tmpl`,
  `editcomment.tmpl` `commentmoderation.tmpl`, `renamesummary.tmpl`,
  `passwordmail.tmpl`, `openid-selector.tmpl`, `revert.tmpl` - Parts of ikiwiki's user
  interface; do not normally need to be customised.

[[!meta robots="noindex, follow"]]

here is a list of variables used in various tmpl files:
ACTION
ACTIONS
ADDCOMMENTURL
ATOMCOMMENTSURL
ATOMURL
ATTACHMENTS-CLASS
AUTHOR
AUTHORURL
BACKLINKS
BASEURL
BROKENLINKS
BROKENLINKS_CHECKED
CATEGORIES
CATEGORY
CDATE_3339
CDATE_822
CGIURL
COMMENTAUTHOR
COMMENTAUTHORURL
COMMENTID
COMMENTIP
COMMENTOPENID
COMMENTS
COMMENTSLINK
COMMENTSURL
COMMENTUSER
COMMITDATE
COMMITTYPE
CONTENT
COPYRIGHT
CTIME
DEST
DIFF
DIFFURL
DISCUSSIONLINK
DYNAMIC
EDITURL
ENCLOSURE
ERROR
ERROR_MESSAGE
EXTRAFOOTER
FAVICON
FEEDDATE
FEEDDESC
FEEDLINKS
FEEDURL
FIELD-ATTACHMENT
FIELD-DO
FIELD-EDITCONTENT
FIELD-EDITMESSAGE
FIELD-FROM
FIELD-LINK
FIELD-NEWFILE
FIELD-PAGE
FIELD-RCSINFO
FIELD-REMOVE
FIELD-RENAME
FIELD-REV
FIELD-REVERTMESSAGE
FIELD-SELECT
FIELD-SID
FIELD-SUBJECT
FIELD-TYPE
FIELD-UPLOAD
FIRST
FIXEDLINKS
FORCEBASEURL
FORCEBASEURL
form-cancel
FORM-END
FORM-START
FORM-SUBMIT
GETSOURCEURL
GUID
HAVE_ACTIONS
HELPONFORMATTINGLINK
HISTORYURL
HTML5
ID
ISTRANSLATION
JAVASCRIPT
LANG
LANGUAGE
LAST
LENGTH
LICENSE
LINE
LINK
LOCAL_CSS
MASTER
MDATE_3339
MESSAGE
META
MONTH
MORE_BACKLINKS
MTIME
NAME
NAME="ATTACHMENT_LIST"
NAME="ATTACHMENT_LIST"
NAME="CAN_COMMIT"
NAME="FIELD-ATTACHMENT"
NAME="FORM-END"
NAME="PAGE_DIFF"
NAME="PAGE_PREVIEW"
NAME="PAGE_PREVIEW"
NAME="PAGE_SELECT"
NAME=ALLOWAUTHOR
NAME=FIELD-AUTHOR
NAME=FIELD-URL
NAME=USERNAME
NONOPENIDFORM
OPENID_URL
OTHERLANGUAGES
PAGE
PAGE_DIFF
PAGE_PREVIEW
PAGES
PAGESPEC
PAGEURL
PARENTLINKS
PASSWORDURL
PERCENT
PERCENTTRANSLATED
PERMALINK
POSTFORMTEXT
PREFSURL
RECENTCHANGESURL
RELVCS
REMOTE_ADDR
REMOVEURL
REV
REVERTURL
ROOTPAGE
RSSURL
SEARCHACTION
SEARCHFORM
SID
SIDEBAR
SIGNINURL
SIZE
SRC
TAG
TAGNAME
TAGS
TITLE
TYPE
URL
USER
USER_NAME
VERSION
VIEW
WIKINAME
WIKIURL
WMD_PREVIEW
YEAR