An in browser module for viewing and editing yaml documents stored on GitHub
Your repo will need 4 files to work with Pensieve (assuming you're serving pensieve from the repo containing the data):
document.yaml, containing the data read/written by Pensieve. Initialize withDataPath: []schema.yaml, containing the structure of the data you'll be storing. See the schema section below.views.yaml, containing saved views. Initialize the repo with an empty views file.index.html, which loads Pensieve
If you're hosting pensieve elsewhere, you just need the 3 YAML files.
Add the following to the <head> element on your page:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto|Ubuntu+Mono">
<script src="https://resin-production-downloads.s3.amazonaws.com/pensieve/latest/pensieve.js"></script>Pensieve uses fontawesome icons and the Roboto and Ubuntu mono fonts, so these should be loaded as well.
Make sure there is a container element with the id pensieve on your page, then execute the Pensieve global using your desired configuration.
Assuming that:
-
you have a repository called
document-repoheld under the accountresin-io -
the repo contains a yaml file called
schema.yamlin its root -
the structure of
schema.yamlis:My string field: type: String My number field: type: Integer My boolean field: type: Boolean
-
the repo contains a yaml file called
document.yamlin its root -
the structure of
document.yamlis:content: Entry 1: My string field: foobar My number field: 1 My boolean field: true Entry 2: My string field: barbaz My number field: 2 My boolean field: false meta: info: example metadata
Your HTML page would look like this:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Pensieve</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto|Ubuntu+Mono">
<script src="https://resin-production-downloads.s3.amazonaws.com/pensieve/latest/pensieve.js"></script>
</head>
<body>
<div id="pensieve"></div>
<script>
Pensieve({
// The path to your schema file or an object literal of your schema
schema: 'schema.yaml',
// The attribute that your document's content is set under
contentPath: 'content',
repo: {
// The name of the repo containing the yaml document
name: 'document-repo',
// The account the repo is held under
account: 'resin-io',
// The path to the yaml file in your github repo
file: 'document.yaml',
// The name of the commit/branch/tag. usually the repository’s default branch (eg master)
ref: 'master'
}
});
</script>
</body>
</html>A common pattern is to use GitHub pages to host the HTML file that contains Pensieve. Be advised that enabling github pages on your master branch will make the entire contents of your repository publicly accessible. If you want to use GitHub pages to host your Pensieve instance and your repo is private, it is recommended that you use a seperate branch that only contains the HTML file and files that you do not consider sensitive.
Your schema is used to construct filters and validate your data when editing or adding a new entry. The schema should be an object composed of key/value pairs, where the fields name is the key and the type definition is the value. The type paramater should be one of:
- Boolean
- Case Insensitive Text
- Date Time
- Date
- Integer
- Real
- Short Text
- Text
- Time
- semver-range
- semver
Here's an example of a schema file in yaml:
GitHub issue:
type: Short Text
Difficulty:
type: Integer
Description:
type: Text
Pull Logs:
type: Boolean
Last Updated:
type: Date Time
Versions Affected:
type: semver-range
Fixed in Version:
type: semverA true or false value.
A string value of any length. When filtering on a field of this type, the match is always case insensitive.
A date time string or unix timestamp. Under the hood Pensieve uses momentjs to parse values, so your string value should be in a known ISO 8601 or RFC 2822 Date time format. See https://momentjs.com/docs/#/parsing/string/ for more information.
Similar to the Date Time type but ignores the time part. The lowest level of comparison is the day when filtering, making 2013-02-08 09:30:26.123 and 2013-02-08 15:03:42.321 equal.
An integer value.
A number value, can be an integer or decimal.
A string value with a maximum length of 255 characters.
A string value with no maximum length.
Similar to the Date Time type but ignores the date part. Only the time of day is evaluated when filtering, making 2013-02-08 09:30:26.123 and 2017-08-12 09:30:26.123 equal.
A valid semver value http://semver.org/
Under the hood the resin-semver module is used, so we support resinified semver strings like Resin OS 2.0.5 (prod).
A semver-range value https://github.com/npm/node-semver#advanced-range-syntax
Filters can be saved as "Views", allowing the filter to be loaded at a later date. Views are saved to a file named views.yaml in the root of the connected GitHub repository. When saving a view you can set it's visibility to 'just me' (Local), meaning that only you will see the saved views, or 'everyone' (Global) which will make the view visible to anyone using the document.
You can specify a default view to be loaded when Pensieve is initialised by adding a defaultView attribute to the Pensieve config. The value can either be the name of a Global view (visible to everyone) or an array of filter rules.
The types Text, Short Text and Case Insensitive Text are all rendered as
markdown.