Codesandbox Example Links
A CLI/API to replace magic placeholders in a markdown files with:
iframe
with a codesandbox project- "Run this example" link to a codesandbox project
- code snippet extracted from a file on a file system
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)
[codesandbox](/demo-project)
Then running:
npx codesandbox-example-links --output-dir=. ./docs/README.md
Will produce a ./README.md
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>
- 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.
[codesandbox](/demo-project)
- turns into either link or an iframe, depending on --iframe
option.
[codesandbox](/demo-project?module=/path/to/file)
- as above, but opens the project on a specific file. Other codesanbdox embed options can be specified too.
[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.
const generateLinks = require('codesandbox-example-links')
const input = fs.readFileSync('readme.md', {encoding: 'utf-8'})
const output = generateLinks(input, {iframe: true})
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.