README.md

Interactive code examples

for documentation, education and fun 🎉

Embed interactive code snippets directly into your product documentation, online course or blog post.

┌───────────────────────────────┐
│ def greet(name):              │
│   print(f"Hello, {name}!")    │
│                               │
│ greet("World")                │
└───────────────────────────────┘
  Run ►  Edit  ✓ Done
┌───────────────────────────────┐
│ Hello, World!                 │
└───────────────────────────────┘

Highlights:

• Automatically converts static code examples into mini-playgrounds.
• Lightweight and easy to integrate.
• Sandboxes for any programming language, database, or software.
• Open source. Uses the permissive Apache-2.0 license.

For an introduction to Codapi, see this post: Interactive code examples for fun and profit.

Installation

Install with npm:

npm install @antonz/codapi

Or use a CDN:

<script src="https://unpkg.com/@antonz/[email protected]/dist/snippet.js"></script>

Optional styles:

<link rel="stylesheet" href="https://unpkg.com/@antonz/[email protected]/dist/snippet.css" />

Usage

See the guide that best fits your use case:

• HTML/Markdown
• Docusaurus
• Docsify
• WordPress
• Notion
• Dev.to/Medium/Substack/Newsletter (or other platforms that do not support JavaScript embeds)

You'll also need a working Codapi server, either cloud-based at codapi.org or self-hosted. Unless you are using an in-browser playground (see below).

Advanced features

Codapi offers a number of features that go beyond simple code playgrounds:

• Output modes for displaying images, HTML fragments and interactive DOM.
• Templates for hiding parts of the code behind the scenes.
• Multi-file playgrounds.
• Custom actions.
• Code cells for a Jupyter notebook-like experience.

In-browser playgrounds

Most playgrounds (like Go or MongoDB) run code on the Codapi server.

But there are some playgrounds that work completely in the browser, no Codapi server required:

• JavaScript
• Fetch
• Lua
• PHP
• PostgreSQL
• Python
• Ruby
• SQLite

Styling

The widget is unstyled by default. Use snippet.css for some basic styling or add your own instead.

Here is the widget structure:

<codapi-snippet sandbox="python" editor="basic">
    <codapi-toolbar>
        <button>Run</button>
        <a href="#edit">Edit</a>
        <codapi-status> ✓ Done </codapi-status>
    </codapi-toolbar>
    <codapi-output>
        <pre><code>Hello, World!</code></pre>
    </codapi-output>
</codapi-snippet>

codapi-snippet is the top-level element. It contains the the toolbar (codapi-toolbar) and the code execution output (codapi-output). The toolbar contains a Run button, one or more action buttons (a) and a status bar (codapi-status).

License

Copyright 2023-2024 Anton Zhiyanov.

The software is available under the MIT License.

Stay tuned

★ Subscribe to stay on top of new features.