Configuring imports from Github

Learn how to configure the meta properties of your Kyso reports by 1.) adding a kyso.yaml file to your repositories or 2.) including this metadata in the notebooks themselves.

Using kyso.yaml

You can add a kyso.yaml file to your directory in which you can determine the metadata of your reports and projects. Below are some of the most popular options to include in these files:

  • main: specifies the main file you want your visitors to see.

  • title: specifies the title of the post.

  • description: specifies the description of the post.

  • preview: path to your preview image.

  • tags: any tags you want added to the post.

  • email: an email address that a Kyso team member used to sign up to Kyso and they will be attributed as the creator on Kyso. This only applies to child posts.

  • created_at: to set the post date just add this field as a string that can be parsed by moment.js (https://momentjs.com/guides/#/parsing/). This only applies to child posts.

  • updated_at: same as created_at but for when the post is updated. This only applies to child posts.

  • posts: choose the sub-directories you want to be pulled into Kyso as separate posts.

  • branch: choose to only accept a certain branch on Kyso. You can push your master branch without needing to specify anything in the kyso.yaml file. If you want to push another branch to Kyso, you must specify it in the kyso.yaml file.

Note: the term 'child posts' refers to sub-directories within a Github repository. With the Kyso import feature you can set up your connection such that all folders are pulled in as their own posts on Kyso. These are the 'child posts' of the main directory - the Readme.md of the repository.

For example, let's say you have a directory with a my-article.ipynb notebook and you want Kyso to only accept the staging branch you could create a 'kyso.yaml' file like the following:

title: "My awesome post"
description: "This is a description of what I did in my awesome post"
preview: "images/preview-image.png"
branch: "staging"
main: "my-article.ipynb"
tags:
- apples
- organges

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.

Setting the 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 each time, 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:

---
title: "My awesome post"
description: "This is a description of what I did in my awesome post"
branch: "staging"
main: "my-article.ipynb"
tags:
- apples
- organges
---

‚Äč