docs: initial version of starter notebook

Author: ssmirr

README.md

@@ -11,7 +11,7 @@ Follow these three simple steps:
 
 ## 📚 Create repository for your notebook
 
-[Click here](https://github.com/ottomatica/docable-starter-template/generate) to use this repository as a template for your first notebook, or alternatively [fork it](https://github.com/ottomatica/docable-starter-template/fork).
+[Click here](https://github.com/ottomatica/docable-starter-template/generate) to use this repository as a _template_ for your first notebook, or alternatively [fork it](https://github.com/ottomatica/docable-starter-template/fork).
 
 Each Docable notebook is managed and stored in its own GitHub repository. Think of a GitHub repository as the whole notebook 📒 and its markdown files as the pages of the notebook 📄. You can create a new repo or use one of your existing ones. However, for this quick onboarding guide we recommend [using this repository as a template](https://github.com/ottomatica/docable-starter-template/generate) because it already contains a few example notebooks which will be useful to use as a starting point.
 
@@ -26,13 +26,13 @@ cd docable-starter-template
 code starter-notebook.md # we're using VS Code here, but feel free to use anything else
 ```
 
-We included a [`starter-notebook.md`](./starter-notebook.md) in this repository. It includes explaination of the structure of a notebook file, and the supported content.
+👉 We included a [`starter-notebook.md`](./starter-notebook.md) in this repository. It includes explaination of the structure of a notebook file, and the supported content.
 
 ## 🚀 Publish
 
 [Login to `https://docable.cloud`](https://docable.cloud/login) using your GitHub account. 
 
-> ❕ If it's your first time using `docable.cloud`, you will see a list of permissions we need to be able to create your account. Please read them and accept to continue.
+> ❕ _If it's your first time using `docable.cloud`, you will see a list of permissions we need to be able to create your account. Please read them and accept to continue._
 
 <p align="center">
   <img src="img/docable-github-publishing.png"  width="75%">

starter-notebook.md

@@ -0,0 +1,54 @@
+<!-- 
+targets:
+    - type: docker
+      name: starter-notebook
+      image: node:12-buster
+-->
+
+# Starter Notebook bab
+
+In this starter notebook, we explain the basic structure of a notebook file as well as some examples of supported interactive content.
+
+Docable notebooks are markdown files which are rendered as an interactive document supporting infrastructure needed for exeuting it. The notebook files consist of two parts:
+
+- ⚙ [Setup (optional)]()
+- 📄 [Notebook content](#-notebook-content)
+
+## ⚙ Setup (optional)
+
+> ❕ _The setup is optional and is only recommended if you need to use our more advanced computing environment management features. Otherwise our defaults will usually be sufficient._
+
+Setup is written as a _commented_ YAML snippet in the beginning your notebook file. In setup you can specify settings related to target environments in this notebook. For example, you can configure setup to create multiple target environments which will be accessible in the notebook, or use a specific Docker image.
+
+Here is an example for a notebook with one target environment, using `node:12-buster` Docker image. Note, if you don't include a setup snippet at all, this is the default Docable uses:
+
+```
+<!-- 
+targets:
+    - type: docker
+      name: starter-notebook
+      image: node:12-buster
+-->
+```
+
+## 📄 Notebook content
+
+The content is written in markdown (Docable also supports custom HTML snippets too, for example you can embedding your external window etc.). And to create the interactive parts of notebook, the Docable cells, we use custom markdown annotations as explained below.
+
+> ❕ _Our custom annotations are ignored by GitHub rendering, so you can even make your `README.md` file be an interactive notebook when viewed on `docable.cloud` while still looking the same as before when viewed on GitHub._
+
+Here is an example of this custom markdown annotation:
+
+    ```bash | {type: 'command'}
+    echo "hello world"
+    ```
+
+This ☝ is similar to a normal markdown code block with language set to `bash`. And Docable's annotation is the JSON after code block's language: `| {type: 'command'}`. This tells Docable to make code block an interactive cell behaving as a `command`. Here is how it looks when viwed as a notebook ([click here to view this on docable.cloud](https://docable.cloud/ottomatica/docable-starter-template/starter-notebook.md)):
+
+```bash | {type: 'command'}
+echo "hello world"
+```
+
+You just created your first interactive notebook cell! 🎉
+
+...