Update best-practices.md

* Create fair-billing-policy.md

* Update fair-billing-policy.md

* Update fair-billing-policy.md

articles/billing/fair-billing-policy.md

@@ -0,0 +1,11 @@
+# Fair Billing Policy 
+
+Stoplight's Fair Billing Policy means you will only be charged for active users in any given billing cycle. We adopted the Fair Billing Policy because we believe you should only pay for what you use. We also wanted to avoid setting strict user limits because it can lead to workflow bottlenecks and promotes poor engineering practices. 
+
+## Active User 
+To be considered an active user, you must perform one of the following actions: 
+- Push a commit 
+- Write or modify a file 
+- Publish documentation 
+
+> If you do not perform on of these actions durign a billing cycle, you will be considered inactive, and will not count towards your user count for that billing cycle. 

articles/desktop/overview.md

@@ -1,7 +1,7 @@
 # Web & Desktop App
 
 
-Stoplight has a desktop app! Download the appropriate version [here](https://stoplight.io/download) .
+Stoplight has a desktop app! Download the appropriate version [here](https://github.com/stoplightio/desktop/releases/latest).
 
 
 ## Web or Local?

articles/editor/file-validation.md

@@ -22,4 +22,4 @@ Different types of file validations are used throughout the Stoplight platform.
 
 **Related Articles**
 
-* [Validating Your API Spec](/modeling/modeling-with-openapi/validating-your-api-sec)
+* [Validating Your API Spec](/modeling/modeling-with-openapi/validating-your-api-spec)

articles/getting-started/new-user-introduction.md

@@ -1,6 +1,6 @@
 # Welcome to Stoplight Next! 
 
-Now that you have the basics on what the [Stoplight Next Platform](/platform/introduction) is, we can go over how to get started. 
+Now that you have the basics on what the [Stoplight Next Platform](/platform/what-is-stoplight) is, we can go over how to get started. 
 
 First things first, are you using Stoplight for Personal Projects or as part of an Organization?
 

articles/hubs/best-practices.md

@@ -0,0 +1,44 @@
+# Hub’s Best Practices 
+
+## Supplementary/Auxiliary Documentation 
+Documentation is a principal driving force for great UX. APIs require basic referential material for consumption, but great UX comes from all of the supplementary information you provide your users.  To support the creation of any number of different supplementary documents, images, videos, etc. we created Hubs, our documentation tool. We pushed the limits of API documentation beyond specifications and models to accommodate all of the secondary and tertiary information that can help drive good UX. 
+
+## Referencing Other Files/ Git Repo for Open Sourcing Docs  
+Open sourcing your documentation can provide a number of advantages including more engagement and content. Users and businesses often create their own supplemental documents supporting their own unique use cases. By providing a Github repo, these users and companies can contribute their unique documentation to your docs enhancing your UX. Stoplight’s Hubs has a ref builder that allows you to directly reference any markdown and YAML files. Create and store your markdown files in a Github Repo or other file sharing platform and directly reference them in Hubs. This workflow also gives the added benefit of changes made to any markdown files being automatically reflected in your documentation.  
+
+## Structure 
+
+### Table of Contents 
+One of Stoplight’s central principles is ‘a single source of truth.’ We applied this principle to Hubs by adding in a ‘Table of Contents.’ The Table of Contents is a bird’s eye view of the structure of your docs that allows you to strategize and manipulate the structure of your docs. 
+
+### Pages
+Pages function similarly to chapters in a book. They group similar content together at the broadest scope. We recommend adding pages sparingly to keep your documentation concise and easily navigable. Connect pages via headers in Hub Settings.  
+
+### Subpages  
+If pages are the chapters of a book, subpages are sections within chapters. Create a subpage for each topic you wish to address. The scope should be as narrow as possible to help your users more easily navigate your documentation. New subpages auto-populate the sidebar navigation of a page. Drag and drop in the navigation for structural adjustments and create empty subpages to create navigational headers to further clarify structure. 
+
+## Integrations 
+Integrations are quickly becoming core elements of any platform. Stoplight’s Hubs provides easy integrations to satisfy the most popular builds. Add a Google Analytics integration to track your documentation consumers activity. Integrate Intercom into your documentation to provide additional support. Add a Segment integration for any other integrations supported by Segment.  
+
+## SEO 
+SEO is important in any content including documentation. Use a Google Analytics integration to optimize your documentation for Google.  
+
+## Routing 
+Routing ties into SEO but is also an important aspect of a well structured and organized document. Create easily readable routes that identify your content accurately to maximize the SEO of your documentation. Use the ‘Table of Contents’ to view the connections between pages and subpages to make clever use of routes. Add Page tags for additional clarification on what kind of content is housed within. 
+
+## Design
+Documentation design is not just a pretty package for your content. It impacts a number of different aspects of your business including marketing, branding, and UX. Use theming for marketing and branding purposes to make simple global style adjustments. Most businesses have 2-3 primary colors that can be applied to your docs through theming. For more advanced design, use Custom CSS to have complete control of the style of your documentation. 
+
+---
+**Related Links**
+- [Documentation with Hubs](/documentation/introduction)
+- [Routing](/documentation/getting-started/routing)
+- [Headers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+- [Blocks](/documentation/blocks)
+- [Referencing Other Data Sources](/documentation/referencing-other-data-sources)
+- [Publishing](/documentation/publishing)
+- [Theming](/documentation/design/theming)
+- [Custom CSS](/documentation/design/custom-css)
+

articles/hubs/blocks.md

@@ -1,6 +1,6 @@
 # Blocks 
 
-![Blocks](https://github.com/stoplightio/docs/blob/develop/assets/gifs/blocks.gif?raw=true)
+![Blocks](https://github.com/stoplightio/docs/blob/develop/assets/gifs/Blocks.gif?raw=true)
 
 ## What
 Blocks are the micro-level building blocks of Hubs. They house multiple forms of content and allow for simple restructuring and modification. 
@@ -22,12 +22,6 @@ Blocks are the micro-level building blocks of Hubs. They house multiple forms of
 * An upper level block for organizing text within tabs 
 ### Callout 
 * A text block with color for emphasis 
-### Hero 
-* A large stylized text block with additional functionality typically found on landing pages 
-### Bar List 
-* A navigational block composed of bars with buttons 
-### Card List 
-* A navigational block composed of cards with text, buttons, and optional images
 ### HTML 
 * Include arbitrary HTML in your hubs when the other base block types don't quite do the trick
 
@@ -35,7 +29,7 @@ Blocks are the micro-level building blocks of Hubs. They house multiple forms of
 **Related Articles**
 - [Documentation with Hubs](/documentation/introduction)
 - [Routing](/documentation/getting-started/routing)
-- [Headers & Footers](/documentation/getting-started/header-footer)
+- [Headers](/documentation/getting-started/header-footer)
 - [Pages](/documentation/getting-started/pages)
 - [Subpages](/documentation/getting-started/subpages)
 - [Referencing Other Data Sources](/documentation/referencing-other-data-sources)

articles/hubs/oauth.md

@@ -0,0 +1,56 @@
+# OAuth for Hubs 
+
+## What 
+
+OAuth provides a level of security to your documentation to restrict access to it. Enabling OAuth in Hubs can be accomplished through two different methods: via Modeling or directly into the Hubs code.
+
+> Stoplight supports OAuth 1.0 and 2.0 
+
+## How 
+
+### Modeling 
+
+![OAuth in Modeling](https://github.com/stoplightio/docs/blob/develop/assets/images/hubs-oauth-modeling.png?raw=true)
+
+1. Create a new Modeling file or select an existing one referenced by the Hub you wish to modify 
+
+> If you are creating a new Modeling file, make sure to reference it in your Hub 
+
+2. Next to **Security** in the left-middle toolbar, Add a Security Scheme by clicking the **+**
+3. Input a **key**
+4. Select oauth2 under **type** 
+5. Select **accessCode** under OAuth **flow** 
+6. Select an **authorization url**
+7. Select a **token url** 
+8. **Add Scope** (optional) 
+9. Add a **Security scheme description** (optional)
+
+### Hubs 
+
+![OAuth in Hubs](https://github.com/stoplightio/docs/blob/develop/assets/images/hubs-oauth-code.png?raw=true)
+
+1. Select the Hub you wish to modify 
+2. Select **Code View**
+3. Add the following lines of code to your Hub:
+
+```
+
+"config": {
+  "http": {
+    "oauth2": {
+      "credentials": {
+        "authorize_url": "insert authorize url here",
+        "access_token_url": "insert access token url here",
+      }
+    }
+  }
+}
+
+```
+
+---
+**Related Articles**
+
+- [Digital Oceans: Introduction to OAuth2](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2)
+- [Security Schemes](/modeling/modeling-with-openapi/security-schemes)
+

articles/modeling/json-introduction.md

@@ -43,7 +43,7 @@ There are many benefits to using JSON, some of which include:
   be written in YAML, so either format can be used to write OpenAPI specifications
 
 * It can be used to link files together through [JSON
-  references](/modeling/introduction/modeling-with-openapi/referencing-another-api-spec), making it easy to break up large documents
+  references](/modeling/modeling-with-openapi/referencing-another-api-spec), making it easy to break up large documents
   into smaller, more focused documents
 
 Whether you are modeling an API, creating a Prism Collection, or writing

articles/modeling/modeling-introduction.md

@@ -30,4 +30,4 @@ There are a few ways to get started designing your API with the Stoplight design
 - Create an API from scratch [Using the CRUD Builder](/modeling/modeling-with-openapi/using-the-crud-builder)
 - [Reference another API Spec](/modeling/modeling-with-openapi/referencing-another-api-spec)
 - [Send HTTP Requests](/modeling/modeling-with-openapi/sending-http-requests) to an existing API Spec 
-- [Validate your API Spec](/modeling/modeling-with-openapi/validating-your-api-sec)
+- [Validate your API Spec](/modeling/modeling-with-openapi/validating-your-api-spec)

articles/modeling/sending-http-requests.md

@@ -31,4 +31,5 @@ Use the HTTP Request Maker to send requests to the endpoints defined in your spe
 
 ---
 **Related Articles**
-[Using Environment Variables](/testing/using-variables/environment)
+
+- [Using Environment Variables](/testing/using-variables/environment)

articles/playbooks/technical-writers.md

@@ -0,0 +1,43 @@
+# Technical Writer Playbook 
+
+Documenting an API is crucial to its success but can be extremely time consuming. Here at Stoplight, we believe documentation should be beautiful, clean, and robust while maintaining a streamlined turnaround time. We’ve created a holistic documentation tool, Hubs, to address some of the problems our users were facing including:
+ 
+- Documenting Endpoints 
+- Testing Endpoints 
+- Creating Non-Reference Documentation 
+- Managing Content
+- External and Internal Referencing 
+- Design and Style 
+
+
+## Documenting Endpoints 
+The most key component to API Documentation are its endpoints. To that end, we created a reference builder that allows you to [“power pages”](/documentation/referencing-other-data-sources) with your specification as you see fit. When you power a page or subpage with your specification, the endpoints are automatically documented and styled for legibility and aesthetic design. 
+
+## Testing Endpoints 
+Testing endpoints is a valuable tool for anyone who wants to consume your API. Users want to know that your API functions properly before they commit to using it. To address this problem, we created [“Try it Out,” an HTTP Request Maker](/modeling/modeling-with-openapi/sending-http-requests). Try it Out allows you to send HTTP Requests to your API to test out its endpoints under any number of different conditions. You can customize Try it Out with security schemes, variables, headers, queries, and it even generates code in various programming languages. 
+
+## Creating Non-Reference Documentation 
+Great documentation is more than just API endpoints. Guides, tutorials, and other supplemental information enhance your users experience by providing them with all the information they need to access your API and your product. We broadened Hubs scope to accomodate all product documentation needs. You can easily build out your content within [Blocks](/documentation/blocks), a number of flexible content structures that can house a number of different forms of content including markdown, images, code snippets, and much more. 
+
+## Managing Content 
+Organizing a complex APIs endpoints and supplemental information can be a challenging task. Some specification can have hundreds of endpoints with supplemental information throughout. To assist with organizing content, we created an overview of all your pages, subpages, and their connections called “Table of Contents”. With a bird’s eye view of your content, you can easily organize and manage your content through drag drop functionality. 
+
+## External and Internal Referencing 
+To accomodate a larger variety of writing workflows, we expanded the capabilities of [Powering a Page](/documentation/referencing-other-data-sources) to allow for more files internally and externally to be referenced. You can now easily reference internal or external specifications, and Markdown, YAML, JSON, and Scenario files. 
+
+## Design and Style 
+We wanted to create a new, beautiful, minimalistic, efficient design for less design-oriented individuals while allowing for customization. Hubs was designed to display your documentation in a neat, efficient structure, designed specifically for displaying the real beauty, your API. On the other hand, we didn’t want to stifle the creativity that goes into documentation design so we added in [theming](/documentation/design/theming) and [custom CSS](/documentation/design/custom-css). We also made it easier to add navigation, different kinds of content, and a more robust search. 
+
+---
+Related Links 
+- [Documentation with Hubs](/documentation/introduction)
+- [Routing](/documentation/getting-started/routing)
+- [Headers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+- [Blocks](/documentation/blocks)
+- [Referencing Other Data Sources](/documentation/referencing-other-data-sources)
+- [Publishing](/documentation/publishing)
+- [Theming](/documentation/design/theming)
+- [Custom CSS](/documentation/design/custom-css)
+

articles/prism/introduction.md

@@ -47,8 +47,7 @@ The [Prism Helpers](https://next.stoplight.io/stoplight/prism) project is a coll
 
 **Related Articles**
 
-* [Javascript Runtime Refrence](/runtime.md)
-* [Passing Data Between Steps](/testing/getting-started/passing-data-between-steps)
+* [Javascript Runtime](/mocking/javascript-runtime)
 * [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
 * [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
 * [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
@@ -56,6 +55,5 @@ The [Prism Helpers](https://next.stoplight.io/stoplight/prism) project is a coll
 * [$$.env (Environment)](/testing/using-variables/environment)
 * [$.ctx(Context)](/testing/using-variables/context)
 * [Sending HTTP Requests](/testing/sending-http-requests/overview)
-* [Referencing other Scenarios](/testing/referencing-other-scenarios/overview)
 * [Contract Testing](/testing/leveraging-openapi/contract-testing)
 * [Integrating in Continuous Integration](/testing/continuous-integration/overview)

articles/prism/runtime.md

@@ -120,10 +120,11 @@ var data = SL.schema.generate(contract);
 
 #### Find Operation
 
+The code snippet below describes the Stoplight representation of an HTTP operation. It is loosely based on OAS 3. You can find more descriptions of some of the properties described below [here](https://swagger.io/specification/#operationObject).
+
 ```js
 /**
 *
-* This describes the Stoplight representation of an HTTP operation. It is loosely based on OAS 3. You can find more descriptions of some of the properties described below here: https://swagger.io/specification/#operationObject.
 *
 * @typedef {Object} Operation
 * @property {string} method

articles/projects/git.md

@@ -0,0 +1,61 @@
+# Git Repositories
+ 
+## What 
+The Stoplight Platform is built on top of Git. This means that all your projects are Git repositories and that our platform benefits from all the additonal functionality provided by Git. To access the Git funtionality, you will need to clone your Git repository by generating an Access Token.  
+
+> You can also use Access Tokens to access the Stoplight API, authenticate Prism in a continuous integration enviornment, and access the underlying Git repositories for projects. You can make this part of your Git workflow, add it to scripts, or your CI/CD process
+
+## Who 
+
+If you have write access to a project, you will be able to:
+* Pull projects via Git
+* Commit to projects via Git
+* Push changes to projects via Git
+
+If you have read access to a project, you will be able to:
+* Pull your project via Git
+
+## How to Clone Your Stoplight Git Repository 
+  
+1. Select the **Settings** tab on the platform homepage
+2. Select **Access Tokens** from the left  
+
+![Access Tokens](https://github.com/stoplightio/docs/blob/develop/assets/images/access-tokens.png?raw=true)
+
+3. Create a token to access projects that your Stoplight account has proper permissions for (These permissions match the ones in the Stoplight UI) 
+
+> You can name your token whatever you want. Once you have created the token, copy it, and only store it in a safe location. Once you close the window, you will not see it again
+
+3. On your machine, store your access token as an environmental variable (recommended)
+
+For example, on Mac/Linux:
+
+```
+export STOPLIGHT_TOKEN="1234567890"
+```
+
+4. You can then `git clone` the repo, replace `{stoplight-username}`, `{username}`, and `{project-name}` with the appropriate information: 
+
+```
+git clone https://{stoplight-username}:$STOPLIGHT_TOKEN@git.stoplight.io/{username}/{project-name}.git
+```
+
+For example: 
+
+```
+git clone https://taylor:$STOPLIGHT_TOKEN@git.stoplight.io/taylor/test-new.git
+```
+
+> If the project is associated with an organization and not a personal project, replace `username` with `organization-name` 
+
+5. Now you can make changes to your files, commit, and push to your master branch. You can see these changes in the Stoplight UI as well as the "History of Changes" 
+
+> Remember: You will only see changes on the master branch in the UI at this time. 
+
+    
+---
+**Related Articles**
+- [Change a Project Member's Role](/platform/projects/change-a-members-role)
+- [Make Your Project Private/Public](/platform/projects/visibility)
+- [Invite People to Organization](/platform/organizations/invite-people)
+- [Add People to a Team](/platform/organizations/teams/add-people)

articles/projects/visibility.md

@@ -1,4 +1,4 @@
-## Making Your Project Private & Public
+# Making Your Project Private & Public
 
 ![Project Visibility](https://github.com/stoplightio/docs/blob/develop/assets/images/project-make-public.png?raw=true)
 

articles/teams/delete-team.md

@@ -19,4 +19,4 @@
 **Related Articles**
 - [Delete an Organization](/platform/organizations/delete-org)
 - [Transfer Ownership of a Team](/platform/organizations/teams/transfer-ownership)
-- [Delete a Team](/platform/organizations/teams/delete)
+

articles/testing/contract-testing.md

@@ -86,7 +86,6 @@ Any validation errors will automatically be added to the test results.
 ---
 **Related Articles**
 - [Testing Introduction](/testing/introduction)
-- [Passing Data Between Steps](/testing/getting-started/passing-data-between-steps)
 - [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
 - [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
 - [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
@@ -94,4 +93,4 @@ Any validation errors will automatically be added to the test results.
 - [$$.env (Environment)](/testing/using-variables/environment)
 - [$.ctx(Context)](/testing/using-variables/context)
 - [Sending HTTP Requests](/testing/sending-http-requests/overview)
-- [Referencing other Scenarios](/testing/referencing-other-scenarios/overview)
+

articles/testing/overview.md

@@ -24,11 +24,10 @@ API tests provide insight into how your API behaves under certain scenarios and
 
 Microservices and serverless architecture have made it easier than ever to iterate quickly. The downside of rapid development is an increase in bugs and technical debt, making projects harder to manage without a proper testing solution. It is critical to have a comprehensive test suite to allow teams to test the API during development. 
 
->Stoplight makes it easy to create a full suite of tests by providing [Environment](/testing/using-variables/environment) and [Context variables](/testing/using-variables/context), and the ability to [reference other scenarios](/testing/referencing-other-scenarios/overview) to accelerate test generation and reduce duplication. 
+>Stoplight makes it easy to create a full suite of tests by providing [Environment](/testing/using-variables/environment) and [Context variables](/testing/using-variables/context), and the ability to reference other scenarios to accelerate test generation and reduce duplication. 
 
 ---
 **Related Articles**
-- [Passing Data Between Steps](/testing/getting-started/passing-data-between-steps)
 - [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
 - [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
 - [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
@@ -36,8 +35,7 @@ Microservices and serverless architecture have made it easier than ever to itera
 - [$$.env (Environment)](/testing/using-variables/environment)
 - [$.ctx(Context)](/testing/using-variables/context)
 - [Sending HTTP Requests](/testing/sending-http-requests/overview)
-- [Referencing other Scenarios](/testing/referencing-other-scenarios/overview)
-- [Contract Testing](testing/leveraging-openapi/contract-testing)
+- [Contract Testing](/testing/leveraging-openapi/contract-testing)
 - [Integrating in Continuous Integration](/testing/continuous-integration/overview)
 - [Integrating with Jenkins](/testing/continuous-integration/jenkins)
 - [Integrating with Travis](/testing/continuous-integration/travis)

articles/testing/run-test-stoplight.md

@@ -7,7 +7,7 @@ way is through the Stoplight editor.
 
 
 > If you haven't created your first scenario yet, please [do so before
-> continuing](testing/introduction)
+> continuing](/testing/introduction)
 
 Scenarios in Stoplight are composed of three different levels:
 

articles/testing/run-test-terminal.md

@@ -63,11 +63,11 @@ You can also run a contract test against a specific upstream URL with the
 prism validate --spec /path/to/my/spec.json --upstream http://localhost:8080
 ```
 
-For more information on contract testing and how it can be used, see [here](testing/leveraging-openapi/contract-testing).
+For more information on contract testing and how it can be used, see [here](/testing/leveraging-openapi/contract-testing).
 
 ---
 **Related Articles**
 
 - [Testing Introduction](/testing/introduction)
-- [Contract Testing](testing/leveraging-openapi/contract-testing)
+- [Contract Testing](/testing/leveraging-openapi/contract-testing)
 - [Integrating in Continuous Integration](/testing/continuous-integration/overview)

articles/testing/send-http-requests.md

@@ -110,7 +110,6 @@ platforms.
   ---
   **Related Articles**
 - [Testing Introduction](/testing/introduction)
-- [Passing Data Between Steps](/testing/getting-started/passing-data-between-steps)
 - [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
 - [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
 - [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)