Skip to content
Generates "run this example" links for your readme.md
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
spec Change everything May 28, 2019
.eslintrc.json init Mar 2, 2019
.gitignore Allow generating link from multiple code blocks Mar 11, 2019
LICENSE Initial commit Mar 2, 2019
README.md Update README.md May 28, 2019
index.js Change everything May 28, 2019
package.json Change everything May 28, 2019
yarn.lock Add debug output Mar 3, 2019

README.md

Codesandbox Example Links Codeship Status for featurist/codesandbox-example-links

This project helps to manage runnable examples for javascript projects.

It covers both cases of project README on github and external docs website.

How it works

There is a CLI/API to replace magic placeholders in a markdown files with one of the following:

  • iframe with a codesandbox project
  • "Run this example" link to a codesandbox project
  • code snippet extracted from a file on a file system

Example

Given the following project structure:

.
├── demo-project
│   ├── index.html
│   ├── package.json
│   └── src
│       ├── app.jsx
│       └── index.js
├── docs
│   └── README.md

Where docs/README.md looks like this:

## An Example

[view code](/demo-project/src/index.js)

[codesanbox](/demo-project)
npx codesandbox-example-links --output-dir=. ./docs/README.md

Will produce a README.md in the root of the project with the following contents:

## An Example

```js
import * as hyperdom from "hyperdom";
import App from "./app";

hyperdom.append(document.body, new App());

```

<a href="https://codesandbox.io/api/v1/sandboxes/define?parameters=N4IgZglgNgpgziAXKAdAIwIZplATgYyVHwHsA7AFxkqRGAB0yACJ-kAB13hgrjcSYBtRixZtqANzYAaEaLYALAJ7sYuACYkAtmzkBdRgF8Qh6SAhl1MAB4oFFLVCIhSlahVoAeAIQARAPIAwgAqAJoACgCiTPaOAHyMnrFQCWSJCjAY6qn0FJ4UEBSwceEYBDhMAMoYlmgk1p4A9AVFMDl5WjwYTPgKZXA8ALxsAKrBAGIAtAAcbEyNqU0ZWTlknnXqSu2e6hASTBDqwyAY7OxscU27Equ5nnD4uBDsFExwBMfv-I0WVrYAVnwQNtGg8ni9Fo0NltGIlGslUiYzOwMPgANYYADmMBQgPIzlcVBoiDocjYZAwnX4rBAylUGm0kxslPYsBkZJAEjUcAg5GpbAAjCgAAwi9nMGlWMHPAp8pA0gASKjUmi0TCsWhITAAUpVxWIQFoMBZ-eZLDY7A4oPqadKXkCBAwJQa4BQyhRTSjylADubbMkmJNJiRVGkQLJnTS0ABXaDqT1lfAVGNx31_S2OXQS0wcqyhqxkfAQeDUp2iKNYHCTTjcCiTOkq7SmoUAFjF4bkBobDJ08rYUAwVFdWZYOYlbCsEl8MHz1CLJflZfkHETVZjllguFNA6HHpAcjHBrRMCUAHcSBoHUIDGRDIwkSAvo1TuxcXBrATyESPCSIFp2BerwAFRMBgcAxMqPZMGAuDaDS3aqmwADcsJkDYAG4K8VhgBg0ZQK8-ADnA4EAIJnEwS5cOauAABQAJQUZ2TBcBQ0a4MwOx7Kk5YsJ4A7YCkp59BQADk4FKCQbFMBSnQAPxME0_E4NxPGeBY7DRq8FDKscVDWHuTBoL8FiYrpCgQHAKAyTAcwLExvHXHE5kURQ5mWdZhhXFxTFeTcKHZkY96mI-BA_H6b6fm4xLmP-gFMCBYEQfSqrQbBaqKJBiEgP5f4Ya8ZHsKlcFsCgz5nMhqEIdoKAvtQ6g0Zo-DRp0lDoCQmzSNJMCnkwBX0XR_kmIYhhAA" target="_blank" rel="noopener noreferrer">Run this example</a>

Real world example

https://hyperdom.org

Usage

  • manually create sandbox for your example
  • download it into your project
  • insert magic links in markdown files
  • repeat for all examples
  • npx codesandbox-example-links --output-dir=./dist docs/*.md

The above command renders links. Add --iframe option to generate iframes instead.

Magic links

[codesanbox](/demo-project) - turns into either link or an iframe, depending on --iframe option

[view code](/path/to/file.js) - turns into a code snippet containing file.js

[view code](/path/to/file.jsL#3) - turns into a code snippet containing a fragment of file.js starting at line 3 onwards

[view code](/path/to/file.jsL#3-L10) - turns into a code snippet containing a fragment of file.js, lines 3 to 10

API

const generateLinks = require('codesandbox-example-links')

const input = fs.readFileSync('readme.md', {encoding: 'utf-8'})
const output = generateLinks(input, {iframe: true})

Debug

As of this writing, codesandbox api is sort of short on validation errors. So if generated links don't work, you might find some additional debug info useful. Set DEBUG=codesandbox-example-links to get some.

You can’t perform that action at this time.