Lima Guide

A practical walkthrough of Lima syntax, the References Extension, resource limits, and the JavaScript/TypeScript API.

A practical walkthrough of Lima syntax, the References Extension, resource limits, and the JavaScript/TypeScript API. This guide is descriptive, not normative — Lima Core 1.3 and Lima References 2.1 are the source of truth. Where this guide and a spec disagree, the spec wins.

Installation

npm install @limaformat/lima
# or
bun add @limaformat/lima

Quick example

import { parse } from '@limaformat/lima'

const result = parse(`
title: Hello World
published: 2024-03-01
draft: false
tags:
  - javascript
  - webdev
`)

// {
//   title: 'Hello World',
//   published: 2024-03-01T00:00:00.000Z,  // a Date
//   draft: false,
//   tags: ['javascript', 'webdev']
// }

parse accepts the raw Lima content between the frontmatter delimiters (---) — stripping those delimiters is the caller’s job, Lima never sees them.

Syntax

Key names

An unquoted key starts with a letter, number, or underscore, in any script, followed by any combination of letters, accents and other marks, numbers, underscores, hyphens, colons, asterisks, or middle dots (·). Letters, marks and numbers are those of Unicode 18.0; numbers include more than the digits 0–9, such as Roman numerals.

Format Example Valid unquoted
camelCase firstName yes
snake_case first_name yes
kebab-case first-name yes
number start 1st, 42 yes
colon-namespaced og:title yes
other languages größe, título, 題名 yes
gendered autor:in, autor*in, autor·in yes
spaces, other characters first name, 🙂 needs quoting

Lima reads a key as it is written and does not normalise Unicode: an ö typed as one character and an ö typed as o plus a combining mark are two different keys. Editors write the first almost always.

Since unquoted keys may themselves contain colons, the key/value separator is the first colon followed by a space or a tab, or :\n, that isn’t inside a quoted key:

og:title: Hello      # key = 'og:title', value = 'Hello'
a:b:c: value          # key = 'a:b:c', value = 'value'

Quoted keys — single or double quotes, for keys with spaces or other characters an unquoted key can’t hold. Delimiters are stripped from the output key:

'first name': Alice          # → { 'first name': 'Alice' }
"display name": Bob          # → { 'display name': 'Bob' }
'': empty string key         # → { '': 'empty string key' }

Double-quoted keys decode the same backslash escapes as double-quoted string values (below). Single-quoted keys are literal. The separator must immediately follow the closing quote — "key" : value (space before the colon) is rejected at the top level (throws in strict mode, skipped as an unrecognised line in non-strict). Enforcement is less consistent for a quoted key nested inside a block or flow mapping — don’t rely on a space there being caught either way; simply avoid it.

Strings

Unquoted:

title: My Article

Double-quoted — suppresses type coercion, decodes escapes:

title: "Lima: A Primer"   # → 'Lima: A Primer' (colon is safe inside quotes)
count: "42"                # → '42' (string, not number)
flag:  "true"               # → 'true' (string, not boolean)
Escape Result
\\ backslash
\" double quote
\/ forward slash
\n \r \t newline / CR / tab
\b \f backspace / form feed
\uXXXX Unicode BMP code point (4 hex digits)
\UXXXXXXXX Unicode supplementary code point (8 hex digits)
\xXX Latin-1 code point (2 hex digits)

An unrecognised escape (including \0 — there is no null-byte escape) is left intact in non-strict mode and throws in strict mode.

Single-quoted — also suppresses coercion, but has exactly one special sequence: \' for a literal quote. Everything else, including backslashes, is literal — 'a\\b' is the four characters a\\b, not a\b.

Comments in unquoted values — # starts a comment at the start of a value or after whitespace; a # right after other text is text. \# always keeps a literal #; only the immediately preceding backslash counts:

link: https://example.com/page#section    # → 'https://example.com/page#section'
lang: C#                                  # → 'C#'
color: #ff0000                            # → null — the whole value is a comment
link: https://example.com/page #section   # → 'https://example.com/page'
link: https://example.com/page \#section  # → 'https://example.com/page #section'

A key whose value is only a comment is a bare key, so its block may follow:

author: # who wrote it
  name: Alice                             # → { author: { name: 'Alice' } }

# inside a single- or double-quoted string is never a comment — comment stripping only ever applies to unquoted values.

Multi-line strings require an explicit | marker — plain indented continuation lines without | are not joined automatically:

description: |
  Line one.
  Line two.

A line belongs to the block scalar as long as its indentation is strictly greater than the introducing key’s — including lines starting with # (they’re literal content, not comments, as long as they’re still indented further than the key).

Merge two lines into one with ^^ at the start of the continuing line, inside a | block only — it has no special meaning elsewhere. The line is joined to the one before it with a single space:

description: |
  This is a very long sentence that
  ^^continues on the next line as one.

There is no YAML-style > folded scalar — | + ^^ covers the same need with less ambiguity. A YAML header such as >, |- or >2 reads as a string in non-strict mode and throws in strict mode, at its own line.

Types

Value Type
null, ~, (empty) null
true, false (case-sensitive) Boolean
42, 3.14, .5 Number
0xFF, 0o77, 0b1010 String (not parsed as numbers)
01, 007, +42, 1. String (not parsed as numbers)
2024-03-01, 2024-03-01T09:00:00Z Date
01.03.2024 14:33 Date
2024/03/01 14:33 Date
anything else String

Leading zeros, an explicit + sign, a trailing bare decimal point, and hex/octal/binary literals are all deliberately kept as strings — no silent reinterpretation.

Dates are always UTC, second precision, no milliseconds:

Form Example
ISO date only 2024-03-01
ISO date + time 2024-03-01T09:00, ...T09:00:00, ...T09:00:00Z, ...T09:00+02:00
German (DD.MM.YYYY, no offset) 01.03.2024, 01.03.2024 14:33
Slash (YYYY/MM/DD, no offset) 2024/03/01, 2024/03/01 14:33

ISO forms require the T separator — a space between date and time is not accepted for ISO forms. German and slash forms require a space between date and time, and never carry a timezone offset (an offset there falls through to a string, not an error). An ISO offset is applied and converted to UTC:

published: 2024-03-01T09:00:00+02:00
# → Date, 2024-03-01T07:00:00.000Z

Years run 0001–9999. An out-of-range calendar value (2024-02-30) or an offset that pushes the resulting UTC year outside that range falls back to a string in non-strict mode, or throws in strict mode.

Arrays

Block sequence — dash-prefixed, one item per line:

tags:
  - javascript
  - webdev

A bare - with nothing after it is null:

values:
  -
  - hello
# → [null, 'hello']

Flow sequence — comma-separated in brackets, same type coercion rules, same result as the block form:

tags: [javascript, webdev, open-source]
values: [1, true, hello]
values: ["42", "true", hello]   # quoted items skip coercion → ['42', 'true', 'hello']

Arrays of objects — multiple keys per item, indented block style:

authors:
  - name: Alice
    affiliation: MIT
  - name: Bob
    affiliation: Stanford

Flow mapping — inline objects, useful as array items or map values:

menu:
  - {name: Home, url: /, weight: 1}
  - {name: About, url: /about, weight: 2}

Array items can be scalars or mappings, never another array or another flow collection nested inside a flow collection — Lima intentionally doesn’t support array-of-arrays or flow nesting deeper than one level (see Appendix A).

Maps

author:
  name: Alice
  email: alice@example.com

Nested to any depth (up to the nesting limit), and inline values / nested maps can be freely mixed at the same level:

params:
  weight: 1
  social:
    twitter: alice
  draft: false

Tabs

Only tabs in leading indentation — before the first non-whitespace character on a line — are normalised to two spaces. A tab that appears within scalar content, quoted or not, is left exactly as written:

a:
	b: 1        # → { a: { b: 1 } } — leading tab normalised to indentation
c: x	y        # → { c: 'x\ty' } — tab inside the value is preserved literally

Comments

title: My Article  # this is a comment

Stripped from single-line values. Multi-line (|) block scalars don’t process comments the same way — see Multi-line strings above for the indentation-based rule that applies there instead.

References (optional extension)

Everything in this section is Lima References 2.1, layered on top of Core. A Core-only parser (parseCore) treats ${key} and $(key) as plain strings. parse enables References by default; parseReferences is its deprecated compatibility alias with identical semantics.

Document reference — ${key} or a dotted path ${a.b.c}:

total: 42
count: ${total}   # → 42 (number, not string — type preserved)

Partial reference — $(key), resolved against a partials object you pass in. Later dotted components traverse mappings; / remains literal namespace content in the partial name:

author: $(defaultAuthor)
city: $(people/alice.address.city)
parse(frontmatter, {
  partials: {
    defaultAuthor: { name: 'Alice', email: 'alice@example.com' },
    'people/alice': { address: { city: 'London' } },
  }
})

Pure reference vs. interpolation — a value that is exactly one reference token (after trimming) preserves the target’s original type. Anything else — surrounding text, or more than one token — is interpolation and always produces a string:

firstName: Alice
fullName: ${firstName} ${lastName}   # interpolation → 'Alice Wonderland'
greeting: Hello ${firstName}!        # interpolation → 'Hello Alice!'

A reference inside a quoted string is inactive — literal text, never resolved:

title: "${key}"   # NOT a reference — stays the literal string "${key}"

Forward and bounded transitive references work. Targets may occur before or after their source. A chain may contain at most three reference edges, connecting at most four values:

a: ${b}
b: ${c}
c: 42

Both a and b resolve to 42. A fourth edge is unresolved: non-strict mode leaves that source token literal, while strict mode throws. Suffixes that fit within three edges may still resolve.

Partial mappings may be traversed by the token’s dotted path. Their stored strings remain inert: reference-looking text inside a partial is always literal, even after insertion.

Resource limits

Checked in both strict and non-strict mode; exceeding any of these throws RESOURCE_LIMIT in both modes (there is no silent-fallback variant for resource limits).

Limit Value
Document size 65,536 bytes (UTF-8)
Key length 128 code points
Scalar length 16,384 code points
Nesting depth 16
Top-level keys 128
Partials: count / name length / value depth / total nodes 128 / 128 / 16 / 4,096
References result: total node count 65,536

Strict mode

Most malformed values are recoverable in non-strict mode — parsing falls back to a string, null, or skips the offending content, and reports what it can via onWarning. A handful of conditions throw in both modes, because there is no safe fallback to recover to: the resource limits above, flow nesting deeper than one level (Core §10.1 itself), and — once References is layered on top — several reference/interpolation/partial conditions (below). Check the “Non-strict” column of each table; don’t assume it always means “never throws”.

Since Core 1.1, strict mode has one plain rule for lines: every line with content belongs to the structure. A line it cannot place — a key without its :, a YAML document marker, a line indented after a value that opens no block — is an error with its line, where non-strict mode skips it silently. What each kind of line does where it stands is one table in Core §7.1.

Condition Non-strict Strict
Duplicate key warn + last value wins throw
Indented freetext first after a bare key, without | skipped; the key is null unless a later line of its block is a member throw
Invalid date (calendar validation) string fallback throw
Float overflow / non-zero underflow to zero string fallback throw
Flow mapping missing : string fallback throw
Flow nesting deeper than one level throw throw
Unclosed [ or { string fallback throw
Trailing comma in flow sequence/mapping ignored throw
Empty flow element null / skipped throw
Unknown or malformed escape sequence left intact throw
Unterminated quoted string string fallback throw
Inconsistent indentation (also a line indented after a top-level inline value) skipped throw
Unrecognised line: an unindented line that is no key (author Odile, ---), or a key the key grammar rejects (a.b: value) at any level skipped throw
Space before colon in a quoted block key skipped throw
Content after a closing quote on an inline value string fallback throw
An unquoted value that starts with &, * or ! (a YAML anchor, alias or tag) string throw
A YAML block scalar header other than |, such as > or |- string throw

References 2.1 adds (Core §10.1 + References §7):

Condition Non-strict Strict
Unresolved reference after resolution left as token string throw
More than three reference edges left as token string throw
Dependency cycle left as token string throw
Mapping value used in interpolation throw throw
Array/nested-array element in interpolation throw throw
Scalar limit exceeded after interpolation/copy throw throw
Nesting depth exceeded after reference insertion throw throw
Invalid partial value throw throw

API

import { parseCore, type CoreOptions } from '@limaformat/lima'
import { parse, parseReferences, type ParseOptions, type ParseMode } from '@limaformat/lima'
import { outline, type LimaOutline } from '@limaformat/lima'

parseCore and parse both take (input: string, options?) => T, T defaulting to Record<string, unknown> — pass your own interface for a typed result. This is a compile-time assertion only, not runtime validation: Lima does not check that the parsed data actually matches T, it just tells TypeScript to treat the return value as that type. Validate separately (e.g. with zod or a manual check) if the input isn’t trusted:

interface PostMeta {
  title:     string
  published: Date
  draft:     boolean
  tags:      string[]
}

const meta = parse<PostMeta>(frontmatter)
meta.title.toUpperCase()  // TypeScript knows title is a string

parseCore(input, options?: CoreOptions) — Core only. ${key} and $(key) are plain strings.

Option Type Default
strict boolean false
onWarning (diagnostic) => void undefined

parse(input, options?: ParseOptions) — the primary Core plus References 2.1 parser. parseReferences is a deprecated exact alias; new code should use parse.

Option Type Default
strict boolean false
onWarning (diagnostic) => void undefined
partials Record<string, unknown> {}
mode 'references' | 'core' 'references'

parse(input, { mode: 'core' }) uses the same reference-unaware path as parseCore. Supplying partials together with mode: 'core' throws before parsing begins.

outline(input) — where each key, comment and error stands in the source, for editors. It never throws for content: an unfinished line leaves the keys below it in place.

import { outline } from '@limaformat/lima'

const { keys, comments, diagnostics } = outline('Autor:in: Michael # byline\n')
keys[0].key         // 'Autor:in'
keys[0].span.start  // { line: 1, column: 1, offset: 0 }

Spans are half-open; lines and columns start at 1, and columns and offsets count UTF-16 code units in the input without a leading BOM. diagnostics holds what a strict parse would report. JavaScript only.

Duplicate keys never go to console.warn — or any other implicit output channel. Diagnostics are only ever delivered through onWarning; without one, they’re silently discarded:

parse(frontmatter, {
  onWarning: (d) => console.warn(d.message, 'at line', d.line),
})

Strict mode throws a plain Error with a descriptive .message on the conditions listed above — this is the guaranteed contract (Core §11.3):

try {
  const meta = parse(frontmatter, { strict: true })
} catch (e) {
  console.error((e as Error).message)
}

Internally the thrown object also carries a .code, .line, and other structured fields, but that richer shape isn’t currently exported as a named type from the package — don’t rely on instanceof against a class you can’t import, or on the extra fields being present in a future version, until that’s a documented, stable export.

Implementation notes

  • Zero runtime dependencies.
  • Avoids backtracking-specific regex features. Every pattern in the implementation avoids lookahead, lookbehind, backreferences, and nested-quantifier constructions — the grammar doesn’t require a backtracking engine, the same property linear-time engines like RE2 require. Not a claim of immunity to slow input in general, just that the grammar itself doesn’t force worst-case regex behaviour.
  • Speed. Measured against js-yaml on Bun, on representative frontmatter documents: reproduce it yourself with bun run bench:vs-yaml from js/. Numbers are runtime-specific — don’t assume they transfer proportionally to other JavaScript engines.
  • Conformance corpus. Every claim about parsing behaviour in this guide is backed by cases in the conformance corpus, checked against both this implementation and (where applicable) any future one — see the corpus design.

Where to go next

On this page