Update plugin shape again
This commit is contained in:
parent
dfc65dacfa
commit
2d3ba356b5
5 changed files with 52 additions and 46 deletions
61
README.md
61
README.md
|
@ -1,20 +1,17 @@
|
|||
# Muse
|
||||
|
||||
A CLI for wrangling directories of source files.
|
||||
|
||||
Like a static generator, but for whatever.
|
||||
_Bind data into anything_
|
||||
|
||||
## Overview
|
||||
|
||||
**Muse** is a CLI and toolchain for operating on directories of
|
||||
json, yaml, toml, and markdown files. Each file can specify any shape
|
||||
of data. Muse scans included files, parses them into data, and streams
|
||||
the loaded data through processors and plugins.
|
||||
**Muse** is a CLI and toolchain for operating on data collected from
|
||||
json, yaml, toml, and markdown files.
|
||||
|
||||
Each processor can modify the data at compile time, as well as enact
|
||||
side effects such as writing files to disk.
|
||||
Muse scans included files, parses them into data, and streams
|
||||
the loaded data through plugins.
|
||||
|
||||
Muse does not edit source files, it only reads them in.
|
||||
Each plugin can modify the data as well as enact side effects
|
||||
such as writing files to disk.
|
||||
|
||||
## Usage
|
||||
|
||||
|
@ -32,10 +29,9 @@ Options:
|
|||
|
||||
Each Muse project should specify a `binding` file with the following shape:
|
||||
```yaml
|
||||
include:
|
||||
- ../another-project # Optional
|
||||
files: # Optional
|
||||
- "**/*.yaml"
|
||||
sources: # Optional
|
||||
- file: "**/*.yaml"
|
||||
- web: "https://example.com/data.json"
|
||||
contentKey: "content" # Optional
|
||||
options: # Optional
|
||||
someOption: someValue
|
||||
|
@ -44,9 +40,9 @@ processors:
|
|||
- second-processor
|
||||
```
|
||||
|
||||
The `binding` file can be any of the supported file types for Muse. 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:
|
||||
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`
|
||||
|
@ -68,3 +64,34 @@ 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,
|
||||
}
|
||||
};
|
||||
}
|
||||
```
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue