Working with text documents

Text documents are an extremely common file type used in the creation of sites and many other software artifacts. Origami includes some features for working with text documents that may or may not have additional data associated with them.

Plain text

Some text files contain just plain text, like this markdown file:

$ ori hokusai.md
I write, erase, rewrite
Erase again, and then
A poppy blooms.

If you ask Origami to unpack this file by appending a slash, it returns the plain text as is:

$ ori hokusai.md/
I write, erase, rewrite
Erase again, and then
A poppy blooms.

Document objects

To include additional data in text documents, you can include it as “front matter” in JSON or YAML format at the top of the document, enclosed in lines of --- three hyphens:

$ cat basho.md
---
author: Basho
---

No one travels
Along this way but I,
This autumn evening.

To represent text with data consistently, Origami will generally work with it as a plain object. The plain object’s properties include the front matter data and an additional text property with the body text.

If you ask Origami to unpack this file:

$ ori basho.md/
author: Basho
"@text": |
  
  No one travels
  Along this way but I,
  This autumn evening.

You can see that Origami is treating the body text as a text property. In JSON format:

$ ori json basho.md
{
  "author": "Basho",
  "@text": "\nNo one travels\nAlong this way but I,\nThis autumn evening.\n"
}

Here, the json command implicitly unpacks the document, so the trailing / slash is unnecessary.

You can create a text document from plain text with the document builtin.

Working on documents with builtin functions

Origami builtins that work on text, like inline and mdHtml, can work on both plain text documents and document objects.

If you give a builtin function plain text, you get back plain text. For example, mdHtml transforms plain markdown text into plain HTML text:

$ ori mdHtml hokusai.md
<p>I write, erase, rewrite
Erase again, and then
A poppy blooms.</p>

If you give the builtin a document object, you get back a new document object that preserves the original front matter data as properties and a text property that contains the transformed text:

$ ori mdHtml basho.md
author: Basho
"@text": |
  <p>No one travels
  Along this way but I,
  This autumn evening.</p>