summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorhttp://kerravonsen.dreamwidth.org/ <http://kerravonsen.dreamwidth.org/@web>2010-10-28 00:21:47 +0000
committerJoey Hess <joey@kitenet.net>2010-10-28 00:21:47 +0000
commitf2f41d680a841813fb3b75e0311793afc956ffd2 (patch)
treeb1294358be8345483fdb63a010d3764ad9addb8b /doc
parent9ffa87671062eecfcd042a9501032d441def7ce1 (diff)
new version of ymlfront finally documented
Diffstat (limited to 'doc')
-rw-r--r--doc/plugins/contrib/ymlfront.mdwn65
1 files changed, 51 insertions, 14 deletions
diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn
index a2c649044..2805be04f 100644
--- a/doc/plugins/contrib/ymlfront.mdwn
+++ b/doc/plugins/contrib/ymlfront.mdwn
@@ -10,6 +10,9 @@ IkiWiki::Plugin::ymlfront - add YAML-format data to a page
# 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
@@ -25,23 +28,57 @@ This plugin is meant to be used in conjunction with the [[field]] plugin.
## DETAILS
-If one is not using the ymlfront directive, 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