X-Git-Url: https://scripts.mit.edu/gitweb/www/ikiwiki.git/blobdiff_plain/95c5cbc721a2382104810e3b4f2bd13b8a56558f..319bf45a37219d8b8f9862948bd2dbb94f11e4a2:/doc/plugins/write.mdwn?ds=sidebyside

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 9e27cc27f..ea2d00630 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -92,6 +92,8 @@ function is passed no values.
 
 ### needsbuild
 
+
+
 	hook(type => "needsbuild", id => "foo", call => \&needsbuild);
 
 This allows a plugin to manipulate the list of files that need to be
@@ -142,6 +144,30 @@ format at preprocessor time. Text output by a preprocessor directive will
 be linkified and passed through markdown (or whatever engine is used to
 htmlize the page) along with the rest of the page.
 
+### linkify
+
+	hook(type => "linkify", id => "foo", call => \&linkify);
+
+This hook is called to convert [[WikiLinks|WikiLink]] on the page into html
+links. The function is passed named parameters "page", "destpage", and
+"content". It should return the linkified content.  Present in IkiWiki 2.40
+and later.
+
+Plugins that implement linkify must also implement a scan hook, that scans
+for the links on the page and adds them to `%links`.
+
+### scan
+
+	hook(type => "scan", id => "foo", call => \&scan);
+
+This hook is called early in the process of building the wiki, and is used
+as a first pass scan of the page, to collect metadata about the page. It's
+mostly used to scan the page for WikiLinks, and add them to `%links`.
+Present in IkiWiki 2.40 and later.
+
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
+
 ### htmlize
 
 	hook(type => "htmlize", id => "ext", call => \&htmlize);
@@ -151,11 +177,6 @@ specifies the filename extension that a file must have to be htmlized using
 this plugin. This is how you can add support for new and exciting markup
 languages to ikiwiki.
 
-Note that if you choose a filename extension that starts with "_",
-ikiwiki will not render the page, or allow the page to be edited with the
-web interface. This is useful for certian types of internal-use pages, but
-should generally be avoided.
-
 The function is passed named parameters: "page" and "content" and should
 return the htmlized content.
 
@@ -227,8 +248,11 @@ source files that were rendered.
 
 Use this to hook into ikiwiki's cgi script. Each registered cgi hook is
 called in turn, and passed a CGI object. The hook should examine the
-parameters, and if it will handle this CGI request, output a page (including the http headers) and
-terminate the program.
+parameters, and if it will handle this CGI request, output a page
+(including the http headers) and terminate the program.
+
+Note that cgi hooks are called as early as possible, before any ikiwiki
+state is loaded, and with no session information.
 
 ### auth
 
@@ -483,11 +507,16 @@ If the destination directory doesn't exist, it will first be created.
 
 Given a page name and a destination file name (not including the base
 destination directory), register that the page will result in that file
-being rendered. It's important to call this before writing to any file in
-the destination directory.
+being rendered. 
+
+It's important to call this before writing to any file in the destination
+directory, and it's important to call it consistently every time, even if
+the file isn't really written this time -- unless you delete any old
+version of the file. In particular, in preview mode, this should still be
+called even if the file isn't going to be written to during the preview.
 
 Ikiwiki uses this information to automatically clean up rendered files when
-the page that rendered them goes away or is changes to no longer render
+the page that rendered them goes away or is changed to no longer render
 them. will_render also does a few important security checks.
 
 #### `pagetype($)`
@@ -536,6 +565,19 @@ destination file, as registered by `will_render`.
 Passed a page and an extension, returns the filename that page will be
 rendered to.
 
+## Internal use pages
+
+Sometimes it's useful to put pages in the wiki without the overhead of
+having them be rendered to individual html files. Such internal use pages
+are collected together to form the RecentChanges page, for example.
+
+To make an internal use page, register a filename extension that starts
+with "_". Internal use pages cannot be edited with the web interface,
+generally shouldn't contain wikilinks or preprocessor directives (use
+either on them with extreme caution), and are not matched by regular
+PageSpecs glob patterns, but instead only by a special `internal()`
+[[ikiwiki/PageSpec]].
+
 ## RCS plugins
 
 ikiwiki's support for [[revision_control_systems|rcs]] also uses pluggable