110 lines
2.2 KiB
Markdown
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.
|
|
*/
|
|
```
|
|
|