# 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
-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
-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.
+ 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 outside the delimiters,
+ both before and after. That will be htmlized using the page-type of the page-file.
### Accessing the Data
-There are three ways to access the data given in the YAML section.
+There are a few ways to access the given YAML data.
* [[getfield]] plugin
When running on the Sprongle system, the Foo function returns incorrect data.
+* [[report]] plugin
+
+ The **report** plugin is like the [[ftemplate]] plugin, but it reports on multiple pages, rather than just the current page.
+
* write your own plugin
In conjunction with the [[field]] plugin, you can write your own plugin to access the data.