Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/elboman/gatsby-remark-embedded-codesandbox
A Gatsby Remark plugin for embedding Codesandbox given a folder of files
https://github.com/elboman/gatsby-remark-embedded-codesandbox
codesandbox embedded gatsby gatsby-plugin gatsby-remark gatsbyjs
Last synced: 26 days ago
JSON representation
A Gatsby Remark plugin for embedding Codesandbox given a folder of files
- Host: GitHub
- URL: https://github.com/elboman/gatsby-remark-embedded-codesandbox
- Owner: elboman
- License: mit
- Created: 2018-04-23T09:30:32.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-07T09:17:13.000Z (almost 2 years ago)
- Last Synced: 2024-09-30T10:01:53.215Z (about 1 month ago)
- Topics: codesandbox, embedded, gatsby, gatsby-plugin, gatsby-remark, gatsbyjs
- Language: JavaScript
- Size: 748 KB
- Stars: 32
- Watchers: 3
- Forks: 8
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# gatsby-remark-embedded-codesandbox
[](https://www.npmjs.com/package/gatsby-remark-embedded-codesandbox)
[](https://travis-ci.org/elboman/gatsby-remark-embedded-codesandbox)
This plugin adds support for generating embedded [CodeSandbox](https://codesandbox.io/), specifying a folder in local files to populate the contents of it.
This enables example code to be stored along side of, and revisioned with, your website content.
This plugin is based on [gatsby-remark-code-repls](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-code-repls).
## Getting started
To embed a CodeSandbox editor in you Markdown/remark content, simply add a link with the custom protocol pointing to the folder desired folder:
```md
[embedded example](embedded-codesandbox://example/folder)
```
It will scan the folder and generate the proper html to include the editor.
## Overview
For example, given the following project directory structure:
```
examples/
├── hello-world-example
│ ├── package.json
│ ├── index.html
│ └── index.js
├── some-other-example
│ ├── package.json
│ └── index.js
```
These example files can be referenced via links in Markdown that get transformed
to embedded editors. For example:
```md
[hello world example](embedded-codesandbox://hello-world-example)
```
> Note: If you are using [gatsby-remark-responsive-iframe](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-responsive-iframe), it must appear _after_ this plugin in your configuration or the iframe will not be transformed.
### Package.json file
CodeSandbox [**requires** a `package.json` file](https://codesandbox.io/docs/importing#how-it-works) in order to work.
This is useful because you can define dependencies such as `react` that will be included in the sandbox.
The plugin will search for the `package.json` file in the example folder.
If not found, it will try in the parent folders up until it reaches the _examples root folder_.
If nothing is found it fall back to a default one:
```json
{
"name": "example",
"dependencies": {}
}
```
### Overriding options on single sandboxes
It's possible to override the global [embedding options](https://codesandbox.io/docs/embedding#embed-options) on a per-sandbox basis, by simply passing them as url query in the generating link.
```md
[hello world example](embedded-codesandbox://hello-world-example?view=split)
```
The options will be merged with the global one.
### How does it work?
CodeSandbox uses the [same URL compression schema used by the Babel REPL](https://github.com/babel/website/blob/c9dd1f516985f7267eb58c286789e0c66bc0a21d/js/repl/UriUtils.js#L22-L26) to embed the local code example in a URL.
This is than passed to the (awesome) [define api](https://codesandbox.io/docs/importing#define-api) to generate a sandbox on the fly.
## Installation
`yarn add gatsby-remark-embedded-codesandbox`
## Usage
```javascript
// In your gatsby-config.js
{
resolve: 'gatsby-transformer-remark',
options: {
plugins: [
{
resolve: 'gatsby-remark-embedded-codesandbox',
options: {
// Required:
// Example code folders are relative to this dir.
// eg src/_examples/some-example-folder
directory: `${__dirname}/src/_examples/`,
// Optional:
// Custom protocol for parsing the embedding link
// default:
protocol: 'embedded-codesandbox://',
// Customise CodeSandbox embedding options:
// https://codesandbox.io/docs/embedding#embed-options
// default:
embedOptions: {
view: 'preview',
hidenavigation: 1,
},
// Customise the embedding iframe given the generated url
// default:
getIframe: url => ``
}
}
]
}
}
```