https://github.com/featurist/codesandbox-example-links
Generates "run this example" links for your readme.md
https://github.com/featurist/codesandbox-example-links
codesandbox javascript
Last synced: 5 months ago
JSON representation
Generates "run this example" links for your readme.md
- Host: GitHub
- URL: https://github.com/featurist/codesandbox-example-links
- Owner: featurist
- License: mit
- Created: 2019-03-02T23:24:20.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T09:42:56.000Z (over 2 years ago)
- Last Synced: 2024-08-09T20:29:42.777Z (9 months ago)
- Topics: codesandbox, javascript
- Language: JavaScript
- Homepage:
- Size: 265 KB
- Stars: 15
- Watchers: 5
- Forks: 2
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[Codesandbox](https://codesandbox.io) Example Links [](https://app.codeship.com/projects/329497)
-----------
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
## 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:
```markdown
## An Example
[view code](/demo-project/src/index.js)
[codesandbox](/demo-project)
```
Then running:
```sh
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());
```
Run this example
### 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
`[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](https://codesandbox.io/docs/embedding#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.
### API
```js
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.