jondashkyle / smarkt

📃 Hyper-readable plain text structure

📃 smarkt

Hyper-readable structure for defining fields and values in plain text

Usage

Transform some structured plain text including Markdown and YAML into JSON, and visa versa. Super useful for archivability and readability. Feature parity with Kirby’s file structure.

var smarkt = require('smarkt')

var str = smarkt.parse(`
title: Cyber Mysticism
----
tags:
  - technopastoral
  - ambient
----
text: Art has always been a focusing device, the frame is a focusing device. What I’m trying to do is eliminate the frame, eliminate all those distractions and put you in direct relationship to the real experience and the real power: your ability to perceive.
`)

var obj = smarkt.stringify({
  title: 'Cyber Mysticism',
  { tags: ['technopastoral', 'ambient']},
  text: 'Art has always been a focusing device, the frame is a focusing device. What I’m trying to do is eliminate the frame, eliminate all those distractions and put you in direct relationship to the real experience and the real power: your ability to perceive.'
})

Structure

A plain-text file is separated into fields delineated by four dashes.

----

Give the field a name and define it’s value.

title: Cyber Mysticism

The value can also be YAML.

tags:
  - technopastoral
  - ambient

Plain text input expanded

title: Cyber Mysticism
----
tags:
  - technopastoral
  - dark-ux
----
design:
  desktop:
    background: red
    navigation: false
  mobile:
    background: blue
    navigation: true
----
text:

Information wants to be free.

JSON output expanded

{
  "title": "Cyber Mysticism",
  "tags": ["technopastoral", "dark-ux"],
  "design": {
    "desktop": {
      "background": "red",
      "navigation": false
    },
    "mobile": {
      "background": "blue",
      "navigation": true
    }
  },
  "text": "Information wants to be free."
}

Methods

stringify

Accepts a single argument which must be type string. Returns an object.

parse

Accepts a single argument which must be type object. Returns a string.

Alternate usage

var stringify = require('smarkt/stringify')
var parse = require('smarkt/parse')

Sometimes it’s handy just to access a single method to reduce bundle size. To do this, simply require the desired method by name.

Todo

• Tests
• .stringify Remove quotes around YAML array values

smarkt's Issues

Digesting YAML objects

Right now setting YAML object as a field value fails.

cities: 
  losangeles:
    name: Los Angeles
    country: USA
  tokyo:
    name: Tokyo
    country: Japan

Todo

• stringify
• parse

Markdown compatiblity

I think this breaks currently:

title: A test document
----
tags:
  - tomato
  - paprika
----
text:

# This is markdown

With paragraphs, and now..

Head
----

Markdown actually allows this in most specifications.```

Paged content

It would be great if multi-part (paged) content could be specified via an array syntax.

My proposal looks like:

content[]:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris tincidunt convallis leo, vitae hendrerit ipsum euismod et. 

Sed sem augue, ornare eu interdum id, semper sit amet leo. Nullam a accumsan velit. Mauris sed lacus eleifend, rhoncus dui ultricies, mollis libero.

----
content[]:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris tincidunt convallis leo, vitae hendrerit ipsum euismod et. 

Sed sem augue, ornare eu interdum id, semper sit amet leo. Nullam a accumsan velit. Mauris sed lacus eleifend, rhoncus dui ultricies, mollis libero.

In the parsing stage, keys that match

/\[\]$/

can be added to JSON with Array.push().

In the serialization stage, if the object is an array but matches the above pattern, it's serialized as a series of plain text fields.

I'm not sure if this is more appropriate at the smarkt level, or should be delegated to when you process the JSON (e.g. through a delimiter inside the plain text field)