Configuring Report Metadata

All reports on Kyso contain variables like authors, dates, tags, descriptions, titles as metadata. This metadata can be added in various ways:
1.Directly on reports in the Kyso UI (titles, descriptions and tags only).
2.Include it in a kyso.yaml/kyso.json file in the same directory as the report.
3.The first cell (JSON) of a Jupyter notebook.
And end-users can search across your company's knowledge base by this report metadata.
Properties
Below is an example of a comprehensive YAML file:
1
organization: acme
2
author: [email protected]
3
team: general
4
type: jupyter
5
title: "Project Title"
6
description: "Project Description."
7
main: report.ipynb
8
preview: "images/preview.png"
9
tags: [tag1, tag2, tag3]
Copied!
Property Lexicon:
main: required. File which will be rendered automatically when the project is opened on Kyso.
title: required. Name of the report.
author: optional
description: required. Description of the report.
preview: optional. Preview image of the report. One will be generated automatically in its absence.
organization: required. Organization which owns the report.
team: required. Team within the organization to which the report belongs.
type: required. Type of report. Options:
jupyter: Jupyter notebook
website: Simple HTML file or more complex website
meta: Mono-folder in which each sub-directory is published as separate project report.
reports: required only if type: meta
1
reports:
2
   - folder1
3
   - folder2
Copied!
In this case, each sub-folder should have its own yaml/json file for the individual reports.
Note that you are also able configure the title, description, and preview image on the post on Kyso after import, but it is recommended to include this in the YAML header for a more seamless workflow.
Recommendation: Always add a title, description and preview image to your posts. You will receive a lot more readers.
If you want to validate your YAML before pushing to Github - checkout this YAML Validator.
Example Workflow
I am working on my local machine in a directory Users/Kyle/Data-Analysis. This folder contains multiple sub folders, which all denote separate projects and that I want to publish as their own Kyso reports.
Example:
1
Data-Analysis
2
└── Marketing
3
    └── data/
4
    └── report.ipynb
5
    └── images/
6
└── Product
7
    └── data/
8
    report.ipynb
9
    └── images/
10
etc..
Copied!
In my root directory (Users/Kyle/Data-Analysis), I have the following kyso.yaml file:
1
type: meta
2
reports:
3
  - marketing
4
  - product
Copied!
This tells Kyso to import 'Marketing' and 'Product' as their own individual Kyso reports and not 'Data-Analysis' as the one Kyso report. By default Kyso does not import in the root directory (Data Analysis) as it's own report, but rather acts as a navigation system for Kyso in finding the project reports.
Then in each sub-directory I have another kyso.yaml which sets the metadata for that specific report. For example, in 'Marketing' I could have the following"
1
organization: acme
2
team: marketing
3
type: jupyter
4
description: "This report explores how we can pull in website data from Google Analytics and find insights on SEO."
5
email: [email protected]
6
main: report.ipynb
7
preview: images/preview.png
8
title: "Predicting the results of our latest marketing campaign"
9
tags: [seo, content-campaigns, google-analytics]
Copied!
And something similar in 'Product'. Any time changes are made to any individual report, Kyso will version the projects as you publish again and again...
Here is how this looks in action on a Git repo: https://github.com/KyleOS/Data-Analysis, feel free to browse through!!
The Power of Tagging
As seen above, authors can 'tag' their reports within the metadata. What makes this specific variable so useful is that when users are searching for reports on Kyso, using specific tags when combined with searching by team and full-text (see next two documents) will really narrow a search from '000s down to a few relevant reports.
Coming Soon: YAML Header in the Notebook
In the absence of any kyso.yaml file in the directory, Kyso will look for a YAML header in a notebook's metadata. This may be a better option for those of you posting ongoing projects, to which commits are made on a daily or weekly basis. Rather than manually configuring a YAML file, you can simply update the metadata while working in the notebook.
The example below is our YAML configs contained within 3 dashed (-) lines top and bottom, in the first Markdown cell of the notebook:
1
---
2
organization: acme
3
team: marketing
4
type: jupyter
5
title: "My awesome post"
6
description: "This is a description of what I did in my awesome post"
7
main: "my-article.ipynb"
8
tags: [apples, oranges]
9
---
Copied!
This feature will be pushed in the next deployment.

Bokeh Plots and Kyso

Next - Search and Discovery

Full-Text Search

Last modified 21h ago

Copy link

Contents

Properties

Example Workflow

The Power of Tagging

Coming Soon: YAML Header in the Notebook