Lima

Website & documentation: limaformat.dev

LIMA Is Metadata Annotation — a YAML-familiar, deliberately bounded frontmatter format with a complete reference specification.

The name is a recursive backronym — LIMA contains itself, just like YAML (YAML Ain't Markup Language). Consider it a nod: Lima is a deliberate, focused subset of YAML, keeping what works and leaving out what doesn't. Fittingly, lima is also Esperanto for "bounded" or "limiting" (from limo, "boundary") — Lima is a deliberately bounded, precisely defined metadata language.

(Lima in running text, always — LIMA only when spelling out the backronym, as above. Full naming convention: Contributing.)

Lima is the part of YAML that frontmatter actually needs, with well-defined types and no surprises. It adds two things YAML doesn't have: references to document properties and to externally provided partials. Everything else is familiar.

---
title: My First Post
tags:
  - javascript
  - webdev
published: 2024-03-01
draft: false
---

Quickstart

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

Parsing content between the fences — parse takes the raw Lima content, not the surrounding --- delimiters or the Markdown body:

import { parse } from '@limaformat/lima'

const meta = parse(`
title: My First Post
tags:
  - javascript
  - webdev
published: 2024-03-01
draft: false
`)
// { title: 'My First Post', tags: ['javascript', 'webdev'],
//   published: 2024-03-01T00:00:00.000Z, draft: false }

Parsing a whole Markdown file — splitting the fences off is the caller's job; Lima has no file-reading or fence-splitting API of its own. This is a plain, dependency-free recipe, not a bundled function — copy it, or use a library like front-matter/gray-matter for the splitting step and hand the extracted text to Lima's parse:

import { readFileSync } from 'node:fs'
import { parse } from '@limaformat/lima'

function splitFrontmatter(fileContent: string): { frontmatter: string; body: string } | null {
  const match = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?([\s\S]*)$/.exec(fileContent)
  if (!match) return null
  return { frontmatter: match[1], body: match[2] }
}

const file = readFileSync('post.md', 'utf-8')
const split = splitFrontmatter(file)
if (!split) throw new Error('post.md has no --- frontmatter block')

const meta = parse(split.frontmatter)
// split.body is the Markdown content after the closing fence

This recipe requires the opening --- on the file's literal first line and a ----only closing line; it does not recognise a completely empty frontmatter block with zero blank lines between the fences (---\n---\n, as opposed to ---\n\n---\n, which works). If this pattern turns out to be widely needed, an official extractFrontmatter (or similar) export is a reasonable future addition — proposed here, not implemented, since it's a new public API surface that deserves its own review rather than arriving as a side effect of a docs pass.

Full Core and References syntax, resource limits, strict mode, and the complete API: docs/guide.md. Migrating existing YAML frontmatter: docs/migrating-from-yaml.md.

What Lima guarantees

Lima is small because it is specified, not specified because it is small. Three guarantees follow from that; the sizes further down are their evidence, not the point.

• Nothing is lost without a word. In strict mode every content line belongs to a key, a block or a scalar, or it is an error at its line (Core 1.1). A typo, a stray tab or a construct Lima does not have is reported where it stands, with a hint where one helps:

  description: >
    A folded text
  
  Lima: unexpected indentation at line 2: "A folded text" (">" is YAML's folded scalar; Lima writes "|" and
  continues a line with "^^")
  

  Strict mode checks a closed list of conditions (Core §10.1) and nothing else; non-strict mode skips what it cannot read, and the same list says what that is.

• One answer in every language. TypeScript, Rust and Go implement the same specification independently. They pass the same 486 Core 1.2 and 144 References 2.1 conformance cases — values, error codes and source lines alike — and in every CI run they parse the same 100,000 random documents in both modes and must agree on every value, warning and error. A disagreement is a defect or a gap in the specification, and once decided it becomes a corpus case.

• Types without guessing. true and false are the only booleans, so country: NO stays the string "NO" — YAML 1.1's wider set is the well-known "Norway problem". Dates have fixed formats, without the locale ambiguity of MM/DD/YYYY and DD/MM/YYYY; integers outside the safe range stay strings. There is one behaviour and no schema to choose: js-yaml's own newer default no longer resolves timestamps at all, unlike most existing frontmatter tooling. Document size, key and scalar length, nesting depth and key count are normative limits, checked in both modes.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗