The following document specifies Collate's file format.
Collate's file format optimizes for human readability. The goal is a format which can be easily parsed and read without the aid of software other than a file browser and text editor. This is important for long term archival purposes as well as removing anxiety about being "locked-in" to a developer's ecosystem. There is a comfort in knowing that your data will be safe and available to you no matter what happens.
Collate's file structure is very simple. Here is an example file structure:
Collection
|-- Inbox
| `-- Welcome
| |-- welcome.md
| `-- attachments
| `-- attachment.jpg
|-- Todo
| `-- January 1 2017
| |-- january 1 2017.md
| `-- attachments
| `-- presentation.doc
`-- Recipes
`-- Hot dogs au gratin
|-- hot dogs au gratin
`-- attachments
`-- Hot dog recipe.pdf
A Collection is a directory where everything is stored. Its located anywhere the user has access. There are no naming conventions or restrictions.
A Notebook is any directory directly nested under the main Collection directory.
The naming convention was removed 4/27/2017. Going forward, Collate will still read notes and notebooks with the old format and will not convert them. However, any new notes and notebooks will not be constrained.
A notebook is any directory immediately nested under the main Collection.
A note is any directory directly nested under a notebook and second child of the Collection directory
The naming convention was removed 4/27/2017. Going forward, Collate will still read notes and notebooks with the old format and will not convert them. However, any new notes and notebooks will not be constrained.
A Note File is a markdown file with suffix .md which is nested immediately under a Note.
The naming convention was removed 4/27/2017.
A note file has two parts, the frontmatter containing the machine readable metadata and the note body which contains the contents of the note.
Collate uses YAML formatted front matter to store note metadata as inspired by Jekyll. YAML offers a great readable way to store metadata for Notes.
Collate's YAML frontmatter looks like this:
---
title: Anatomy of a Collate Note
tags:
- Collate
- Markdown
- YAML
type: markdown
created: 2017-02-16T08:51:20.000Z
modified: 2017-02-16T08:56:56.000Z
---
Translated to JSON:
{
"title": "Anatomy of a Collate Note",
"tags": ["Collate", "Markdown", "YAML"],
"type": "markdown",
"created": "2017-02-16T08:51:20.000Z",
"modified": "2017-02-16T08:56:56.000Z"
}
The only required key is the title.
Here's a table of keys:
| Key | Required/Optional | Data Type | Default Value |
|---|---|---|---|
| title | Required | String | |
| tags | Optional | Array | |
| type | Optional | String | markdown |
| created | Optional | String | |
| modified | Optional | String |
Created and Modified use ISO 8601 formatted strings. If not found, Collate defaults to system birthtime for created and mtime for modified.
Other fields may also be added to the frontmatter and Collate may utilize it in the future for other features.
Note: Any additional YAML encoded fields in the front matter will be passed through by Collate.
The default body text is in markdown format.
Collate will use Github Flavored Markdown, a superset of Markdown which includes CommonMark.
As of v. 0.2.3, Collate will be expanding the contents of the body to include other types of data in support of the upcoming Note Types feature. This feature trades rich text or other note editing capabilities on the front end of the application for a less readable but more flexible data format. Data types may include JSON, HTML, or additional types in the future. Files that contain data other than markdown must be denoted in the front matter by using the type key.
The attachments folder may hold any type of file. Collate will not open or parse these files except for the file name. Any directories within this folder will be ignored, but this may change in the future.