Kiwi Document Format

This site is developed in with structured document tool that allows you to divide a document into sections and provide key/value metadata for each section, and for the document as a whole.

I call this document format a KiwiDocument. Why? Because I needed something short and catchy, and I’m from New Zealand. Otherwise, the name means nothing.

When a KiwiDocument is parsed, the resulting C# object has a structured representation of the document, divided up into sections.

This system does nothing to output or change the document in any way. It simply converts a text format into a C# object format. What you do with that is totally up to you.

Sections

A “section” is just part of the document identified by a section delimiter, which is [[, the section name, then ]].

The concept of sections came up when the capabilities of Markdown ran short. Markdown is great for text formatting, but when I wanted to impart some structure to a document, Markdown just wasn’t great at that.

I got to the point where I found myself thinking, “I wish I could divide this document up into… sections.” So, I did.

For example:

This is some content.

[[ my_section ]]

This is some more content in a section.

[[ another_section ]]

This is yet more content in another section.

This document has three sections. The starting content is in a section with a default name, since it has no explicit name (the default name is… default by… default; it can be changed in the settings).

Then a second section called my_section contains another line of content, and a third section called another_section contains some more content.

You do not have to close sections. You normally won’t. The start of a new section automatically closes the prior section. (You can close them if you want – see below – but the closing of the existing section is assumed when you start a new section.)

The section name can be anything, and section names can (and usually do) repeat.

What should constitute a section? Whatever you want. For me, a section is something that cannot be represented by a contiguous stretch of Markdown.

Metadata

Sections can contain metadata, which is simple key/value data at the beginning of the section.

This is not YAML. It’s just key/value pairs, delimited by a colon and a space.

key: value

Any casing will work, but use lower-case as a general rule. There are some edge cases where casing might cause issues (see below). There cannot be whitespace inside the keys – they can contain dashes and underscores as necessary.

NO: full name: Deane Barker
YES: full-name: Deane Barker

Values can be anything you want, provided that it fits on a single line (though, that line can be as long as you want…)

If you provide meta, skip one blank line before starting the content of the section.

[[ person ]]
first: Deane
last: Barker

This is Deane.

[[ person ]]
first: Annie
last: Barker

This is Deane's wife, Annie.

In this case, there are two sections, both with the name person. They both have two metadata items, with a key (first and last) and a value. They both also have content (the sentence separated from the meta with a blank line).

Metadata keys do not have to be unique. They can repeat as many times as you like.

The metadata of the first section is considered to be the metadata of the document itself.

title: The Barker Family
established: 1999-06-05

[[ person ]]
first: Deane
last: Barker

This is Deane.

[[ person ]]
first: Annie
last: Barker

This is Deane's wife, Annie.

When Metadata Key Casing Matters

Sometimes, the library needs to figure out if the first line of a section is (1) metadata, or (2) just regular content. To figure this out, it asks itself:

Is the first character of the line lower-case?
Is there a colon before the first whitespace?

If those two things are true, then it’s metadata, and not content. The only time this would be incorrect, is if you have content that starts with a single lower-case word, then a colon and a space.

So, something like…

consider: blah, blah, blah

That’s pretty rare, I think – in that case, “Consider” would have an uppercase “C”. It’s rare enought that I haven’t bothered to create anything more precise.

If you’re even in a situation when the library is incorrectly deciding the the first line is metadata because it passes the above two rules, just add a blank line at the top, and that should fix it (and that blank line will eventually be trimmed, anyway)

Closed Sections

As mentioned above, you do not have to close sections, but you can. For example:

[[ text ]]
This is some text.

[[ person ]]
first: Deane
last: Barker

Some text about this person
[[ /person ]]

This is some more text

When you explicitly close a section, the content under the closing tag starts a new section with the name of whatever the last unclosed section was.

In the example above, the text at the top is in a section called text. Then there’s a section for person which is closed. By going right from text to person, we left the text section unclosed.

So, the content below person starts a new section with the name text since that was the last section left unclosed. In effect, it “resumes” the last section (it’s actually a new section, but it continues under the same section name).

For the record, this code does exactly the same thing:

[[ text ]]

This is some text.

[[ person ]]
first: Deane
last: Barker

[[ text ]]

This is some more text

You might want to close a section for three reasons:

The syntax is occasionally clearer
All unclosed sections are considered the “narrative” of the document, and are exposed in the API under a special list property called NarrativeSections and a string property called NarrativeContent. Closed sections can be used for things like images, asides, and embeds. The parsed object will provide just the “narrative sections” which, in the first example above, would be just the text sections, since the person section is closed.
Sometimes you just don’t want to keep repeating the same section name. Many documents have lots of sections called text interspersed with other sections. It’s handy to let the default text section “flow” and just interrupt it here and there.

Hidden Sections

A section that starts with an underscore is considered “hidden” and will not be returned in most Section collections.

[[ text ]]

Some content.

[[ _code ]]

Some code that is not part of the content.

These sections are often used for templates (see Templating), or for other formatting directives. Again, the StructuredText format doesn’t know or care what you plan to use the section content for, it’s just a method of structuring it.

(They’re also handy for hiding stuff. Since in most cases, hidden sections won’t be used for display, you can just throw somethig in a section called _whatever and it will disappear from the output, while remaining in the source.)

This is item #0 in a sequence of 4 items.

You can use your left/right arrow keys to navigate