emdy/README.md
2025-06-06 09:50:52 -04:00

110 lines
2.2 KiB
Markdown

# EMDY
Enhanced Markdown with YAML
EMDY makes it easy to work with markdown files like data. It provides a simple
JSON-like API for parsing and serializing objects to and from a markdown + YAML
frontmatter format.
## Install
Configure your environment to be aware of @endeavorance packages:
```toml
# Bunfig.toml
[install.scopes]
endeavorance = "https://git.astral.camp/api/packages/endeavorance/npm/"
```
Then install the package:
```sh
bun add @endeavorance/emdy
```
## Usage
```typescript
import EMDY from "@endeavorance/emdy";
EMDY.parse(/* ... */);
// -- or --
import { parse, stringify, parseAll } from "@endeavorance/emdy";
parse(/* ... */);
```
## Functions
EMDY provides three main functions for working with markdown files.
### `parse(content: string, markdownKey?: string): Record<string, unknown>`
Parses a single EMDY document. Frontmatter keys become top level properties
in the return value. The markdown content is loaded as-is into a key based
on the provided `markdownKey`. If no `markdownKey` is provided, it will default
to `content`.
```typescript
const emdyDoc = `
---
key: value
anotherKey: anotherValue
---
This is my markdown content.
`.trim();
console.log(EMDY.parse(emdyDoc));
/*
Output:
{
"key": "value",
"anotherKey": "anotherValue",
"content": "This is my markdown content."
}
*/
```
### `parseAll(content: string, markdownKey?: string): Record<string, unknown>[]`
Similar to `.parse`, but parses multiple EMDY documents from a single string,
returning an array of objects.
Documents are separated by a line containing only three equals signs:
```md
---
property: value
---
This is the first document
===
This is the second document
```
### `stringify(data: Record<string, unknown>, markdownKey?: string): Record<string, unknown>`
Given an object, serializes it to a string in EMDY format. Uses the `markdownKey`
to identify which property in the object holds the markdown content. If no
`markdownKey` is provided, it will default to `content`.
```typescript
const emdyObj = {
key: "value",
anotherKey: "anotherValue",
content: "This is my markdown content."
};
console.log(EMDY.stringify(emdyObj));
/*
Output:
---
key: value
anotherKey: anotherValue
---
This is my markdown content.
*/
```