{"id":13594507,"url":"https://github.com/ottomatica/docable-notebooks","last_synced_at":"2025-04-07T17:09:01.037Z","repository":{"id":40284064,"uuid":"273791647","full_name":"ottomatica/docable-notebooks","owner":"ottomatica","description":":ledger: Next-Generation Interactive Notebooks","archived":false,"fork":false,"pushed_at":"2023-01-27T03:16:13.000Z","size":13372,"stargazers_count":309,"open_issues_count":24,"forks_count":19,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-31T14:13:54.908Z","etag":null,"topics":["execution","notebook","tutorials","workshops"],"latest_commit_sha":null,"homepage":"https://docable.cloud","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ottomatica.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-20T22:09:15.000Z","updated_at":"2024-12-13T08:46:04.000Z","dependencies_parsed_at":"2023-02-15T04:46:22.775Z","dependency_job_id":null,"html_url":"https://github.com/ottomatica/docable-notebooks","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fdocable-notebooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fdocable-notebooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fdocable-notebooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ottomatica%2Fdocable-notebooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ottomatica","download_url":"https://codeload.github.com/ottomatica/docable-notebooks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694876,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["execution","notebook","tutorials","workshops"],"created_at":"2024-08-01T16:01:34.737Z","updated_at":"2025-04-07T17:09:01.010Z","avatar_url":"https://github.com/ottomatica.png","language":"JavaScript","readme":"# Docable\n\n\u003e Next-Generation Interactive Notebooks 📒\n\n`Docable` notebooks provide a literate programming environments which works great for writing and publishing interactive tutorials, training material for courses, blogs, or simple infrastructure runbooks. \n\n✨The interactive components include specialized cells for terminals, commands, scripts, files contents, quizes, and more. These interactive cells can be customized using several parameters and allow the reader to modify and execute the document.\n\n✍ Authoring a `Docable` notebook is as easy as writing a Markdown file. The Markdown file, when opened in `Docable` will be rendered into interactive cells, which can be run, edited, and shared. This results in a literate programming environment for Markdown files. `Docable` notebook Markdown files remain 100% compatible and render normally on GitHub, etc.\n\nHere is a preview of a markdown vs. GitHub vs. how the notebook works:\n\n![](docs/img/md_docable_github.png)\n\n---\n\n## Contents\n\n* [Using Docable Notebooks](#using-docable-notebooks)\n  - [Example notebooks](#example-notebooks)\n  - [Editing cells](#editing-cells)\n  - [Creating file content, using variables](#creating-file-content-using-variables-and-more)\n  - [Cell format](#Cell-format)\n  - [Docable CLI](#docable-cli)\n* [Notebook Server](#notebook-server)\n  - [Notebook treeview](#notebook-treeview)\n  - [Managing environments](#target-environments)\n  - [Managing variables](#variables)\n* [Installing and Running Notebooks](#installing-and-running-docable-notebooks)\n* [Quick Reference](#quick-reference)\n\n## Using Docable Notebooks\n\nWith docable, your markdown will be translated from this:\n\n~~~\n`figlet` will translate the given text into an ascii banner. Try it out!\n\n```bash| {type: 'command'}\nfiglet docable\n```\n~~~\n\n\nInto this ✨:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/docable-figlet.gif\"  width=\"75%\"\u003e\n\u003c/p\u003e\n\nDocable's interactive cells are simply Markdown code block (```) with addition of a few annotations as a JSON which defines the type of the cell and other details about how it should be executed. In the example above, we created a command cell by adding `|{type: 'command'}`. \n\n✨ _These code blocks are 100% compatible with GitHub's Markdown rendering and the JSON is simply ignored. So you can update your existing `README.md` or other documentation files to make them executable by Docable while they still look the same as before when viewed on GitHub!_\n\nFor a list of supported cells and supported modifiers for each type see [quick reference](#quick-reference) section below.\n\n### Example Notebooks\n\nYou can find example for most of the supported features in the [documentation examples](docs/examples/) or try an [online notebook](https://docable.cloud/):\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/banner.png\"  width=\"90%\"\u003e\n\u003c/p\u003e\n\n### Editing Cells\n\nAll Docable cells can be edited and run again. Additionally, the `script` and `file` cells provide the same code editor you use on VSCode which include syntax highlighting and [intellisense](https://code.visualstudio.com/docs/editor/intellisense) documentation. \n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/docable-edit-script.gif\"  width=\"49%\"\u003e\n  \u003cimg src=\"docs/img/docable-edit.gif\"  width=\"49%\"\u003e\n\u003c/p\u003e\n\n### Creating file content, using variables, and more.\n\nDocable has been designed after [studying over 600 online tutorials](http://chrisparnin.me/pdf/docable_FSE_20.pdf) and discovering issues that contribute to poor learner experiences. We've designed a few additional features that smooth over these issues for tutorial takers and authors.\n\nOne of the most common problem was the numerous and inconsistent ways tutorials asked someone to edit a file on a server.\nDocable _`file` cells_ take care of creating paths, setting file permissions and owners, and filling in variable content with a simple click.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/docable-variable.gif\"  width=\"75%\"\u003e\n\u003c/p\u003e\n\n_Variables can be stored securely in Docable Notebook server and automatically masked in the outputs. See [#variables](#variables) section below for more details._\n\n## Cell Format\n\nTo create a notebook, you simply create a markdown file and provide a few annotations on code blocks.\n\n~~~\n```bash|{type: 'command'}\nfiglet docable\n```\n~~~\n\nA docable file cell can be created as follows.\n~~~bash\n```js|{type:\"file\",path:'id.js'}\nMath.random().toString(36).substring(2);\n```\n~~~\n\nSpecial annotations can also be provided on commands, allowing even better experiences, such as auto-detecting platforms to enable/disable cell execution.\n\n~~~bash\n```bash|{type: 'command', privileged: true, platform: 'win32'}\nchoco install figlet-go -y\n```\n~~~\n\n\u003ckbd\u003e\n\n![privileged](docs/img/docable-privileged.png)\n\n\u003c/kbd\u003e\n\n### Docable CLI\n\nYou can also run your markdown files with the [docable CLI](https://github.com/ottomatica/docable), allowing you to run your notebooks in CI/CD or gitops workflows: \n\n`$ docable report server-test.md`\n\n\u003ckbd\u003e\n\n\u003cimg src=\"docs/img/docable-cli.png\" width=300px\u003e\n\n\u003c/kbd\u003e\n\n## Notebook Server\n\nThe notebook server can run locally and allow you to interact with your notebooks in your web browser. Run the command below to start the server in your current working directory:\n\n```bash\n# if using the Docable tray app\ndocable-server .\n\n# if installed from source\ndocable-notebooks .\n```\n\nThen you will be able to browse your notebooks on `http://localhost:3000/`. On the home page you will see the notebook treeview which allows you navigate and open different pages.\n\n### Notebook Treeview\n\nTo access your notebooks, you can browse and click on a notebook in the tree.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/docable-tree.png\"  width=\"75%\"\u003e\n\u003c/p\u003e\n\n### Target Environments\n\nDocable has different connectors to run against different kinds of environments. Use the dropdown menu to select an environment.\n\n\u003ckbd\u003e\n\n![docable-env](docs/img/docable-env.png)\n\n\u003c/kbd\u003e\n\n* **local**: The default environment is your local computer.\n* **Docker**: If there is a running docker service, Docable can create a container to run operations in.\n* **ssh**: Any virtual machine, created locally, or remotely can be targeted. You can use configure a new ssh connection at http://localhost:3000/targets, and then select in the dropdown menu of your notebook.\n\n### Variables\n\nAs we showed above, Docable supports variables in the notebooks. These variables can be stored in the notebook server to be reused in the future and in multiple notebooks. \n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/docable-variables-secrets.png\"  width=\"75%\"\u003e\n\u003c/p\u003e\n\n\n\n🔐 Sometimes these variables contain sensitive information such as API tokens, passwords and ssh keys. Notebook server can encrypt and store these variables for future reuse. As shown above, Docable automatically masks these values when they are displaying anywhere in the notebook or the execution outputs. \n\n## Installing and Running Docable Notebooks\n\nYou can run Docable Notebooks by installing either the Docable tray app or the CLI server from source. We recommend trying our [tray app](#docable-tray-app-recommended) since it includes closed-source features not included in this repository.\n\n### Docable Tray App (recommended)\n\nYou can find [installation instructions here](./docs/install.md). Docable tray is a GUI app which runs in your operating system's menu bar and allows you control (start/stop) the Docable server. This is the recommended method of running Docable Notebooks which includes the Terminal cell feature.\n\n### Install from source\n\nRequires [node.js \u003e= 12.x](https://nodejs.org/).\n\nSimply clone this repository.\n```bash|{type: 'command'}\ngit clone https://github.com/ottomatica/docable-notebooks/\n```\n\nInstall dependencies and start server.\n```bash|{type: 'command'}\ncd docable-notebooks\nnpm install\nnpm run dev\n```\n\nYour Docable Notebooks can be interacted with at http://localhost:3000. You can set `PORT=4000` to use a different address.\n\nYou can also run directly, which will serve up notebooks in the current directory. You can change this with `--notebook_dir \u003cpath\u003e`.\n\n```bash|{type: 'command'}\ncd docable-notebooks\nnpm link\ndocable-notebooks\n```\n\n_Installation help for running from source:_\n* If you have problems with `gyp` on MacOs, [see this simple guide](https://medium.com/flawless-app-stories/gyp-no-xcode-or-clt-version-detected-macos-catalina-anansewaa-38b536389e8d) for setting up/reinstalling CommandLineTools.\n* If updating existing repository, make sure to run `npm update \u0026\u0026 npm install` to get updates from modules.\n\n## Quick Reference\n\n* Run commands in cell: `{type: 'command'}`.\n    * Command modifiers.\n        - `stream`: if `true`, then stdout/stderr is printed in output block as available.\n        - `shell`: If given, then run command in provided shell. Supported: `'bash'`, `'powershell'`\n        - `path`: set working directory of command.\n        - `privileged`: Ask permission for an admin shell---useful for local installation. Only supported in local connections.\n        - `user`: run command as as given user.\n\n* Create file with given content: `{type: 'file'}`.\n    * File modifiers:\n        - `path`: **Required**. The path to place contents.\n        - `permission`: Set permissions of file, use any format given by supported by chmod (`'u+x'`, `'700'`).\n        - `user`: Owner of file.\n        - `mode`: If `'append'`, will add content to file instead of overwriting.\n\n* Script content: `{type: 'script'}`.\n   - Execute content using the language of content in the first part of fence infostring. Supported: `js`. Create issue if another language is needed!\n\n* Multiple-choice quiz: `{type: 'quiz'}`\n    * Quiz modifiers:\n        - `quiz_type`: This can be set to either `multichoice` or `singlechoice`.\n        - `quiz_answers`: Specify the correct answer for the quiz, using index of your choices starting from 0. If more than one choice, separate by comma `0,1`.\n        - content of cell should be checkbox bulletpoint `- [ ] foo` \n\n* Embed interactive terminal: `{type: 'terminal'}`.\n    * Terminal modifiers:\n        - `command`: The command to start your interactive shell. For example, this can be `bash` for bash shell or `node` for starting a node.js REPL.\n\n* Conditions:\n  - `platform`: Allow cell to be executed only if connection is to given platform. Supported: `win32`, `darwin`, `linux`. \n  - `failed_when`: Node.js expression to evaluate whether command succeeded or not. For example, `'!stdout.includes(\"download completed.\")'`.\n  \n* Variables:\n  - `variables`: A comma seperated list of variables referenced in cell content. Inside cell block, use `{{variable_name}}`.\n     \n\nExperimental features:\n  - `chart`: Create chart from cell output. \n  - `highlight`: Select text in output, and create a popover with more information.\n  - `block`: Select text in output, and create a box, with height rows.\n  - `range`: Select lines from cell to highlight. Useful for calling attention.\n  - `svg`: Render content as svg.\n  - `tty`: Run command with pty.\n","funding_links":[],"categories":["JavaScript","tutorials"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fottomatica%2Fdocable-notebooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fottomatica%2Fdocable-notebooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fottomatica%2Fdocable-notebooks/lists"}