caml-mkdn

CAML is a Colon Attribute Markup Language similar to YAML with some key differences:

• Slims down the syntax by removing the need for separators (---).
• Can be sprinkled throughout a markdown file (similar to markdown footnotes).
• Focuses on single level sequence collections (e.g. does not support object values, just arrays).
• Supports [[wikiref]] values.
• Can be rendered as a wikipedia-style infobox alongside the rest of your markdown.
• Supports markdown inside of strings.

🕸 Weave a semantic web in your 🎋 WikiBonsai digital garden.

Install

Install with npm:

npm install caml-mkdn

Use

import * as caml from 'caml-mkdn';

let text = `
:key::value
:another-key::val1,val2,val3
:yet-another-key::
- 1
- 2
- 3

And some content!
`;
let payload = caml.load(text);

console.log(payload.data);
// should produce:
// {
//    key: 'value',
//    another-key: ['val1', 'val2', 'val3'],
//    yet-another-key: [1, 2, 3],
//  }

console.log(payload.content);
// should produce:
// 'And some content!'

Note: To use commas (,) inside of singular caml string value, make sure to surround the value with single or double quotes ('', "") so that the comma is not used to create a list value. Commas inside of list string values is not (yet) supported.

API

dump(attrs: any, opts?: DumpOpts): string

Serializes object as a CAML document. Similar to js-yaml's dump().

import { dump } from 'caml-mkdn';
import type { CamlDumpOpts } from 'caml-mkdn';

const attrs: Record<string, any> = {
  title: 'My Document',
  tags: ['tag1', 'tag2', 'tag3'],
};
const result: string = dump(attrs);
// result = ': title :: My Document\n'
//        + ': tags  ::\n'
//        + '           - tag1\n'
//        + '           - tag2\n'
//        + '           - tag3\n'

const compact: string = dump(attrs, { format: 'none', listFormat: 'comma', prefix: true });
// compact = ':title::My Document\n'
//         + ':tags::tag1,tag2,tag3\n'

Options

format: 'pretty' | 'pad' | 'none'

The format CAML attributes should be printed in. Choices are 'pretty', 'pad', and 'none':

• 'none': Will just dump the text with no added whitespace.
  • ex:

  :this-is-a-really-long-key::value
  :short-key:: value
  :comma-list::1,2,3
  :mkdn-list::
  - 1
  - 2
  - 3

• 'pad': Will pad with a single whitespace around text and special chars.
  • ex:

  : this-is-a-really-long-key :: value
  : short-key :: value
  : comma-list :: 1, 2, 3
  : mkdn-list ::
  - 1
  - 2
  - 3

• 'pretty': Will pad as well as determine the longest key length and pad all other keys with the same amount of spaces to achieve a "pretty" print feel.
  • ex:

  : this-is-a-really-long-key :: value
  : short-key                 :: value
  : comma-list                :: 1, 2, 3
  : mkdn-list                 ::
                                 - 1
                                 - 2
                                 - 3

listFormat: 'comma' | 'mkdn'

Dump CAML attribute lists by comma-separation or mkdn-list-separation.

• comma-separated:

  : comma-list :: 1, 2, 3

• Mkdn-separation:

    : mkdn-list ::
    - 1
    - 2
    - 3

prefix: boolean;

Whether or not to use the colon : prefix when dumping CAML attributes.

• With:

  : key :: value

• Without:

  key :: value

load(content: string): CamlLoadPayload

Load a content string, parse CAML attributes, and store attributes in data and the rest of the content string in content. Similar to graymatter.

import { load } from 'caml-mkdn';
import type { CamlLoadPayload } from 'caml-mkdn';

const payload: CamlLoadPayload = load(
  ': title :: My Document\n'
+ ': tags  :: tag1, tag2, tag3\n'
+ '\n'
+ 'And some content!\n'
);
// payload = {
//   data: {
//     title: 'My Document',
//     tags: ['tag1', 'tag2', 'tag3'],
//   },
//   content: 'And some content!',
// }

resolve(value: string): CamlValData

Take a CAML attribute value as a string, parse it, and return CamlValData.

import { resolve } from 'caml-mkdn';
import type { CamlValData } from 'caml-mkdn';

const str: CamlValData = resolve('hello');
// str = { type: 'string', string: 'hello', value: 'hello' }

const num: CamlValData = resolve('42');
// num = { type: 'int', string: '42', value: 42 }

const bool: CamlValData = resolve('true');
// bool = { type: 'bool', string: 'true', value: true }

const nil: CamlValData = resolve('null');
// nil = { type: 'null', string: 'null', value: null }

CamlValData looks like:

interface CamlValData {
  type: string;   // a string description of the value's type
  string: string; // a string representation of the value
  value: null     // the literal parsed value
  | boolean
  | number
  | bigint
  | Date
  | string;
}

update(content: string, key: string, newVal: string, opts?: UpdateOpts): [number, number, string] | string | undefined

Find a CAML attribute by key and replace its value. Returns undefined if the key is not found. Whitespace around the :: marker is preserved.

import { update } from 'caml-mkdn';
import type { UpdateOpts } from 'caml-mkdn';

// default format: 'content' — returns the full string with the replacement applied
const content = update('attr::old value\n', 'attr', 'new value');
// content = 'attr::new value\n'

// format: 'offsets' — returns [start, end, replacementText]
const offsets = update('attr::old value\n', 'attr', 'new value', { format: 'offsets' });
// offsets = [0, 15, 'attr::new value']

// type-aware matching
const dated = update(': date :: 2001-12-14\n', 'date', '2022-11-14', { type: 'timestamp' });
// dated = ': date :: 2022-11-14\n'

Options

format: 'content' | 'offsets'

• 'content' (default): Returns the full content string with the value replaced inline.
• 'offsets': Returns [start, end, replacementText] — the character offsets and the replacement string, useful for editor integrations.

type?: string

Constrain the match to a specific value type (e.g. 'timestamp', 'int', 'bool'). If omitted, matches any value.

scan(content: string, opts?: CamlScanOpts): CamlScanResult[]

Scan a given content string and return an array of descriptions of all valid CAML attribute constructs. Each result groups a key with its values.

import { scan } from 'caml-mkdn';
import type { CamlScanResult } from 'caml-mkdn';

const results: CamlScanResult[] = scan(': title :: My Document\n: count :: 42\n');
// results = [
//   {
//     key: { text: 'title', start: 2 },
//     vals: [
//       { type: 'string', val: { text: 'My Document', start: 11 } },
//     ],
//   },
//   {
//     key: { text: 'count', start: 25 },
//     vals: [
//       { type: 'int', val: { text: '42', start: 34 } },
//     ],
//   },
// ]

Options

skipEsc: boolean

Whether or not to skip escaped CAML construct instances; set to true by default.

• true (default): CAML inside backticks, code spans, and fenced code blocks is ignored.
• false: All CAML constructs are returned regardless of escaping.

const results: CamlScanResult[] = scan('`:attr::value`\n', { skipEsc: true });
// results = [
//   {
//     key: { text: 'attr', start: 1 },
//     vals: [
//       { type: 'string', val: { text: 'value', start: 7 } },
//     ],
//   },
// ]

Types

interface CamlScanOpts {
  skipEsc?: boolean;
}

interface ScanTxt {
  text: string;
  start: number;
}

interface CamlScanResVal {
  type: string;
  val: ScanTxt;
}

interface CamlScanResult {
  key: ScanTxt;
  vals: CamlScanResVal[];
}