Documentation (codesandbox#387)

* Start of docs

* Docs update

* Fix sorting

* Finish some docs

* Don't redirect in browser

* Add autolink for header

* More docs

* More docs

* Responsiveness

* Update embed docs

* Change header to 'Updates'

* Fix padding

* Fix docscroll

* improvements

* Fix **extremely** weird bug of page jumping

* Add Run on Click

* Fix linter errors

Author: CompuIves

packages/app/src/app/store/entities/sandboxes/utils/create-zip/index.js

@@ -4,6 +4,7 @@ import { saveAs } from 'file-saver';
 
 import type { Sandbox, Module, Directory } from 'common/types';
 import { react, reactTs, vue, preact, svelte } from 'common/templates/index';
+import slugify from 'common/utils/slugify';
 import resolveModule from 'common/sandbox/resolve-module';
 
 const CSSTag = (resource: string) =>
@@ -48,25 +49,6 @@ export function getIndexHtmlBody(
   return `<div id="root"></div>`;
 }
 
-function slugify(text) {
-  const a = 'àáäâèéëêìíïîòóöôùúüûñçßÿœæŕśńṕẃǵǹḿǘẍźḧ·/_,:;';
-  const b = 'aaaaeeeeiiiioooouuuuncsyoarsnpwgnmuxzh------';
-  const p = new RegExp(a.split('').join('|'), 'g');
-
-  /* eslint-disable */
-  return text
-    .toString()
-    .toLowerCase()
-    .replace(/\s+/g, '-') // Replace spaces with -
-    .replace(p, c => b.charAt(a.indexOf(c))) // Replace special chars
-    .replace(/&/g, '-and-') // Replace & with 'and'
-    .replace(/[^\w\-]+/g, '') // Remove all non-word chars
-    .replace(/\-\-+/g, '-') // Replace multiple - with single -
-    .replace(/^-+/, '') // Trim - from start of text
-    .replace(/-+$/, ''); // Trim - from end of text
-  /* eslint-enable */
-}
-
 export function createPackageJSON(
   sandbox: Sandbox,
   dependencies: Object,

packages/app/src/embed/App.js

@@ -70,6 +70,7 @@ type State = {
   editorSize: number,
   forceRefresh: boolean,
   expandDevTools: boolean,
+  runOnClick: boolean,
   highlightedLines: Array<string>,
 };
 
@@ -92,6 +93,7 @@ export default class App extends React.PureComponent<{}, State> {
       highlightedLines,
       forceRefresh,
       expandDevTools,
+      runOnClick,
     } = getSandboxOptions(document.location.href);
 
     this.state = {
@@ -111,6 +113,7 @@ export default class App extends React.PureComponent<{}, State> {
       editorSize,
       forceRefresh,
       expandDevTools,
+      runOnClick,
       highlightedLines: highlightedLines || [],
     };
   }
@@ -198,7 +201,7 @@ export default class App extends React.PureComponent<{}, State> {
       );
     }
 
-    const { showEditor, showPreview, isInProjectView } = this.state;
+    const { showEditor, showPreview, isInProjectView, runOnClick } = this.state;
 
     return (
       <ThemeProvider
@@ -235,6 +238,7 @@ export default class App extends React.PureComponent<{}, State> {
             highlightedLines={this.state.highlightedLines}
             forceRefresh={this.state.forceRefresh}
             expandDevTools={this.state.expandDevTools}
+            runOnClick={runOnClick}
           />
         </Container>
       </ThemeProvider>

packages/app/src/embed/components/Content.js

@@ -11,7 +11,12 @@ import {
   getModulePath,
 } from 'app/store/entities/sandboxes/modules/selectors';
 
+import Fullscreen from 'common/components/flex/Fullscreen';
+import Centered from 'common/components/flex/Centered';
 import type { Sandbox, Module, ModuleError } from 'common/types';
+import theme from 'common/theme';
+
+import playSVG from './play.svg';
 
 const Container = styled.div`
   display: flex;
@@ -64,6 +69,7 @@ type Props = {
   forceRefresh: boolean,
   highlightedLines: Array<string>,
   expandDevTools: boolean,
+  runOnClick: boolean,
 };
 
 type State = {
@@ -90,6 +96,7 @@ export default class Content extends React.PureComponent<Props, State> {
       inInProjectView: false,
       codes: {},
       errors: [],
+      running: !props.runOnClick,
       tabs,
     };
   }
@@ -233,6 +240,28 @@ export default class Content extends React.PureComponent<Props, State> {
     this.setState({ tabs: this.state.tabs.filter((_, i) => i !== pos) });
   };
 
+  RunOnClick = () => (
+    <Fullscreen
+      style={{ backgroundColor: theme.primary(), cursor: 'pointer' }}
+      onClick={() => this.setState({ running: true })}
+    >
+      <Centered horizontal vertical>
+        <img width={170} height={170} src={playSVG} alt="Run Sandbox" />
+        <div
+          style={{
+            color: theme.red(),
+            fontSize: '2rem',
+            fontWeight: 700,
+            marginTop: 24,
+            textTransform: 'uppercase',
+          }}
+        >
+          Click to run
+        </div>
+      </Centered>
+    </Fullscreen>
+  );
+
   render() {
     const {
       sandbox,
@@ -266,6 +295,8 @@ export default class Content extends React.PureComponent<Props, State> {
 
     if (!alteredMainModule) throw new Error('Cannot find main module');
 
+    const { RunOnClick } = this;
+
     return (
       <Container>
         {showEditor && (
@@ -333,27 +364,31 @@ export default class Content extends React.PureComponent<Props, State> {
             only={showPreview && !showEditor}
             size={100 - editorSize}
           >
-            <Preview
-              sandboxId={sandbox.id}
-              template={sandbox.template}
-              isInProjectView={isInProjectView}
-              modules={alteredModules}
-              directories={sandbox.directories}
-              externalResources={sandbox.externalResources}
-              module={alteredMainModule}
-              addError={this.addError}
-              clearErrors={this.clearErrors}
-              preferences={this.getPreferences()}
-              setProjectView={this.props.setProjectView}
-              hideNavigation={hideNavigation}
-              setFrameHeight={this.handleResize}
-              initialPath={this.props.initialPath}
-              errors={errors}
-              corrections={[]}
-              dependencies={sandbox.npmDependencies}
-              shouldExpandDevTools={expandDevTools}
-              entry={sandbox.entry}
-            />
+            {!this.state.running ? (
+              <RunOnClick />
+            ) : (
+              <Preview
+                sandboxId={sandbox.id}
+                template={sandbox.template}
+                isInProjectView={isInProjectView}
+                modules={alteredModules}
+                directories={sandbox.directories}
+                externalResources={sandbox.externalResources}
+                module={alteredMainModule}
+                addError={this.addError}
+                clearErrors={this.clearErrors}
+                preferences={this.getPreferences()}
+                setProjectView={this.props.setProjectView}
+                hideNavigation={hideNavigation}
+                setFrameHeight={this.handleResize}
+                initialPath={this.props.initialPath}
+                errors={errors}
+                corrections={[]}
+                dependencies={sandbox.npmDependencies}
+                shouldExpandDevTools={expandDevTools}
+                entry={sandbox.entry}
+              />
+            )}
           </Split>
         )}
       </Container>

packages/app/src/embed/components/play.svg

@@ -52,6 +52,7 @@ export const getSandboxOptions = (url: string) => {
   result.enableEslint = url.includes('eslint=1');
   result.forceRefresh = url.includes('forcerefresh=1');
   result.expandDevTools = url.includes('expanddevtools=1');
+  result.runOnClick = url.includes('runonclick=1');
 
   return result;
 };

packages/common/url.js

@@ -0,0 +1,18 @@
+export default function slugify(text) {
+  const a = 'àáäâèéëêìíïîòóöôùúüûñçßÿœæŕśńṕẃǵǹḿǘẍźḧ·/_,:;';
+  const b = 'aaaaeeeeiiiioooouuuuncsyoarsnpwgnmuxzh------';
+  const p = new RegExp(a.split('').join('|'), 'g');
+
+  /* eslint-disable */
+  return text
+    .toString()
+    .toLowerCase()
+    .replace(/\s+/g, '-') // Replace spaces with -
+    .replace(p, c => b.charAt(a.indexOf(c))) // Replace special chars
+    .replace(/&/g, '-and-') // Replace & with 'and'
+    .replace(/[^\w\-]+/g, '') // Remove all non-word chars
+    .replace(/\-\-+/g, '-') // Replace multiple - with single -
+    .replace(/^-+/, '') // Trim - from start of text
+    .replace(/-+$/, ''); // Trim - from end of text
+  /* eslint-enable */
+}

packages/common/utils/slugify.js

@@ -0,0 +1,54 @@
+---
+title: "Documentation"
+authors: ["CompuIves"]
+url: /
+description: "Welcome to CodeSandbox! This documentation serves as a way for you to learn what CodeSandbox is, how to use it and what its APIs are."
+---
+
+## What is CodeSandbox
+
+CodeSandbox is an online editor that's built for web application development.
+Web application development is a growing field, and with all new configuration
+options it becomes harder and harder to focus on writing code. We make this
+easier by doing most configuration for you.
+
+This focus on web application development allows us to do many more
+optimizations. We can analyze npm dependencies, we can show custom error
+messages for known errors, we can make projects easily searchable by npm
+dependency. The possibilities are endless!
+
+## Our Values
+
+We started development of CodeSandbox with a single goal: make it easy to share
+projects, wherever you are. During development we started noticing other
+benefits though, and we decided to make three focus points for all further
+development.
+
+### Lower the Learning Curve
+
+With CodeSandbox you don't have to do anything to start programming. You don't
+have to set up a development environment, you don't have to install
+dependencies, you don't even need a laptop! During initial development we
+quickly noticed that other students at the university were using CodeSandbox to
+learn React, and we found this a great idea.
+
+We shifted our focus to make it as easy as possible to start a project, and to
+make UI and UX as easy as possible.
+
+### Empower Sharability and Discoverability
+
+The initial reason Ives wanted to build CodeSandbox was because of sharability.
+The JavaScript community is one of the most active communities out there;
+libraries and projects are shared everyday. Still, it was very hard to share a
+project you've built with, for example, Vue or React. With CodeSandbox you can
+easily build, import or export your project and share a single URL.
+
+We also aim to make discoverability very easy: it should be easy to find
+examples if you're struggling with a library.
+
+### Work as a Local Editor
+
+We find it important to support the whole flow of development: from creation, to
+committing, to deployment. You should have your development environment
+everywhere, so you can work whenever you want. We make it possible to build a
+web application from start to finish, without leaving your browser.

packages/homepage/content/docs/1-overview.md

@@ -0,0 +1,60 @@
+---
+title: "Embedding"
+authors: ["CompuIves"]
+description: "It's possible to embed a sandbox on Medium and other websites."
+---
+
+## What is an Embed?
+
+CodeSandbox has a separate application for the embed. This application is specifically built to be as small as possible. If you replace `s` in the URL of a sandbox to `embed` you have the embed version of the sandbox. Example: https://codesandbox.io/**s**/new => https://codesandbox.io/**embed**/new. Notice that the embed doesn't have all features of the full editor.
+
+## Generate a URL
+
+You can generate a URL clicking 'Share' in the header and selecting the options you want to have enabled.
+
+![Share Button](./images/share-button.png)
+
+## Embed on Medium
+
+You can easily embed on Medium by taking your sandbox URL (like https://codesandbox.io/s/new) and pasting it in a Medium article. It should automatically become an embed after you press enter.
+
+## Embed Options
+
+The options shown in the embed modal are not all options available. We need a new UI for the share model to reflect these options, in the meantime you can find them here.
+
+| Option           | Description                                                                   | Values                               | Default                              |
+| ---------------- | ----------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------ |
+| `hidenavigation` | Hide the navigation bar of the preview.                                       | `0`/`1`                              | `0`                                  |
+| `moduleview`     | Evaluate the file that is open in the editor.                                 | `0`/`1`                              | `0`                                  |
+| `autoresize`     | Automatically resize the embed to the content (only works on Medium).         | `0`/`1`                              | `0`                                  |
+| `codemirror`     | Use CodeMirror editor instead of Monaco (decreases embed size significantly). | `0`/`1`                              | `0`                                  |
+| `eslint`         | Use eslint (increases embed size significantly).                              | `0`/`1`                              | `0`                                  |
+| `forcerefresh`   | Force a full refresh of frame after every edit.                               | `0`/`1`                              | `0`                                  |
+| `expanddevtools` | Start with the devtools (console) open.                                       | `0`/`1`                              | `0`                                  |
+| `runonclick`     | Only load the preview when the user says so.                                  | `0`/`1`                              | `0`                                  |
+| `view`           | Which view to open by default                                                 | `editor`/`split`/`preview`           | `split`, `preview` for small screens |
+| `module`         | Which module to open by default                                               | path to module (starting with `/`)   | entry path                           |
+| `initialpath`    | Which url to initially load in address bar                                    | string                               | `/`                                  |
+| `fontsize`       | Font size of editor                                                           | number (in px)                       | `14`                                 |
+| `highlights`     | Which lines to highlight (only works in CodeMirror)                           | comma separated list of line numbers |                                      |
+| `editorsize`     | Size in percentage of editor.                                                 | number                               | `50`                                 |
+
+## Example Embeds
+
+These are some examples of embeds, based on their properties.
+
+### Smallest Embed
+
+This embed is focused on being as light as possible:
+
+`https://codesandbox.io/embed/new?codemirror=1`
+
+<iframe src="https://codesandbox.io/embed/new?codemirror=1" style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"></iframe>
+
+### Code Example Embed
+
+You can also use CodeSandbox to show code examples, with highlighted lines. We recommend using CodeMirror for now for that:
+
+`https://codesandbox.io/embed/new?codemirror=1&highlights=11,12,13,14`
+
+<iframe src="https://codesandbox.io/embed/new?codemirror=1&highlights=11,12,13,14" style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"></iframe>