Merge 1d7105e into 74ebba6

.github/CONTRIBUTING.md

@@ -6,6 +6,7 @@ Hi! We're really excited that you are interested in contributing to ReDoc. Befor
 - [Pull Request Guidelines](#pull-request-guidelines)
 - [Development Setup](#development-setup)
 - [Project Structure](#project-structure)
+- [Style Guide](#style-guide)
 
 ## Issue Reporting Guidelines
 - Before filing a new issue, try to make sure your problem doesn’t already exist.
@@ -94,3 +95,7 @@ There are some other scripts available in the `scripts` section of the `package.
   - **`src/utils`**: utility functions
   - **`src/styled-components.ts`**: - reexports styled-components with proper typescript annotations using theme
   - **`src/theme.ts`**: - default theme (colors, fonts, etc) used by all the components
+
+  ## Style Guide
+
+  Please find our style-guide [here](style-guide).

.github/style-guide

@@ -0,0 +1,172 @@
+# Documentation style guide
+
+This style guide applies to all documentation created for Redocly products.
+
+For information about how to write technical documentation, we suggest reviewing the content of the [Google Technical Writing courses](https://developers.google.com/tech-writing).
+
+The [Divio documentation system](https://documentation.divio.com/) site is also a good resource.
+
+## Contributing
+
+The *Documentation style guide* is a living document. Add to it whenever a style decision is made or a question is answered regarding style, grammar, or word choice.
+
+## Published guides
+
+For all items not covered in this guide, refer to the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/).
+
+## Inclusive language
+
+This section provides guidelines on how to avoid using charged language in documentation.
+
+### Allowing and blocking
+
+Don't use "whitelist" or "blacklist" when referring to allowing or blocking content or traffic.
+
+* When used as a noun, use "allowlist" or "blocklist".
+* When used as a verb, use "allow" or "block"
+
+Example: _To **allow** outgoing traffic, add the IP to the **allowlist**._
+
+### Leader and follower
+
+Don't use "master" or "slave" to describe relationships between nodes or processes.
+
+* Use "leader", "main" or "primary," instead of "master."
+* Use "follower" or "secondary," instead of "slave."
+
+#### Exceptions
+
+When referring to a configuration or settings used by third-party libraries or technologies outside the Redocly project, prefer the original name to avoid confusion.
+
+For example, use "master" when referring to the default Git branch.
+
+## Redocly-specific style
+
+The following sections provide general guidelines on topics specific to Redocly documentation. Note that for the most part, these are *guidelines*, not rigid rules. If you have questions, ask in the #docs channel of Redocly Slack.
+
+### General
+
+* Use active voice. Avoid passive voice.
+  - Passive: The heatmap visualization is displayed.
+  - Active: Redocly displays the heatmap visualization.
+* Write in the imperative second person. Examples: You can write an API. Click the panel. Close the window.
+* Write in present tense.
+  - Not: The rule will check content.
+  - Use: The checks content. Redocly checks the content.
+* Do not use an ampersand (&) as an abbreviation for "and."
+  - **Exceptions:** If an ampersand is used in the Redocly UI, then match the UI.
+* Avoid using internal slang and jargon in technical documentation.
+
+### File naming conventions
+
+- Files that are displayed in the help system should have names that are all lowercase, no spaces. Use hyphens instead of spaces. Example: glossary.md
+- Documentation file names should match the title. **Note:** This only applies to new files at this time. Do not change the names of older files unless directed to do so.
+- Internal reference file names should be all uppercase except the file extension. Example: CONTRIBUTING.md
+
+### Headings
+
+* Write headings in sentence case, not title case.
+  - This is sentence case
+  - This Is Title Case
+* Task topic headings start with a verb.
+  - Write a query. Create a dashboard.
+* Concept and reference topic headings should be nouns or gerunds. Examples: Contributing to docs, Visualizations, Style guide
+* Avoid following one heading with another heading.
+* Avoid skipping heading levels. For example, an h1 should be followed by an h2 rather than an h3.
+* Avoid having just one lower-level heading. For example, h1, h2, h2, h3, h3, h2 is a good order. Do no go h1, h2, h3, h2, h3, h2.
+* Don't include parenthetical words like (Important!) in headings.
+
+### Images
+
+* Preferred format is .png
+* File extension should be all lowercase.
+* Preferred DPI is 72.
+* Assume all graphics will be exclusively viewed on the web.
+* Maximum image size is 3840px X 2160px.
+* Screenshots should be readable, but not too large.
+
+### Capitalization
+
+* Redocly and Redoc are always capitalized unless part of a code block.
+* API names are always Title Case, followed by "API"—for example, "Reference Docs API"
+* Git is always capitalized, unless part of a code block.
+* Abbreviations are always capitalized (such as API, HTTP, ID, JSON, SQL, or URL) unless they are part of a code block.
+* Menu and submenu titles always use sentence case: capitalize the first word, and lowercase the rest.
+  - "Dashboards" when referring to the submenu title.
+  - "Keyboard shortcuts" when referring to the submenu topic.
+* Generic and plural versions are always lowercase.
+  - Lowercase "dashboard" when referring to a dashboard generally.
+  - Lowercase "dashboards" when referring to multiple dashboards.
+* **Exceptions:** If a term is lowercased in the Redocly UI, then match the UI.
+
+### Links and references
+
+When referencing another document, use "Refer to" rather than alternatives such as "See" or "Check out."
+
+Always give the reader some idea of what to expect in the reference. Avoid blind references, such as, "Refer to [this file](link)."
+
+When possible, use the exact title of the page or section you are linking to as the link text.
+
+**Example**
+Refer to the [Documentation style guide](documentation-style-guide.md) for information about word usage and capitalization guidelines.
+
+### Command line examples
+
+* Do not assume everyone is using Linux. Make sure instructions include enough information for Windows and Mac users to successfully complete procedures.
+
+* Do not add `$` before commands. Make it easy for users to copy and paste commands.
+
+  * **Wrong:** `$ sudo npm i redoc`
+  * **Right:** `sudo npm i redoc`
+
+* Include `sudo` before commands that require `sudo` to work.
+
+For terminal examples and Redocly configuration, use a `bash` code block:
+```bash
+npm i redoc
+```
+For HTTP request/response, use an `http` code block:
+```http
+GET  HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: 
+```
+
+### Word usage
+
+Redocly products have some words, abbreviations, and terms particular to the Redocly community.
+
+#### List specific terms here
+
+
+
+#### display (verb)
+
+*Display* is a transitive verb, which means it always needs a direct object.
+* Correct, active voice: Redocly displays your list of objects.
+* Correct, but passive voice: Your list of objects is displayed.
+* Incorrect: The list of objects displays.
+
+#### intro, introduction
+
+"Introduction" is the preferred word. Use "intro" if there are space constraints (like on the side menu) or you are specifically trying for a less formal, more conversational tone.
+
+#### metadata
+
+One word, not two.
+
+#### open source, open-source
+
+Do not hyphenate when used as an adjective unless the lack of hyphen would cause confusion. For example: _Open source software design is the most open open-source system I can imagine._
+
+Do not hyphenate when it is used as a noun. For example: _Open source is the best way to develop software._
+
+#### setup, set up
+
+Two words if used as a verb, one word if used as a noun.
+
+**Examples**
+
+* Set up the workspace.
+* Initial setup might take five minutes.

docs/FAQ

@@ -0,0 +1,44 @@
+# Redocly Frequently Asked Questions
+
+- [How do I enable the Console API?](#how-do-i-enable-the-console-api)
+- [Redoc Community Edition is not rendering my large json file smoothly.](#redoc-community-edition-is-not-rendering-my-large-json-file-smoothly)
+- [Does Redocly support webhooks with OpenAPI 3.1?](#does-redocly-support-webhooks-with-openapi-31)
+- [How do I adjust the theme settings on a page, such as color, line spacing, and fonts?](#how-do-i-adjust-the-theme-settings-on-a-page-such-as-color-line-spacing-and-fonts)
+- [Where can I locate Docker images for Redocly and redoc.cli?](#where-can-i-locate-docker-images-for-redocly-and-redoc-cli)
+- [Which tag should I use for operations that cannot be logically grouped?](#which-tag-should-i-use-for-operations-that-cannot-be-logically-grouped)
+- [Which vendor extensions does Redocly support?](#which-vendor-extensions-does-redocly-support)
+
+## How do I enable the Console API?
+
+Redocly API Reference Docs supports the Console API, though it is disabled by default. You can enable it in 'API Reference Settings'->'Live Configuration'. Redoc Community Edition does not support the Console API.
+
+## Redoc Community Edition is not rendering my large json file smoothly.
+
+Consider upgrading. Redocly API Reference Docs includes an option to section files.
+
+    referenceDocs:
+       layout:
+         scope: section
+
+If upgrading is not an option, simplifying your schema or reducing file size can both help to improve performance.
+
+## Does Redocly support webhooks with OpenAPI 3.1?
+
+Yes, Redocly supports OpenAPI 3.1 webhooks. See [\#1304](https://github.com/Redocly/redoc/pull/1304) for more information.
+
+## How do I adjust the theme settings on a page, such as color, line spacing, and fonts?
+
+Redoc.ly API Reference Docs supports themes, with a limited subset of theme features supported by Redoc Community Edition. Discover more information on configuring page themes [here](https://redoc.ly/docs/cli/configuration/reference-docs/#theming).
+
+## Where can I locate Docker images for Redocly and redoc cli?
+
+[Redoc Docker Image](https://hub.docker.com/r/redocly/redoc)  
+[redoc.cli Docker Image](https://hub.docker.com/r/broothie/redoc-cli). See [\#1158](https://github.com/Redocly/redoc/pull/1158) for more information.  
+
+## Which tag should I use for operations that cannot be logically grouped?
+
+When `x-tagGroups` is enabled, each tag must have a group or it will not be displayed. For operations that cannot be logically grouped, use the `other` group/tag. By default, Lint your API definition to ensure that each path has a tag using the [operation-tag-defined](https://redoc.ly/docs/cli/built-in-rules/#operation-tag-defined) built-in rule. Note that there is no built-in rule to check that tags aren't missing from the `x-tagGroups` groups definitions.
+
+## Which vendor extensions does Redocly support?
+
+You can view the list of supported vendor extensions [here](https://redoc.ly/docs/api-reference-docs/vendor-extensions/redoc-supported-extensions/).