From 5a7f6960bb1da17da3d3eabf5a5f8f6328aacd98 Mon Sep 17 00:00:00 2001
From: Lorna Mitchell <lorna.mitchell@redocly.com>
Date: Fri, 18 Aug 2023 16:25:25 +0100
Subject: [PATCH] docs: Give Redoc a landing page with overview and tldr
 instructions

---
 docs/index.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 docs/index.md

diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..e4a45cf1
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,96 @@
+---
+title: Redoc
+---
+
+# Redoc: Open source API documentation tool
+
+Redoc is a clean and easy way to produce web-ready documentation from an OpenAPI description (Swagger is also still supported). With one command, create your documentation, and customise it to meet the needs of your users.
+
+Redoc is based around a three panel layout, with clear sections for navigation, detailed documentation, and request/response examples.
+
+## Headline features
+
+* Modern layout with extensive customization options.
+* Support for OpenAPI 3.1, 3.0 and older 2.0 and Swagger formats.
+* Embed or build standalone HTML documentation.
+* CLI tool for easy automation and local development.
+
+## Demo
+
+[Try the live demo](https://redocly.github.io/redoc/) and upload your own API specification there to try.
+
+## Usage
+
+Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component.
+
+### Generate documentation from the CLI
+
+If you have Node installed, quickly generate documentation using `npx`:
+
+```
+npx @redocly/cli build-docs openapi.yaml 
+```
+
+The tool outputs by default to a file named `redoc-static.html` that you can open in your browser.
+
+> [Redocly CLI](https://github.com/Redocly/redocly-cli/) does more than docs, check it out and add linting, bundling and more to your API workflow.
+
+### Add an HTML element to the page
+
+Create an HTML page, or edit an existing one, and add the following:
+
+```html
+    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
+```
+
+Open the HTML file in your browser, and your API documentation is shown on the page.
+
+Add your own `spec-url` to the `<redoc>` tag, this attribute can also be a local file. The JavaScript library can also be installed locally using `npm` and served from your own server, see the [HTML deployment documentation](https://redocly.com/docs/redoc/deployment/html/) for more details.
+
+### More usage options
+
+Check out the [deployment documentation](./deploment/index/md) for more options, and detailed documentation for each.
+
+## Configure Redoc
+
+Redoc is highly configurable. Each deployment option accepts configuration in a way that's appropriate to that platform, but the options are the same for each. For example:
+
+* Using [Redocly CLI](../cli/index.md), configuration goes in the `redocly.yaml` file, or can be supplied as command line parameters, such as `--theme.openapi.disableSearch`.
+* Using HTML or React or react, configure by setting `option` in the tag.
+
+Here's a sample `redocly.yaml` configuration file, showing a few common settings and tweaking some of the visual theme settings:
+
+```yaml
+theme:
+  openapi:
+    disableSearch: true
+    expandResponses: 200,202
+    jsonSampleExpandLevel: 1
+
+    theme:
+      sidebar:
+        backgroundColor: '#eae0cc'
+        textColor: '#3d005b'
+      colors:
+        primary:
+          main: '#660099'
+      typography:
+        fontSize: 14pt
+        headings:
+          fontWeight: bold
+```
+
+Redocly CLI detects a file named `redocly.yaml` in the same directory as you run the command and uses it. See the documentation with a command like this:
+
+```
+redocly preview-docs openapi.yaml
+```
+
+There are many, many more options available. Visit the [configuration reference](./config.md) for a complete list.
+
+## Next steps
+
+* If you are new to OpenAPI, try the [OpenAPI starter project](../../cli/openapi-starter/) for a great introduction.
+* Ready to build documentation from an existing OpenAPI file? The [Redoc quickstart](./quickstart.md).
+* Learn more about the project by visiting [Redoc on GitHub](https://github.com/Redocly/redoc).