diff --git a/docs/conf.py b/docs/conf.py
index cad48da..8619605 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -13,7 +13,6 @@
 import os
 from importlib import metadata
 
-
 # -- Project information -----------------------------------------------------
 
 project = "mockup"
@@ -57,7 +56,10 @@
 nb_merge_streams = True
 
 # https://myst-nb.readthedocs.io/en/latest/authoring/custom-formats.html#write-custom-formats
-nb_custom_formats = {".py": ["jupytext.reads", {"fmt": "py:percent"}]}
+# ! if you use it, then you cannot directly execute the notebook in the browser in colab
+# (the file needs to be fetched from the repository)
+# just keep both syncing it using papermill
+# nb_custom_formats = {".py": ["jupytext.reads", {"fmt": "py:percent"}]}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
diff --git a/docs/tutorial/.jupytext b/docs/tutorial/.jupytext
new file mode 100644
index 0000000..46e9467
--- /dev/null
+++ b/docs/tutorial/.jupytext
@@ -0,0 +1,2 @@
+# all notebooks in this directory are in the percent format
+formats = "ipynb,py:percent"
diff --git a/docs/tutorial/tutorial.ipynb b/docs/tutorial/tutorial.ipynb
new file mode 100644
index 0000000..6bce07b
--- /dev/null
+++ b/docs/tutorial/tutorial.ipynb
@@ -0,0 +1,78 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "62cb84c2",
+   "metadata": {},
+   "source": [
+    "# Mockup tutorial"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "825cc996",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from mockup import mockup"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d3ac73ba",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mockup.add_one(-11)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f3a3d02a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "list(mockup.flatten_ints([[9, 11], [12], [4, 5]]))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9cf7157d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "c2 = mockup.Circle.from_circumference(100)\n",
+    "round(c2.radius, 3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4ae5341c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "c2  # repr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1bc4ca39",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "cell_metadata_filter": "-all",
+   "main_language": "python",
+   "notebook_metadata_filter": "-all"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}