[GSoD]Reorganizes the quickstart into a deployment guide and quicksta…

…rt (#1749) * Reorganizes the quickstart into a deployment guide and quickstart * Minor edits * fix: minor formatting issue * fix: simplify phrasing * Adds redirects, link to preview-docs docs, and other review edits * remove IE polyfills as IE is no longer supported Co-authored-by: Ivana Isadora Devcic <33730345+skadinna@users.noreply.github.com>
Redocly · Nov 23, 2021 · 6cbd96a · 6cbd96a
1 parent 262177d
commit 6cbd96a
Show file tree

Hide file tree

Showing 9 changed files with 183 additions and 143 deletions.
diff --git a/README.md b/README.md
@@ -183,6 +183,7 @@ IE support for Redoc.
 For more information on Redoc's commmand-line interface, refer to
 [**Using the Redoc CLI**](https://redoc.ly/docs/redoc/quickstart/cli/).
 
+
 ## Configuration
 
 ### Security Definition location

diff --git a/docs/quickstart/cli.md → docs/deployment/cli.md b/docs/quickstart/cli.md → docs/deployment/cli.md
@@ -1,5 +1,7 @@
 ---
 title: Using the Redoc CLI
+redirectFrom: 
+  - /docs/quickstart/cli/
 ---
 
 # Using the Redoc CLI

diff --git a/docs/quickstart/docker.md → docs/deployment/docker.md b/docs/quickstart/docker.md → docs/deployment/docker.md
@@ -1,5 +1,7 @@
 ---
 title: Using the Redoc Docker image
+redirectFrom:
+  - /docs/quickstart/docker/
 ---
 
 # Using the Redoc Docker image

diff --git a/docs/quickstart/html.md → docs/deployment/html.md b/docs/quickstart/html.md → docs/deployment/html.md
@@ -1,101 +1,11 @@
 ---
 title: Using the Redoc HTML element
+redirectFrom:
+  - /docs/quickstart/html/
 ---
 
 # Using the Redoc HTML element
 
-## TL;DR final code example
-
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>Redoc</title>
-    <!-- needed for adaptive design -->
-    <meta charset="utf-8"/>
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
-
-    <!--
-    Redoc doesn't change outer page styles
-    -->
-    <style>
-      body {
-        margin: 0;
-        padding: 0;
-      }
-    </style>
-  </head>
-  <body>
-    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
-    <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
-  </body>
-</html>
-
-```
-
-:::attention Running Redoc locally requires an HTTP server
-Loading local OpenAPI definitions is impossible without running a web server because of issues with
-[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) and
-other security reasons. 
-:::
-
-### Running Redoc locally
-
-If you want to view your Redoc output locally, you can simulate an HTTP server.
-
-#### Using Redocly OpenAPI CLI
-
-Redocly OpenAPI CLI is an open source command-line tool that includes a command
-for simulating an HTTP server to provide a preview of your OpenAPI definition locally.
-
-If you have [OpenAPI CLI](https://redoc.ly/docs/cli/#installation-and-usage) installed, `cd` into your
-project directory and run the following command:
-
-```bash
-openapi preview-docs openapi.yaml
-```
-
-By default, without providing a port, the preview starts on port 8080, and can be accessed at `http://localhost:8080`.
-To exit the preview, use `control+C`.
-
-#### Using Python
-
-If you have [Python 3](https://www.python.org/downloads/) installed, `cd` into your
-project directory and run the following command:
-
-```python
-python3 -m http.server
-```
-
-If you have [Python 2](https://www.python.org/downloads/) installed, `cd` into your
-project directory and run the following command:
-
-```python
-python -m SimpleHTTPServer 8000
-```
-
-The output after entering the command provides the local URL where the preview can be accessed.
-To exit the preview, use `control-C`.
-
-#### Using Node.js
-
-If you have [Node.js](https://nodejs.org/en/download/) installed, install `http-server`
-using the following npm command:
-
-```bash
-npm install -g http-server
-```
-
-Then, `cd` into your project directory and run the following command:
-
-```node
-http-server
-```
-
-The output after entering the command provides the local URL where the preview can be accessed.
-To exit the preview, use `control-C`.
-
 ## Step 1 - Install Redoc
 
 You can install Redoc using one of the following package managers:
@@ -113,7 +23,6 @@ For more information, see
 [Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file)
 in the npm documentation or [Yarn init](https://classic.yarnpkg.com/en/docs/cli/init/)
 in the yarn documentation.
-
 :::
 
 ### Install Redoc with yarn

diff --git a/docs/deployment/intro.md b/docs/deployment/intro.md
@@ -0,0 +1,115 @@
+---
+title: Redoc deployment guide
+redirectFrom:
+  - /docs/quickstart/intro/
+---
+
+# Redoc deployment guide
+
+Redoc offers multiple options for rendering your OpenAPI definition.
+You should select the option that best fits your needs.
+
+The following options are supported:
+
+- **[Live demo](https://redocly.github.io/redoc/):**
+  The live demo offers a fast way to see how your OpenAPI will render with Redoc.
+  A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your
+  definition and select **TRY IT**.
+- **[HTML element](./html.md):**
+  Using the HTML element works well for typical website deployments.
+- **[React component](./react.md):**
+  Using the React component is an option for users with a React-based application.
+- **[Docker image](./docker.md):**
+  Using the Docker image works in a container-based deployment.
+- **[CLI](./cli.md):**
+  Using the CLI is an option for users who prefer to use a command-line interface.
+
+## Before you start
+
+### OpenAPI definition
+
+You will need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions: 
+- OpenAPI 3.0
+    - [Rebilly Users OpenAPI Definition](https://github.com/raw/Rebilly/api-definitions/main/openapi/users.yaml)
+    - [Swagger Petstore Sample OpenAPI Definition](https://petstore3.swagger.io/api/v3/openapi.json)
+- OpenAPI 2.0
+    - [Thingful OpenAPI Definition](https://github.com/raw/thingful/openapi-spec/master/spec/swagger.yaml)
+    - [Fitbit Plus OpenAPI Definition](https://github.com/raw/TwineHealth/TwineDeveloperDocs/master/spec/swagger.yaml)
+
+::: OpenAPI Specification info
+For more information on the OpenAPI specification, refer to the [Learning OpenAPI 3](https://redoc.ly/docs/resources/learning-openapi/)
+section in the documentation.
+:::
+
+### Running Redoc locally
+
+If you want to view your Redoc output locally, you can simulate an HTTP server.
+
+#### Using Redocly OpenAPI CLI
+
+Redocly OpenAPI CLI is an open source command-line tool that includes a command
+for simulating an HTTP server to provide a preview of your OpenAPI definition locally.
+
+If you have [OpenAPI CLI](https://redoc.ly/docs/cli/#installation-and-usage) installed, `cd` into your
+project directory and run the following command:
+
+```bash
+openapi preview-docs openapi.yaml
+```
+
+::: openapi.yaml
+Replace `openapi.yaml` in the example command with the file path to your OpenAPI definition. 
+:::
+
+By default, without providing a port, the preview starts on port 8080, and can be accessed at `http://localhost:8080`.
+To exit the preview, use `control+C`.
+
+You can alter the port if you are using 8080 already, for example:
+
+```bash
+openapi preview-docs -p 8888 openapi.yaml
+```
+
+::: openapi.yaml
+Replace `openapi.yaml` in the example command with the file path to your OpenAPI definition. 
+:::
+
+For more information about the `preview-docs` command, refer to
+[OpenAPI CLI commands](https://redoc.ly/docs/cli/commands/preview-docs/#preview-docs) in the OpenAPI CLI documentation.
+
+#### Using Python
+
+If you have [Python 3](https://www.python.org/downloads/) installed, `cd` into your
+project directory and run the following command:
+
+```python
+python3 -m http.server
+```
+
+If you have [Python 2](https://www.python.org/downloads/) installed, `cd` into your
+project directory and run the following command:
+
+```python
+python -m SimpleHTTPServer 8000
+```
+
+The output after entering the command provides the local URL where the preview can be accessed.
+To exit the preview, use `control-C`.
+
+#### Using Node.js
+
+If you have [Node.js](https://nodejs.org/en/download/) installed, install `http-server`
+using the following npm command:
+
+```bash
+npm install -g http-server
+```
+
+Then, `cd` into your project directory and run the following command:
+
+```node
+http-server
+```
+
+The output after entering the command provides the local URL where the preview can be accessed.
+To exit the preview, use `control-C`.
diff --git a/docs/quickstart/react.md → docs/deployment/react.md b/docs/quickstart/react.md → docs/deployment/react.md
@@ -1,5 +1,7 @@
 ---
 title: Using the Redoc React component
+redirectFrom:
+  - /docs/quickstart/react/
 ---
 
 # Using the Redoc React component

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,51 @@
+---
+title: Redoc quickstart guide
+---
+
+# Redoc quickstart guide
+
+To render your OpenAPI definition using Redoc, use the following HTML code sample and
+replace the `spec-url` attribute with the URL or local file address to your definition.
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redoc</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+
+    <!--
+    Redoc doesn't change outer page styles
+    -->
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+  </head>
+  <body>
+      <!--
+    Redoc element with link to your OpenAPI definition
+    -->
+    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
+    <!--
+    Link to Redoc JavaScript on CDN for rendering standalone element
+    -->
+    <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> </script>
+  </body>
+</html>
+
+```
+
+:::attention Running Redoc locally requires an HTTP server
+Loading local OpenAPI definitions is impossible without running a web server because of issues with
+[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) and
+other security reasons. Refer to [Running Redoc locally](https://redoc.ly/docs/deployment/intro/#running_redoc_locally) for
+more information.
+:::
+
+For a more detailed explanation with step-by-step instructions and additional options for using Redoc, refer to the [Redoc deployment guide](/deployment/intro).
diff --git a/docs/quickstart/intro.md b/docs/quickstart/intro.md
diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml
@@ -1,13 +1,15 @@
 redoc:
-  - group: Quickstart
+  - label: Quickstart
+  - page: redoc/quickstart.md
+  - group: Deployment
     expanded: false
-    page: redoc/quickstart/intro.md
+    page: redoc/deployment/intro.md
     pages:
       - label: HTML element
-        page: redoc/quickstart/html.md
+        page: redoc/deployment/html.md
       - label: React component
-        page: redoc/quickstart/react.md
+        page: redoc/deployment/react.md
       - label: Docker image
-        page: redoc/quickstart/docker.md
+        page: redoc/deployment/docker.md
       - label: Command-line interface
-        page: redoc/quickstart/cli.md
+        page: redoc/deployment/cli.md