Location for Stencila examples?


Hello Stencila Community!

We need your input! What is your preferred location for examples of Stencila interactive documents?

At the moment we have a set of examples in the main Stencila repository So when you clone this repository, you also get some examples you can play with.
But we also have a separate repository called examples Which at the moment contains a variety of examples for data analysis.

This is not consistent and probably confusing. What do you think would be the best idea?

  1. Have all examples in the separate repository and none in the main stencila repository (which essentially will contain the engine of Stencila)?

  2. Have 3-4 flagship examples in the stencila repository sohwcasing the key functionalities and also have a comprehensive examples repository with potentially many various examples, including the flagship ones?

Or maybe something else?

Please comment under this post with your ideas!
Thank you!


I think both sets of examples are necessary and like your option 2:

  • in stencila/stencila repo :

    • just 3-5 kitchensink examples (everything in them but not necessarily nice to read) focused on developer use, maybe one with a single Article, one with a Sheet, and one with an Article and a Sheet testing translcusions between them;
    • It’s important to these comprehensive (but not too long) for developers to quickly test on
    • if it’s confusing to have an examples directory in this repo (I think it is a bit), we could move then to tests/examples
  • in stencila/examples repo:

    • have as many examples as people want to contribute!
    • have a README which highlights features 3 or 4 flagship examples but also directs people to the ones they might be most interest in… “If you’re a R user you might be intested in…”


I prefer to “have all examples in the separate repository”.

You could have two folders in stencila/examples repository, one for the kitchensink examples and another for all the others and use Git submodule to include the examples into stencila/stencila.


I like @rgaiacs idea. Let’s try going with it. We can always amend, if needs be.