Fix link to my homepage.

[git.ikiwiki.info.git] / doc / plugins / contrib / ymlfront.mdwn

diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn
index 6dd8ed532ad07d9873ae45be37ad9a70d7b53cef..2805be04fd838429e71be664f12558e1f1003635 100644 (file)
--- a/doc/plugins/contrib/ymlfront.mdwn
+++ b/doc/plugins/contrib/ymlfront.mdwn
@@ -10,39 +10,79 @@ IkiWiki::Plugin::ymlfront - add YAML-format data to a page
     # activate the plugin
     add_plugins => [qw{goodstuff ymlfront ....}],
 
     # activate the plugin
     add_plugins => [qw{goodstuff ymlfront ....}],
 

+    # configure the plugin
+    ymlfront_delim => [qw(--YAML-- --YAML--)],
+

 ## DESCRIPTION
 
 This plugin provides a way of adding arbitrary meta-data (data fields) to any
 ## DESCRIPTION
 
 This plugin provides a way of adding arbitrary meta-data (data fields) to any

-page by prefixing the page with a YAML-format document.  This provides a way to
-create per-page structured data, where each page is treated like a record, and
-the structured data are fields in that record.  This can include the meta-data
-for that page, such as the page title.
+page by prefixing the page with a YAML-format document.  This also provides
+the [[ikiwiki/directive/ymlfront]] directive, which enables one to put
+YAML-formatted data inside a standard IkiWiki [[ikiwiki/directive]].
+
+This is a way to create per-page structured data, where each page is
+treated like a record, and the structured data are fields in that record.  This
+can include the meta-data for that page, such as the page title.

 
 This plugin is meant to be used in conjunction with the [[field]] plugin.
 
 ## DETAILS
 
 
 This plugin is meant to be used in conjunction with the [[field]] plugin.
 
 ## DETAILS
 

-The YAML-format data in a page must be placed at the start of the page
-and delimited by lines containing precisely three dashes.  The "normal"
-content of the page then follows.
+There are three formats for adding YAML data to a page.  These formats
+should not be mixed - the result is undefined.

 
 

-For example:
+1. ymlfront directive
+   
+   See [[ikiwiki/directive/ymlfront]] for more information.

 
 

-    ---
-    title: Foo does not work
-    Urgency: High
-    Status: Assigned
-    AssignedTo: Fred Nurk
-    Version: 1.2.3
-    ---
-    When running on the Sprongle system, the Foo function returns incorrect data.
+2. default YAML-compatible delimiter
+
+   By default, the YAML-format data in a page is placed at the start of
+   the page and delimited by lines containing precisely three dashes.
+   This is what YAML itself uses to delimit multiple documents.
+   The "normal" content of the page then follows.
+
+   For example:
+
+       ---
+       title: Foo does not work
+       Urgency: High
+       Status: Assigned
+       AssignedTo: Fred Nurk
+       Version: 1.2.3
+       ---
+       When running on the Sprongle system, the Foo function returns incorrect data.
+
+   What will normally be displayed is everything following the second line of dashes.  That will be htmlized using the page-type of the page-file.
+
+3. user-defined delimiter
+
+   Instead of using the default "---" delimiter, the user can define,
+   in the configuration file, the **ymlfront_delim** value, which is an
+   array containing two strings. The first string defines the markup for
+   the start of the YAML data, and the second string defines the markip
+   for the end of the YAML data. These two strings can be the same, or
+   they can be different. In this case, the YAML data section is not
+   required to be at the start of the page, but as with the default, it
+   is expected that only one data section will be on the page.
+
+   For example:
+
+       --YAML--
+       title: Foo does not work
+       Urgency: High
+       Status: Assigned
+       AssignedTo: Fred Nurk
+       Version: 1.2.3
+       --YAML--
+       When running on the Sprongle system, the Foo function returns incorrect data.

 
 

-What will normally be displayed is everything following the second line of dashes.
-That will be htmlized using the page-type of the page-file.
+   What will normally be displayed is everything outside the delimiters,
+   both before and after.  That will be htmlized using the page-type of the page-file.

 
 ### Accessing the Data
 
 
 ### Accessing the Data
 

-There are a few ways to access the data given in the YAML section.
+There are a few ways to access the given YAML data.

 
 * [[getfield]] plugin
 
 
 * [[getfield]] plugin