97 lines
2.3 KiB
Markdown
97 lines
2.3 KiB
Markdown
# Muse
|
|
|
|
_Bind data into anything_
|
|
|
|
## Overview
|
|
|
|
**Muse** is a CLI and toolchain for operating on data collected from
|
|
json, yaml, toml, and markdown files.
|
|
|
|
Muse scans included files, parses them into data, and streams
|
|
the loaded data through plugins.
|
|
|
|
Each plugin can modify the data as well as enact side effects
|
|
such as writing files to disk.
|
|
|
|
## Usage
|
|
|
|
```plaintext
|
|
Usage:
|
|
muse [/path/to/binding.yaml] <options>
|
|
|
|
Options:
|
|
--stdout -s Output final data to stdout
|
|
--verbose, -v Enable verbose logging
|
|
--help, -h Show this help message
|
|
```
|
|
|
|
## Binding File
|
|
|
|
Each Muse project should specify a `binding` file with the following shape:
|
|
```yaml
|
|
sources: # Optional
|
|
- file: "**/*.yaml"
|
|
- web: "https://example.com/data.json"
|
|
contentKey: "content" # Optional
|
|
options: # Optional
|
|
someOption: someValue
|
|
processors:
|
|
- first-processor
|
|
- second-processor
|
|
```
|
|
|
|
The `binding` file can be any of the supported file types for Muse and can
|
|
be named anything. If the CLI is invoked with a directory instead of a file,
|
|
Muse will look for a binding file in the directory with the following order:
|
|
|
|
1. `binding.json`
|
|
2. `binding.yaml`
|
|
3. `binding.toml`
|
|
4. `binding.md`
|
|
|
|
## Markdown Files
|
|
|
|
Muse supports loading and parsing Markdown files with optional YAML frontmatter.
|
|
|
|
```
|
|
---
|
|
someKey: someValue
|
|
---
|
|
|
|
Your markdown content here
|
|
```
|
|
|
|
When loading markdown files, Muse will load the content of the file
|
|
into a key called `content` by default. This can be changed in the binding
|
|
configuration by setting a `contentKey` value as an override.
|
|
|
|
## Plugin API
|
|
|
|
Muse plugins are written in TypeScript/JavaScript and expose information
|
|
describing the plugin, as well as the functions to operate with:
|
|
|
|
```typescript
|
|
export const name = "Plugin Name";
|
|
export const description = "Plugin Description";
|
|
export async function step(binding: Binding): Promise<Binding> {}
|
|
```
|
|
|
|
The main function of a plugin is `step`, which takes a `Binding` object
|
|
and returns a modified `Binding` object.
|
|
|
|
When returning a new Binding object, it is best practice to make immutable
|
|
changes:
|
|
|
|
```typescript
|
|
export async function step(binding: Binding): Promise<Binding> {
|
|
const newBinding = { ...binding };
|
|
newBinding.options.someOption = "newValue";
|
|
return {
|
|
...binding,
|
|
meta: {
|
|
...binding.meta,
|
|
customValue: true,
|
|
}
|
|
};
|
|
}
|
|
```
|