fix link

* update gifs and image for project docs

* update editor gif

* add updated editor images

articles/editor/editor-configuration.md

@@ -6,7 +6,7 @@ It is placed in the root of your project and allows you to configure editor sett
 
 You can make changes to the `.stoplight.yml` file by opening it:
 
-![](../../assets/images/editor-configuration.png)
+![Editor Configuration Location](https://github.com/stoplightio/docs/blob/develop/assets/images/editor-configuration.png?raw=true)
 
 ### Editor Configuration
 
@@ -14,9 +14,9 @@ You can make changes to the `.stoplight.yml` file by opening it:
 
 ### Environments
 
-![](../../assets/images/editor-configuration2.png)
+![Environments](https://github.com/stoplightio/docs/blob/develop/assets/images/editor-configuration2.png?raw=true)
 
-Environments make it easy to auto-populate variables (hostnames, ports, passwords, etc.) used by specifications and scenarios. Read more about them [here](../testing/variables-environment.md).
+Environments make it easy to auto-populate variables (hostnames, ports, passwords, etc.) used by specifications and scenarios. Read more about them [here](/testing/using-variables/environment).
 
 The environments and variables defined in the `.stoplight.yml` are shared amongst all users, which makes this a good place to define common or shared variables, such as the url host for a particular API + environment. 
 
@@ -30,6 +30,6 @@ These environments can be customized by editing the `environments` key of the `.
 
 ***
 
-**Related**
+**Related Articles**
 
-* [Testing Environment Variables](../testing/variables-environment.md)
+* [Testing Environment Variables](/testing/using-variables/environment)

articles/editor/environments.md

@@ -4,7 +4,7 @@
 
 An environment is simply a container for data, represented as a list of key-value pairs (behind the scenes, this is a JSON object). Every Stoplight project has one or more environments associated with it. The data stored in an environment can be used in many places within the Stoplight editor.
 
-Environments, and their default data, are defined in the [Stoplight configuration file](./editor-configuration.md#environments).
+Environments, and their default data, are defined in the [Stoplight configuration file](/platform/editor-basics/editor-configuration).
 
 - __Do__ create an environment for each development environment associated with the project. For example, `development`, `staging`, and `production`.
 - __Don't__ create environments for individual users. Instead, use private variables (below) to customize existing environments.
@@ -14,7 +14,7 @@ Environments, and their default data, are defined in the [Stoplight configuratio
 <!--(FIXME - SHOW SCREENSHOT OF THE ENVIRONMENTS WINDOW)-->
 
 For more information on environment variables and how they can be used during API testing, please
-see [here](../testing/variables-environment.md).
+see [here](/testing/using-variables/environment).
 
 ## Private Variables
 
@@ -41,11 +41,11 @@ Private variables are merged over default variables that share the same name. Th
 for individual team members to customize and extend environments without affecting the rest of the team.
 
 For more information on updating and customizing environment variables, please
-see [here](./editor-configuration.md#environments).
+see [here](/platform/editor-basics/editor-configuration).
 
-***
-
-**Results**
-
-* [Using Environment Variables in Testing](../testing/variables-environment.md)
-* [Configuration with the `.stoplight.yml` File](./editor-configuration.md#environments)
+---
+**Related Articles**
+- [Working with Files](/platform/editor-basics/working-with-files)
+- [Change History](/platform/editor-basics/change-history)
+- [Editor Configuration](/platform/editor-basics/editor-configuration)
+- [File Validation](/platform/editor-basics/file-validation)

articles/editor/file-validation.md

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

articles/editor/view-history-changes.md

@@ -8,7 +8,7 @@ navigation bar to the left of the project window (shown below). When the history
 is being viewed, you will see a series of changes for the project, listed in
 descending order by date.
 
-![](../../assets/images/viewing-changes2.png)
+![Viewing Changes](https://github.com/stoplightio/docs/blob/develop/assets/images/viewing-changes2.png?raw=true)
 
 Each change event includes:
 
@@ -23,10 +23,8 @@ Each change event includes:
 
 See the image below for an overview of the contents of the change view.
 
-![](../../assets/images/viewing-changes.png)
+![Viewing Changes Alt](https://github.com/stoplightio/docs/blob/develop/assets/images/viewing-changes.png?raw=true)
 
 ---
-
-**Related**
-
-* [Working with Files](./working-with-files.md)
+**Related Articles**
+- [Working with Files](/platform/editor-basics/working-with-files)

articles/editor/visual-code-view.md

@@ -1,7 +1,15 @@
-# Visual & Code Views
+# Read, Design, & Code Views
 
-![](../../assets/gifs/editor-visual-toggle.gif)
+![Read, Design, and Code View](https://github.com/stoplightio/docs/blob/develop/assets/gifs/editor-visual-toggle.gif?raw=true)
 
-Stoplight NEXT now has a toggle for switching between our visual editor and our code editor. If you prefer working with code, need to paste in some OAS, or just want to make changes manually, switch over to the code editor.  This new feature is included in all our editors including Hubs, Modeling, and Scenarios. 
+Stoplight Next has a toggle for switching between Read, Design, and Code views. If you prefer working with code, need to paste in some OAS, or just want to make changes manually, switch over to the code view.  This new feature is included in all our editors including Hubs, Modeling, and Scenarios. 
 
-<callout> New Feature! Any changes made in the code editor will automatically populate the visual editor. </>
+>New Feature! Any changes made in the code editor will automatically populate the visual editor
+
+---
+**Related Articles**
+- [Working with Files](/platform/editor-basics/working-with-files)
+- [Change History](/platform/editor-basics/change-history)
+- [Editor Configuration](/platform/editor-basics/editor-configuration)
+- [Environments](/platform/editor-basics/environments)
+- [File Validation](/platform/editor-basics/file-validation)

articles/editor/working-with-files.md

@@ -2,7 +2,7 @@
 
 ![](../../assets/gifs/fileexplorer.gif)
 
-As part of our effort to make the Stoplight platform more flexible and familiar we added a file explorer to Stoplight NEXT. You can now see all your files sorted by filetype in one central location within Projects. File types include: 
+As part of our effort to make the Stoplight platform more flexible and familiar we added a file explorer to Stoplight Next. You can now see all your files sorted by filetype in one central location within Projects. File types include: 
 
 * .hub (Hub/Docs Files)
 * .oas2 (Modeling Files)
@@ -22,3 +22,10 @@ Within the file explorer you can:
 	* Hover to the right of a file and click the **arrow** to export files into OAS
 * **Delete Files** 
 	* Hover to the right of a file and click the **trash can** to delete files
+
+---
+**Related Articles**
+- [Change History](/platform/editor-basics/change-history)
+- [Editor Configuration](/platform/editor-basics/editor-configuration)
+- [Environments](/platform/editor-basics/environments)
+- [File Validation](/platform/editor-basics/file-validation)

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

@@ -1,7 +1,5 @@
 # Welcome to Stoplight Next! 
 
-![The Original Three](https://github.com/stoplightio/docs/blob/develop/assets/images/stoplight-crew.jpg?raw=true)
-
 Now that you have the basics on what the [Stoplight Next Platform](/platform/introduction) 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/getting-started/organization-owner-introduction.md

@@ -2,36 +2,39 @@
 
 ![](/assets/gifs/org-create.gif)
 
-## Welcome to Stoplight NEXT!
+## Welcome to Stoplight Next!
 
-If you are trying to create a new Organization then you are in the right place. Stoplight NEXT was designed with large scale collaboration and governance as a central principle. The following guide will take you through the process of creating and populating an Organization, and offer an overview of the governance tools within Stoplight NEXT. 
+If you are trying to create a new Organization then you are in the right place. Stoplight Next was designed with large scale collaboration and governance as a central principle. The following guide will take you through the process of creating and populating an Organization, and offer an overview of the governance tools within Stoplight Next. 
 
 ## Organization 
-Organizations function as a shared space for you and your co-workers. Members of an Organization have access to a centralized Activity Feed, Project Repository, and an Issues (link) discussion tool. Organization Owners can also assign varying levels of Permissions to other members of the Organization.  
+Organizations function as a shared space for you and your co-workers. Members of an Organization have access to a centralized Activity Feed, Project Repository, and an Issues discussion tool. Organization Owners can also assign varying levels of Permissions to other members of the Organization.  
  
-* [Create an Organization](./create-org.md)
-* [Invite People to Organization](./managing-people.md) 
-* [Remove People from your Organization](./remove-people.md) 
-* [Member Roles and Permissions](./roles.md)
-* [Customize your Organization](./customize-org.md) 
-* [Transfer Primary Ownership](./transferring-ownership.md) 
-* [Delete an Organization](./delete-org.md)
+- [Create an Organization](/platform/organizations/create-org)
+- [Invite People to Organization](/platform/organizations/invite-people)
+- [Remove People from Your Organizations](/platform/organizations/remove-members)
+- [Organization Member Roles and Permissions](/platform/organizations/roles)
+- [Customize Your Organization](/platform/organizations/customize)
+- [Transfer Primary Ownership of an Organization](/platform/organizations/transfer-ownership)
+- [Delete an Organization](/platform/organizations/delete-org)
+
 
 ## Teams 
 If you are managing a large Organization with multiple teams you can use Teams to group Organization members together. 
 
-* [Create a Team](./create-team.md)
-* [Add People to a Team](./add-people.md)
-* [Remove People from a Team](./remove-people.md)
-* [Member Roles and Permissions](./member-roles.md) 
-* [Customize a Team](./customize-team.md) 
-* [Transfer Primary Ownership](./transfer-ownership.md) 
-* [Delete a Team](./delete-team.md) 
+- [Create a Team](/platform/organizations/teams/create-team)
+- [Add People to a Team](/platform/organizations/teams/add-people)
+- [Remove People for a Team](/platform/organizations/teams/remove-people)
+- [Team Member Roles and Permissions](/platform/organizations/teams/roles)
+- [Customize a Team](/platform/organizations/teams/create-team)
+- [Transfer Ownership of a Team](/platform/organizations/teams/transfer-ownership)
+- [Delete a Team](/platform/organizations/teams/delete)
+
 
 ## Projects 
-Projects are the workspaces you can create for your Organization. 
+Projects are the workspaces you can create for your Organization.
+
+- [Creating a Project](/platform/projects/creating-a-project)
+- [Invite People & Teams](/platform/projects/invite-people)
+- [Change a Project Member's Role](/platform/projects/change-a-members-role)
+- [Make Your Project Private/Public](/platform/projects/visibility)
 
-* [Creating a Project](./create-project.md) 
-* [Invite People & Teams to a Project](./invite-people-team.md)
-* [Change a Project Member’s Role](./change-member-role.md) 
-* [Make Your Project Private/Public](./visibility.md) 

articles/getting-started/what-is-stoplight.md

@@ -10,20 +10,21 @@ At Stoplight, everything starts with design. Our visual designer makes it easy f
 
 Whether you have an existing OpenAPI (Swagger) or are creating a new API design from scratch, we've got you covered.
 
-![](../../assets/images/modeling-editor.png)
+![Modeling Overview](https://github.com/stoplightio/docs/blob/develop/assets/images/modeling-overview.png?raw=true)
 
 ## API Testing
 Once you have your API design / documentation, how do you make sure that it remains accurate over time? Stoplight contract testing, powered by Prism, makes it trivial to create a full suite of tests that apply your API documentation (your contract) to your API. Run these tests from the Stoplight app, and standalone in your CI process or elsewhere.
 
-![](../../assets/images/scenarios-editor.png)
+![Scenarios Overview](https://github.com/stoplightio/docs/blob/develop/assets/images/testing-overview.png?raw=true)
 
 ## Documentation 
 
 You have your API designed and documented privately in the Stoplight app, and now you want to share all or part of it with 3rd parties (developers, customers, clients, etc). Stoplight makes it easy to publish your documentation to the world, with a single click.
 
 
-![](../../assets/images/HubsPreview.png)
+![Hubs Overview](https://github.com/stoplightio/docs/blob/develop/assets/images/hubs-overview.png?raw=true)
 
 ## Mock Server
 Stoplight provides a complete mock server for every API described in the app. Run tests against this mock server, build consumers (like mobile apps, SDKS, etc) before the final API is ready, and more.
 
+![Mocking Overview](https://github.com/stoplightio/docs/blob/develop/assets/images/mocking-overview.png?raw=true)

articles/hubs/blocks.md

@@ -5,7 +5,6 @@
 ## What
 Blocks are the micro-level building blocks of Hubs. They house multiple forms of content and allow for simple restructuring and modification. 
 
-<!-- theme: info -->
 >Hovering over a Block reveals additional tooling including: Preview, Cut, Copy, Reference External Source, and Delete
 
 ## Block Types 
@@ -34,6 +33,11 @@ Blocks are the micro-level building blocks of Hubs. They house multiple forms of
 
 ---
 **Related Articles**
-- [Pages](./pages.md)
-- [Subpages](./subpages.md)
-- [Reference Other Sources](./ref-other-sources-hubs.md)
+- [Documentation with Hubs](/documentation/introduction)
+- [Routing](/documentation/getting-started/routing)
+- [Headers & Footers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+- [Referencing Other Data Sources](/documentation/referencing-other-data-sources)
+- [Publishing](/documentation/publishing)
+

articles/hubs/hubs-introduction.md

@@ -1 +1,30 @@
+# Documentation with Hubs
 
+Documenting your API is critical to its success. The methods of creation and languages and libraries utilized to create APIs differ dramatically across the API landscape. To ensure that consumers of your API can access it, you must provide robust documentation of its services. To that end, Stoplight has created Hubs, our new documentation editor and generator. 
+
+Hubs allows users to:
+- Expedite the process of documenting your API
+- Focus on content instead of design 
+- Host documentation anywhere
+- Connect your API specification to your documentation
+
+## Optimized for Speed 
+- Hubs generates static documentation that gives you near instant load times and can be cached in the browser  
+- Makes it easy to add textual elements to your docs through a UI/UX designed for non-technical users 
+- Focuses on content instead of design
+- Can be served from anywhere or hosted by us 
+
+## Ensures Documentation Accuracy  
+
+One of the most common issues we wanted to solve with Hubs was outdated and incorrect documentation. This occurs because most solutions treat documentation as separate from the API design process. This ultimately leads to out of date documentation due to changes in API specifications not being reflected in documentation. Hubs connects your documentation to your API specification. Whenever you make changes to your API spec, it immediately gets pushed to your documentation, never have out of date docs again. 
+
+
+---
+**Related Articles**
+- [Routing](/documentation/getting-started/routing)
+- [Headers & Footers](/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)

articles/hubs/managing-headers-footers.md

@@ -1,32 +1,50 @@
 
-# Managing Headers and Footers 
+# Managing Headers 
 
 ![](../../assets/gifs/headers-footers.gif)
 
 ## What 
-You can customize the headers and footers of your Hub to add additional navigation to your documentation. You can modify a header and footer: 
+You can customize the headers of your Hub to add additional navigation to your documentation. You can modify a header's: 
 
-- **Location on Page**: Drag and drop along the header and footer to the desired location 
-- **Type**: Page, External Link, Image 
+- **Location on Page**
 - **Title**: What text is displayed on page
 - **Path to Page**: Specify path to page  
-- **Image URL**: If you want to display an image instead of text for the link input image URL 
+- **Image URL**: If you want to display an image within the header 
 
 
 ## How 
 
-### Modify Existing Header and Footer
+### Modify Existing Header 
 
 1. Select the Hub you wish to modify
-2. Click on the **Editing toggle** 
+2. Click on the **Design toggle** at the top of the page 
 3. By default, there will already be three headers (Home, API Reference, Help) and a footer (Home) 
-    1. Hover over one of the headers or footers and click on the **gear icon** to modify 
-    2. Drag the header or footer to another location to change its location 
+4. Hover over **Settings** in the top right and select **Hub**
+5. Select **Header** in the left had sidebar of the modal 
+6. Input new text under **Title** to modify text 
+7. Input an image URL under **Image** to add an image 
+8. Input a new **Path** to modify the header's destination 
 
+> The location of the header is determined by the order of the list in **Settings**. The first header item in either category will be displayed at the left extreme. 
 
-### Create New Header and Footer 
+### Create New Header
 
 1. Select the Hub you wish to modify 
-2. Click on the **Editing toggle**
-3. Hover over the left or right edge of the header or footer 
-    1. Click on the **+** button 
+2. Click on the **Design toggle** at the top of the page
+3. By default, there will already be three headers (Home, API Reference, Help) and a footer (Home) 
+4. Hover over **Settings** in the top right and select **Hub**
+5. Select **Header** in the left had sidebar of the modal
+6. Click **+ Add** to add a new header in either the left or right navigation 
+7. Input new text under **Title** to modify text 
+8. Input an image URL under **Image** to add an image 
+9. Input a new **Path** to modify the header's destination 
+
+---
+**Related Articles**
+- [Documentation with Hubs](/documentation/introduction)
+- [Routing](/documentation/getting-started/routing)
+- [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)

articles/hubs/pages.md

@@ -10,7 +10,7 @@ Pages are the macro level building blocks of a Hub. They function as the canvas
 - Pages 
     - Subpages 
         - Blocks
-    - Header and Footer 
+    - Header
     - Blocks 
 
 ## How 
@@ -18,19 +18,20 @@ Pages are the macro level building blocks of a Hub. They function as the canvas
 ### Create a New Page
 
 1. Select the Hub you wish to modify 
-2. Click on **Toggle Editor** 
-3. Select **+** Page in the editor toolbar 
-    1. Input a **Page Title** 
+2. Click on the **Design** toggle at the top of the page 
+3. Hover over **+ Add** at the top of the page 
+4. Click on **Page**
+    1. Input a **Page Title**
     2. Input a **Page Route** (optional) 
     3. **Power the Page** with an External Data Source (optional) 
 
-<!-- theme: info -->
- >Did you know? After creating a new page; a header link will automatically be generated
+ >Did you know? After creating a new page, a header link will automatically be generated
 
 ---
-**Related Articlers**
-- [Subpages](./subpages.md)
-- [Blocks](./blocks.md)
-- [Routing](./routing.md)
+**Related Articles**
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+- [Blocks](/documentation/blocks)
+
 
 

articles/hubs/publishing.md

@@ -7,7 +7,6 @@ Publishing your documentation has never been easier. Stoplight has added:
 - New **Authorizations** to make sure your documentation is secure at all times. This includes basic user/password authentication and SSO provider integration, powered by Auth0, SAML, and more.
 - New **Builds** section for tracking published Hubs, including when a Hub was published, who published it, and under what domain.
 
-<!-- theme: info -->
 >Take that Gutenberg! 
 
 ## Who 
@@ -31,3 +30,12 @@ Publishing your documentation has never been easier. Stoplight has added:
 11. Once a Hub is published, it will appear under **Builds** 
 12. To unpublish a Hub, select **Unpublish** in the **Danger Zone** underneath **Builds**
     - If you wish to delete all builds and release the domain you are currently using, select **Remove Domain**
+
+---
+**Related Articles**
+- [Documentation with Hubs](/documentation/introduction)
+- [Routing](/documentation/getting-started/routing)
+- [Headers & Footers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+- [Blocks](/documentation/blocks)

articles/hubs/ref-other-sources-hubs.md

@@ -24,6 +24,13 @@ Hubs allows you to reference other sources to automatically populate your Hub wi
     4. Input an inner data source (optional)  
 4. Click **Confirm**  
 
-<!-- theme: info -->
 >Try it Out! Power a Subpage with an API Spec from the same project.
 
+---
+**Related Articles**
+- [Documentation with Hubs](/documentation/introduction)
+- [Routing](/documentation/getting-started/routing)
+- [Headers & Footers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+- [Blocks](/documentation/blocks)

articles/hubs/routing.md

@@ -7,13 +7,12 @@
 Stoplight’s Hubs features an easy to use routing system to make sure your docs have identifiable and friendly URL’s. The routing system allows customization of the following objects: 
 
 - Your Hub 
-- [Pages within a Hub](./pages.md) 
-- [Subpages within a Hub](./subpages.md) 
-- [Headers + Footers](./managing-headers-footers.md)
+- [Pages within a Hub](/documentation/getting-started/pages) 
+- [Subpages within a Hub](/documentation/getting-started/subpages) 
+- [Headers + Footers](/documentation/getting-started/header-footer)
 - Links 
 
 
-<!-- theme: info -->
 >Friendly URLs are links that are easily readable, rememberable, and relevant to the content.
 
 
@@ -22,7 +21,7 @@ Stoplight’s Hubs features an easy to use routing system to make sure your docs
 ### Pages & Subpages 
 
 1. Select the **Hub** you wish to modify 
-2. Add a new **page** or **subpage** (link) 
+2. Add a new **page** or **subpage**  
    1. Select a **page title** to auto-fill the **Page Route** or 
    2. Input a **custom page route** 
 3. Select an **existing page** or **subpage** 
@@ -32,12 +31,13 @@ Stoplight’s Hubs features an easy to use routing system to make sure your docs
 ### Headers & Footers 
 
 1. Select the **Hub** you wish to modify 
-2. Add a new **header or footer** (link) or
+2. Add a new **[header or footer](/documentation/getting-started/header-footer)** or
 3. Hover over an existing header or footer and click the **gear icon** 
     a. Input a **Path to Page** or **image URL**  
 
 ---
 **Related Articles**
-- [Pages within a Hub](./pages.md) 
-- [Subpages within a Hub](./subpages.md) 
-- [Headers + Footers](./managing-headers-footers.md)
+- [Headers & Footers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+

articles/hubs/subpages.md

@@ -5,7 +5,6 @@
 ## What
 Subpages are the second tier macro building blocks of Hubs. They function as a canvas for blocks. They are commonly used to house content based on a specific topic.  Subpages can have more subpages nested underneath them, which gives you lots of flexibility to organize your Hub as you see fit. If a subpage has subpages nested inside of it, it will be displayed as a collapsible group in the left sidebar.
 
-<!-- theme: info -->
 >Subpages populate the navigational sidebar of a page.
 
 ### Hubs Architecture Top Down
@@ -27,12 +26,12 @@ Subpages are the second tier macro building blocks of Hubs. They function as a c
     3. Give the Subpage a **Sidebar Token** (optional) 
     4. **Power the Subpage** with an External Data Source (optional) 
 
-<!-- theme: info --> 
+
 >Just like pages, subpages can have blocks. Any blocks added to a subpage will be displayed when a reader navigates to that subpage in your Hub
 
 ---
 **Related Articles**
-- [Pages](./pages.md)
-- [Headers & Footers](./managing-headers-footers.md)
-- [Routing](./routing.md)
-- [Publishing](./publishing.md)
+- [Routing](/documentation/getting-started/routing)
+- [Headers & Footers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Publishing](/documentation/publishing)

articles/modeling/how-to-create-models.md

@@ -60,26 +60,26 @@ A design first approach helps create neat and consistent models. It will take lo
 
 6. To create a model click on the + sign next to the Model section.
 
-![](../../assets/images/create-model.png)
+![Create model button](https://github.com/stoplightio/docs/blob/develop/assets/images/create-model.png?raw=true)
 
 7. Enter the details for the key, title, and description fields
 
-![](../../assets/images/editor-details.png)
+![Model details](https://github.com/stoplightio/docs/blob/develop/assets/images/editor-details.png?raw=true)
 
 8. Click on the Editor Tab to create the object and specify the properties you want in the model (You can also copy and paste the JSON Schema from an endpoint into the Raw Schema section of the model)
 
-![](../../assets/images/create-object.png)
+![Create object](https://github.com/stoplightio/docs/blob/develop/assets/images/create-object.png?raw=true)
 
-![](../../assets/images/model-design.png)
+![Example model design](https://github.com/stoplightio/docs/blob/develop/assets/images/model-design.png?raw=true)
 
 9. Click the Save button to save the changes you have made in the editor 
 10. Select the GET  /pets {petid} (or any endpoint)  and navigate to Responses→ Editor 
 11. To reference the model in your endpoint, click on the object and select $ref as the array item type. Select the model you created from the drop down list
 
-![](../../assets/images/ref-model.png)
+![Referencing model](https://github.com/stoplightio/docs/blob/develop/assets/images/ref-model.png?raw=true)
 
 12. Select the Viewer section to see the changes you have made
 
-![](../../assets/images/viewer-ref-model.png)
+![Viewer view of model](https://github.com/stoplightio/docs/blob/develop/assets/images/viewer-ref-model.png?raw=true)
 
 13. All changes made to the properties of the object in the model are now automatically updated in all endpoints that make a reference to the model

articles/modeling/modeling-introduction.md

@@ -1,5 +1,7 @@
 # Modeling Introduction 
 
+![Design Abstract](https://github.com/stoplightio/docs/blob/develop/assets/images/design.png?raw=true)
+
 ## What is API Design? 
 
 Designing (also known as Modeling) your API involves describing all of the inputs and outputs across the footprint of your entire service. Your API design will answer questions like: 

articles/modeling/openapi-validation.md

@@ -1,6 +1,6 @@
 # OpenAPI Validation
 
-![](../../assets/gifs/file-validation-oas-spec.gif)
+![Looking at validation errors for OAS spec](https://github.com/stoplightio/docs/blob/develop/assets/gifs/file-validation-oas-spec.gif?raw=true)
 
 ## What
 OpenAPI validation is the process of verifying the underlying OpenAPI file syntax by making sure it conforms to the [OpenAPI Specification requirements](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification) provided by the [OpenAPI Initiative](https://www.openapis.org/). Stoplight immediately validates any changes done to a spec to ensure they are in the correct format prior to being saved.

articles/modeling/security-schemes.md

@@ -15,7 +15,7 @@ started, the section below outlines some common schemes in use.
 * Should not be used without SSL, or some other data-in-transit encryption mechanism
 * Can easily be combined with other security methods
 
-> **Note**, basic authentication is susceptible to hijacks and man-in-the-middle
+> **Note**: basic authentication is susceptible to hijacks and man-in-the-middle
 > attacks when no encryption is in use. Due to this limitation, this method of
 > authentication is only recommended when paired with SSL.
 
@@ -89,4 +89,4 @@ identify potential security risks.
 **Related**
 
 * [Additional Information on HTTP Status and Error Codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
-* [API Operations](/modeling/introduction/modeling-with-openapi/api-operations)
+* [API Operations](/modeling/modeling-with-openapi/api-operations)

articles/modeling/sending-http-requests.md

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

articles/modeling/shared-params-responses.md

@@ -21,7 +21,7 @@ Shared components in Stoplight come in two forms:
 Shared parameters provide a way to use request properties across multiple API
 endpoints without having to duplicate effort.
 
-![](../../assets/gifs/shared-params-responses-param.gif)
+![How to create a shared parameter](https://github.com/stoplightio/docs/blob/develop/assets/gifs/shared-params-responses-param.gif?raw=true)
 
 Shared parameters are supported in the following request property locations:
 
@@ -31,14 +31,13 @@ Shared parameters are supported in the following request property locations:
   * __body__ - The request HTTP message body
   * __form-data__ - The request HTTP message body in the `multipart/form-data` format 
 
-<!-- theme: info -->
 > For more information the above properties, see the [OpenAPI v2 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object)
 
 Similar to generic request parameters, restrictions on the parameter values can
 also be applied based on type, expected default value, minimum/maximum length,
 and regular expression (regex).
 
-![](../../assets/images/shared-params-responses.png)
+![Create a reference to a shared parameter](https://github.com/stoplightio/docs/blob/develop/assets/images/shared-params-responses.png?raw=true)
 
 To use a shared parameter, navigate to an API endpoint's _Request_ section and
 create a reference to the shared parameter using the "chain" button as shown in
@@ -46,7 +45,7 @@ the image above. Once the parameter has been referenced, any updates to the
 shared parameter will automatically be propagated to every endpoint using that
 parameter.
 
-![](../../assets/gifs/shared-params-responses-param2.gif)
+![Reference as a query parameter](https://github.com/stoplightio/docs/blob/develop/assets/gifs/shared-params-responses-param2.gif?raw=true)
 
 Like other references in Stoplight, shared parameters can also be shared across
 files, projects, and other external sources.
@@ -95,7 +94,7 @@ Now that we know how we want the components to behave, let's create them in
 Stoplight. To get started, create a new shared parameter for an OpenAPI file
 under the "Shared" section of the menu.
 
-![](../../assets/images/shared-params-responses2.png)
+![Instructions below](https://github.com/stoplightio/docs/blob/develop/assets/images/shared-params-responses2.png?raw=true)
 
 As shown in the image above, set the properties for each parameter based on our
 requirements:
@@ -114,7 +113,7 @@ requirements:
    each parameter for every request. For our example, it makes sense to set
    defaults that will return the first page (limit of 20, offset of 0).
 
-![](../../assets/images/shared-params-responses3.png)
+![Linking a shared parameter](https://github.com/stoplightio/docs/blob/develop/assets/images/shared-params-responses3.png?raw=true)
 
 Once the shared parameters are created, reference them in any API endpoint under the
 __Query Parameters__ block of the request section in the editor.
@@ -129,7 +128,7 @@ benefit of this approach is that updates to the shared response object are
 automatically propagated to any endpoint using that object, no extra changes
 required.
 
-![](../../assets/gifs/shared-params-responses-response.gif)
+![How to create a shared response](https://github.com/stoplightio/docs/blob/develop/assets/gifs/shared-params-responses-response.gif)
 
 Shared responses allow you to configure the following properties:
 
@@ -137,11 +136,11 @@ Shared responses allow you to configure the following properties:
 * Response body - Customize the HTTP message body contents using the Stoplight
   modeling tool (or reference a pre-existing model)
 
-<!-- theme: info -->
+
 > For more information on the above properties, see the OpenAPI v2 Specification
   [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject)
 
-![](../../assets/gifs/shared-params-responses-response2.gif)
+![](../../assets/gifs/shared-params-responses-response2.gif?raw=true)
 
 To use a shared response, navigate to an API endpoint's __Response__ section and
 create a reference to the shared response by choosing the _Type_ of the response
@@ -166,7 +165,7 @@ Now that we know what should be returned, let's create a shared response in
 Stoplight. To get started, create a new shared response for an OpenAPI file
 under the "Shared" section of the menu.
 
-![](../../assets/images/shared-params-responses4.png)
+![](https://github.com/stoplightio/docs/blob/develop/assets/images/shared-params-responses4.png?raw=true)
 
 As shown in the image above, set the properties for each portion of the response
 based on our requirements:
@@ -180,7 +179,7 @@ based on our requirements:
 3. The contents of the shared response object based on the three required
    properties above.
 
-![](../../assets/images/shared-params-responses5.png)
+![](https://github.com/stoplightio/docs/blob/develop/assets/images/shared-params-responses5.png?raw=true)
 
 Once the shared response is created, it can be referenced in any API endpoint by
 using a _Reference_ type under a response. A shared response can also be used

articles/prism/overview.md

@@ -58,5 +58,4 @@ path/to/prism.exe test --spec https://goo.gl/jniYmw
 
 You should see some nice output to your terminal detailing the tests and assertions that are run. These tests take our OAS contract and apply it to your API. They act as a sort of sync manager. 
 
-<!-- theme: info -->
 > If a test fails, it means one of two things - your API is broken or, our OAS contract is out of date / incorrect 

articles/projects/change-member-role.md

@@ -1,6 +1,6 @@
 # Change a Project Member's Role
 
-![](/assets/gifs/project-member-invite.gif)
+![Change a Project Member's Role](https://github.com/stoplightio/docs/blob/develop/assets/gifs/project-change-role.gif?raw=true)
  
 ## What 
 You can invite people to a Project to grant them read or read/write permissions. There are three tiers of read/write permissions: 
@@ -15,10 +15,9 @@ You can invite people to a Project to grant them read or read/write permissions.
     * Read
       
    
-## 	 Who 
+## Who 
 * Only the Organization **Owner** and Organization or Project **Administrators** can modify member roles
 
-<!-- theme: info -->
 >By deafult, all members of the Organization and the Project will have Read permission
 
 ## How

articles/projects/create-project.md

@@ -1,6 +1,6 @@
 # Creating a Project  
 
-![Create a Project](https://github.com/stoplightio/docs/blob/develop/assets/gifs/project-create-personal.gif?raw=true)
+![Create a Project in an Organization](https://github.com/stoplightio/docs/blob/develop/assets/gifs/project-create-org-project.gif?raw=true)
 
 ## What 
 Projects are the workspace of the Stoplight Platform. Projects contain: 
@@ -12,7 +12,6 @@ Projects are the workspace of the Stoplight Platform. Projects contain:
 * Mocking (Prism) 
 * Markdown Editor 
 
-<!-- theme: info -->
 >Single Point of Truth: All editors are now contained within a Project
 
 ## Who 

articles/projects/invite-people-team.md

@@ -1,6 +1,6 @@
 # Invite People & Teams to a Project
 
-![](../../assets/gifs/project-member-invite.gif)
+![Invite People and Teams to a Project](https://github.com/stoplightio/docs/blob/develop/assets/gifs/project-invite-people-teams.gif?raw=true)
  
 ## What 
 * You can invite people to a Project to grant them read or read/write permissions 

articles/projects/visibility.md

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

articles/teams/member-roles.md

@@ -8,9 +8,9 @@ There are 3 Roles:
 * **Owner** 
     * Owners can update the Team, its connections, and its collaborators. They can also update the team's settings and delete the team.
 * **Administrator** 
-        * Admins can update the Team, its connections, and its collaborators. 
+    * Admins can update the Team, its connections, and its collaborators. 
 * **Member** 
-        * Members can view and create projects. They can view the Team's members.
+    * Members can view and create projects. They can view the Team's members.
            
 ## Who
 * Only the Team **Owner** or **Administrator** can modify Roles and Permissions 

articles/testing/continuous-integration-circle.md

@@ -72,23 +72,18 @@ When running `prism conduct` you can:
 * Include the Scenario JSON on your CI server, and pass in its absolute file path
 * Pass in the absolute URL to the scenario JSON served up via HTTP
 
-<!-- theme: warning -->
-
 > Don't forget to pass in any required environment values with the --env command
 > line flag (or you can provide the filepath to a json file with your environment
 > variables)!
 
-<!-- theme: info -->
-
 > Did you know? You can find the full command to run your scenario collection
 > or individual scenarios in the Stoplight application. Click on the "Home"
 > button of a scenario under "Trigger This Collection".
 
 ---
 
-**Related**
-
-* [Continuous Integration Overview](./continuous-integration.md)
-* [Continuous Integration with Travis CI](./continous-integration-travis)
-* [Continuous Integration with Jenkins](./continous-integration-jenkins)
-* [Prism Docker Image](https://hub.docker.com/r/stoplight/prism/)
+**Related Articles**
+- [Integrating in Continuous Integration](/testing/continuous-integration/overview)
+- [Integrating with Jenkins](/testing/continuous-integration/jenkins)
+- [Integrating with Travis](/testing/continuous-integration/travis)
+- [Prism Docker Image](https://hub.docker.com/r/stoplight/prism/)

articles/testing/continuous-integration-jenkins.md

@@ -28,7 +28,6 @@ off your tests. If running natively, use the command format:
 BUILD_ID=dontKillMe nohup prism mock --spec ... &
 ```
 
-<!-- theme: warning -->
 
 > Please note that the trailing ampersand (`&`) is required
 
@@ -38,7 +37,7 @@ If running in Docker, use the format:
 docker run -d --rm -p 4010:4010 stoplight/prism:latest mock --spec ...
 ```
 
-For more information on using Prism as a test server, see [here](./overview.md).
+For more information on using Prism as a test server, see [here](/mocking/introduction).
 
 ### Running Prism in the Foreground
 
@@ -60,13 +59,11 @@ When running `prism conduct`, you can:
 * Include the Scenario JSON on your CI server, and pass in its absolute file path
 * Pass in the absolute URL to the scenario JSON served up via HTTP
 
-<!-- theme: warning -->
 
 > Don't forget to pass in any required environment values with the --env command
 > line flag (or you can provide the filepath to a json file with your environment
 > variables)!
 
-<!-- theme: info -->
 
 > Did you know? You can find the full command to run your scenario collection
 > or individual scenarios in the Stoplight application. Click on the "Home"
@@ -83,10 +80,10 @@ on the plugin, see [here](https://plugins.jenkins.io/stoplightio-report).
 
 **Related**
 
-* [Jenkins Website](https://jenkins.io/)
-* [Continuous Integration Overview](./continuous-integration.md)
-* [Continuous Integration with Circle CI](./continous-integration-circle)
-* [Continuous Integration with Travis CI](./continous-integration-travis)
-* [Prism Docker Image](https://hub.docker.com/r/stoplight/prism/)
-* [Stoplight Report Plugin Homepage](https://plugins.jenkins.io/stoplightio-report)
-* [Stoplight Report Plugin Github](https://github.com/jenkinsci/stoplightio-report-plugin)
+- [Jenkins Website](https://jenkins.io/)
+- [Integrating in Continuous Integration](/testing/continuous-integration/overview)
+- [Integrating with Travis](/testing/continuous-integration/travis)
+- [Integrating with CircleCI](/testing/continuous-integration/circle-ci)
+- [Prism Docker Image](https://hub.docker.com/r/stoplight/prism/)
+- [Stoplight Report Plugin Homepage](https://plugins.jenkins.io/stoplightio-report)
+- [Stoplight Report Plugin Github](https://github.com/jenkinsci/stoplightio-report-plugin)

articles/testing/continuous-integration-travis.md

@@ -49,13 +49,11 @@ When running `prism conduct` you can:
 * Include the Scenario JSON on your CI server, and pass in its absolute file path
 * Pass in the absolute URL to the scenario JSON served up via HTTP
 
-<!-- theme: warning -->
 
 > Don't forget to pass in any required environment values with the --env command
 > line flag (or you can provide the filepath to a json file with your environment
 > variables)!
 
-<!-- theme: info -->
 
 > Did you know? You can find the full command to run your scenario collection
 > or individual scenarios in the Stoplight application. Click on the "Home"
@@ -63,9 +61,9 @@ When running `prism conduct` you can:
 
 ---
 
-**Related**
+**Related Articles**
 
-* [Continuous Integration Overview](./continuous-integration.md)
-* [Continuous Integration with Circle CI](./continous-integration-circle)
-* [Continuous Integration with Jenkins](./continous-integration-jenkins)
-* [Prism Docker Image](https://hub.docker.com/r/stoplight/prism/)
+- [Integrating in Continuous Integration](/testing/continuous-integration/overview)
+- [Integrating with Jenkins](/testing/continuous-integration/jenkins)
+- [Integrating with CircleCI](/testing/continuous-integration/circle-ci)
+- [Prism Docker Image](https://hub.docker.com/r/stoplight/prism/)

articles/testing/continuous-integration.md

@@ -16,13 +16,13 @@ the lifetime of the project.
 
 There are a few different approaches available when integrating Prism into a CI
 testing pipeline:
-testing with Stoplight [Scenarios](./scenarios-introduction.md),
+testing with Stoplight [Scenarios](/testing/introduction),
 testing with a mock server, and
 contract testing.
 
 ## Testing with Scenarios
 
-Stoplight [Scenarios](./scenarios-introduction.md) allows users to define
+Stoplight [Scenarios](/testing/introduction) allows users to define
 multiple steps for testing an OpenAPI specification. Scenarios provide a similar
 function to API's as [functional test
 cases](https://en.wikipedia.org/wiki/Functional_testing) do in software
@@ -35,7 +35,7 @@ To run a scenario with Prism, use the `conduct` command:
 prism conduct my-scenario.json --spec open-api-spec.json -e "myapikey=abc123"
 ```
 
-For more information on Scenarios, please see [here](./scenarios-introduction.md).
+For more information on Scenarios, please see [here](/testing/introduction).
 
 ## Testing with a Mock Server
 
@@ -57,7 +57,7 @@ To start a mock server with Prism, use the `mock` command:
 prism mock --spec open-api-spec.json
 ```
 
-For more information on mock testing with Prism, see [Mocking Introduction](FIXME).
+For more information on mock testing with Prism, see [Mocking Introduction](/mocking/introduction).
 
 ## Contract Testing
 
@@ -79,14 +79,14 @@ To start a contract/validation server with Prism, use the `validate` command:
 prism validate --spec open-api-spec.json --upstream http://localhost:8080
 ```
 
-For more information on contract testing with Prism, see [Mocking Introduction](FIXME).
+>For more information on contract testing with Prism, see [Mocking Introduction](/mocking/introduction).
 
 ---
 
 **Related**
+- [Mocking Introduction](/mocking/introduction)
+- [Testing Introduction](/testing/introduction)
+- [Integrating with Jenkins](/testing/continuous-integration/jenkins)
+- [Integrating with Travis](/testing/continuous-integration/travis)
+- [Integrating with CircleCI](/testing/continuous-integration/circle-ci)
 
-* [Testing Overview](./overview.md)
-* [Scenarios Introduction](./scenarios-introduction.md)
-* [Continuous Integration with Circle CI](./continous-integration-circle.md)
-* [Continuous Integration with Travis CI](./continous-integration-travis.md)
-* [Continuous Integration with Jenkins](./continous-integration-jenkins.md)

articles/testing/contract-testing.md

@@ -23,10 +23,8 @@ Benefits of contract testing include:
   pipeline ensures that the spec accurately represents your API implementation
   over time.
 
-<!-- theme: info -->
-
 > If you don't have an API specification yet, you can create one using the
-> [Stoplight modeling tool](../modeling/modeling-introduction.md)!
+> [Stoplight modeling tool](/modeling/introduction)!
 
 ## Connecting a Spec
 
@@ -84,3 +82,16 @@ JSON schema.
 When a contract assertion step is run, the HTTP response structure will be
 validated against the matched JSON schema from the connected API specification.
 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)
+- [Using Variables Overview](/testing/using-variables/overview)
+- [$$.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

@@ -1 +1,42 @@
+# Testing with Scenarios
 
+Following the rise of APIs, it has become increasingly important to develop highly flexible, performant, and powerful testing roadmaps to catch bugs faster and rapidly iterate without breaking existing features. A thorough test suite is essential for: 
+- Assessing the health of an API
+- Providing valuable documentation 
+- Driving design and implementation 
+- Managing technical debt 
+
+## Assessing the Health of an API
+
+APIs require maintenance like any other software. To ensure that your API is functioning properly, a suite of tests should be run periodically to check for weaknesses and errors.  
+
+>Create and [run tests within Stoplight](/testing/running-tests/in-stoplight), [the terminal](/testing/running-tests/in-the-terminal), or [trigger it by URL](/testing/running-tests/triggering-by-url). If you prefer to [use CI](/testing/continuous-integration/overview), Stoplight also provides integrations to [Jenkins](/testing/continuous-integration/jenkins), [CircleCI](/testing/continuous-integration/circle-ci), and [Travis](/testing/continuous-integration/travis).  
+
+## Providing Valuable Documentation & Driving Design
+
+API tests provide insight into how your API behaves under certain scenarios and can drive design if created early enough in the design process. Test/Behavior-driven development (TDD/BDD) encourages you to think about design requirements before writing any code. 
+
+>Stoplight further promotes this design first principle by providing [Contract Testing](/testing/leveraging-openapi/contract-testing); an integration between your tests and your OpenAPI Specification. This allows for immediate validation and verification that your API responses match the “Contract” specified in your OpenAPI spec.
+
+## Managing Technical Debt 
+
+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. 
+
+---
+**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)
+- [Using Variables Overview](/testing/using-variables/overview)
+- [$$.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)
+- [Integrating with Jenkins](/testing/continuous-integration/jenkins)
+- [Integrating with Travis](/testing/continuous-integration/travis)
+- [Integrating with CircleCI](/testing/continuous-integration/circle-ci)

articles/testing/run-test-stoplight.md

@@ -2,13 +2,12 @@
 
 Scenarios allow you to quickly and efficiently test APIs. Scenarios can be
 run in a variety of different ways, including from the [command-line with
-Prism](./run-test-terminal.md) or by [URL](./run-test-url). However, the easiest
+Prism](/testing/running-tests/in-the-terminal) or by [URL](/testing/running-tests/triggering-by-url). However, the easiest
 way is through the Stoplight editor.
 
-<!-- theme: info -->
 
 > If you haven't created your first scenario yet, please [do so before
-> continuing](./scenarios-introduction.md)
+> continuing](testing/introduction)
 
 Scenarios in Stoplight are composed of three different levels:
 
@@ -42,7 +41,6 @@ as show below.
 
 ![](../../assets/images/run-test-stoplight2.png)
 
-<!-- theme: info -->
 
 > Scenarios can also be run directly from every step using the **Run Scenario**
 > button
@@ -56,15 +54,14 @@ of the editor while viewing the collection home screen, as shown below.
 
 ![](../../assets/images/run-test-stoplight3.png)
 
-<!-- theme: info -->
 
 > Collections can also be run from the scenario and step screens using the **Run
 > Collection** button
 
 ---
 
-**Related**
+**Related Articles**
+- [Testing Introduction](/testing/introduction)
+- [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
+- [Running Tests Triggered by URL](/testing/running-tests/triggering-by-url)
 
-* [Scenarios Overview](./scenarios-introduction.md)
-* [Running Scenarios from the Command-Line](./run-test-terminal.md)
-* [Running Scenarios by URL](./run-test-url.md)

articles/testing/run-test-terminal.md

@@ -10,8 +10,6 @@ _On macOS or Linux:_
 curl https://raw.githubusercontent.com/stoplightio/prism/2.x/install.sh | sh
 ```
 
-<!-- theme: info -->
-
 > When installed through the installation script, Prism will be installed to `/usr/local/bin/prism`
 
 _On Windows:_
@@ -24,7 +22,6 @@ After installing, you should be able to run `prism -h` (or `prism.exe -h` in Win
 
 The Scenario app has a convenient display that gives you the exact command required to run the collection or scenario that you are viewing (taking into account your current environment variables). If you have the Scenario editor connected to a local file on your computer, it will use the path to that file, otherwise it will use the Scenario SRN (unique identifier).
 
-<!-- theme: warning -->
 
 > Keep in mind that if you are storing your Scenarios on Stoplight's servers, and running them from the command line, you must save them in the Stoplight app before running! This is because Prism will make a call to the Stoplight API to fetch your Scenario JSON, which it will then run from your computer.
 
@@ -47,7 +44,7 @@ prism conduct /path/to/collection.json
 prism conduct "https://export.stoplight.io/1234/master/main.scenarios.yml"
 ```
 
-For more information on Scenarios and how they can be used, see [here](./scenarios-introduction.md).
+For more information on Scenarios and how they can be used, see [here](/testing/introduction).
 
 ## Contract Testing
 
@@ -66,10 +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](./contract-testing.md).
+For more information on contract testing and how it can be used, see [here](testing/leveraging-openapi/contract-testing).
 
-## Related
+---
+**Related Articles**
 
-* [Scenarios Overview](./scenarios-introduction.md)
-* [Contract Testing Overview](./contract-testing.md)
-* [Integrating Prism into a CI Pipeline](./continuous-integration.md)
+- [Testing Introduction](/testing/introduction)
+- [Contract Testing](testing/leveraging-openapi/contract-testing)
+- [Integrating in Continuous Integration](/testing/continuous-integration/overview)

articles/testing/run-test-url.md

@@ -1,6 +1,6 @@
 # Triggering Scenarios by URL
 
-In addition to being able to run tests [through Stoplight](./run-test-stoplight.md) and [the terminal](./run-test-terminal.md),
+In addition to being able to run tests [through Stoplight](/testing/running-tests/in-stoplight) and [the terminal](/testing/running-tests/in-the-terminal),
 scenarios can also be run by issuing a HTTP request.
 
 To trigger a scenario by URL, there are two methods:
@@ -107,14 +107,12 @@ it to be used to authenticate with the Stoplight API. For example:
 $ curl -H 'Private-Token: H4BTDASDf5sGHMWJSfE32' ...
 ```
 
-<!-- theme: warning -->
-
 > Be sure to keep all private tokens safe! They can be used to authenticate
 > requests with any project that your account has access to.
 
 ---
 
-**Related**
+**Related Articles**
+- [Running Tests In Stoplight](/testing/running-tests/in-stoplight)
+- [Running Tests in the Terminal](/testing/running-tests/in-the-terminal)
 
-* [Running Scenarios through Stoplight](./run-test-stoplight.md)
-* [Running Scenarios from the Terminal](./run-test-terminal.md)

articles/testing/send-http-requests.md

@@ -1,50 +1,116 @@
-# Overview of Testing with HTTP Requests 
+# Overview of Testing with HTTP Requests
 
-## What are HTTP methods? 
+## What are HTTP methods?
 
-- Hypertext Transfer Protocol (HTTP) is a set of rules that define how information is requested, transmitted, and formatted between a client and a server. HTTP methods (verbs) are used to implement create, read, update, and delete operations on identified resources. 
-- HTTP methods are classified as safe, non-safe methods, idempotent or non-idempotent methods. Safe methods do not change the state of a resource. Idempotent methods, if executed severally, deliver consistent outcomes. An example of idempotency is outlined below:
+Hypertext Transfer Protocol (HTTP) is a set of rules that define how information
+is requested, transmitted, and formatted between a client and a server. HTTP
+methods (verbs) are used to implement create, read, update, and delete
+operations on identified resources.
 
-### Example 
-- petAge = 2 # will always return 2 even when the statement is executed over and over again. This statement is idempotent. 
-- petAge++ # will return different results based on the number of executions. This statement is non-idempotent. 
+Each HTTP method can be classified as safe, idempotent, or both.
+
+### Safe Methods
+
+Safe methods do not change the state of a resource. Safe methods include:
+
+* **OPTIONS**
+* **GET**
+* **HEAD**
+
+### Idempotent Methods
+
+Idempotent methods can be called several times and should expect the same
+results. Idempotent methods include:
+
+* **OPTIONS**
+* **GET**
+* **HEAD**
+* **PUT**
+* **DELETE**
+
+To demonstrate an idempotent HTTP request:
+
+* `GET petAge`, where the returned age is 2. Since the result will always return
+  2 when the statement is issued over and over again, this request is
+  idempotent
+* `POST petAge`, where you are incrementing the age of a pet. Since we are
+  actively incrementing the age, each successive execution will give the pet a
+  different age each time, making this request non-idempotent
 
 ## Methods
-- The **GET** method retrieves data and resource representation. It does not change the state of a resource and several executions produce the same results. Thus, it is a safe and idempotent method. When a GET method is successful, it should return a 200 (OK) HTTP status code with the content in the response body and a 404 (NOT FOUND) code if the resource is not available. 
-- The **POST** method creates new resources. The POST method is not safe and is non-idempotent as the execution of similar POST requests will create two different resources with similar details. It is suggested for non-idempotent resource requests. 
-- The **PATCH** method makes partial updates to a resource and it is non-idempotent. 
-- The **PUT** method updates a resource or creates a new resource if it does not exist. It is ideal for the complete update of a resource. The PUT method is idempotent but not safe. 
-- The **DELETE** method deletes a resource. It is idempotent but not safe. 
 
-### Summary 
-The GET method is the only safe method, as it does not change the state of a resource. GET, PUT, and DELETE methods are idempotent while the POST and PATCH methods are non-idempotent. 
+* The **GET** method retrieves data and resource representation. It does not
+  change the state of a resource and several executions produce the same
+  results. Thus, it is a safe and idempotent method. When a GET method is
+  successful, it should return a 200 (OK) HTTP status code with the content in
+  the response body and a 404 (NOT FOUND) code if the resource is not available
 
-## Testing with HTTP Requests 
-- Testing using HTTP Requests demonstrates whether or not an API will perform as expected when it is deployed to a production server and integrated with existing platforms. 
+* The **POST** method creates new resources. The POST method is not safe and is
+  non-idempotent as the execution of similar POST requests will create two
+  different resources with similar details. It is suggested for non-idempotent
+  resource requests
+
+* The **PATCH** method makes partial updates to a resource and it is
+  non-idempotent
+
+* The **PUT** method updates a resource or creates a new resource if it does not
+  exist. It is ideal for the complete update of a resource. The PUT method is
+  idempotent but not safe
+
+* The **DELETE** method deletes a resource. It is idempotent, but not safe
+
+## Testing with HTTP Requests
+
+Testing using HTTP Requests demonstrates whether or not an API will perform as
+expected when it is deployed to a production server and integrated with existing
+platforms.
 
-<!-- theme: info -->
 > HTTP Request Tests should include checks to the response code, message, and body.
 
-- Apart from verifying the functionality of essential features, HTTP Request Tests **save time and cost**.
+Apart from verifying the functionality of essential features, HTTP Request Tests
+**save time and cost**.
 
-## Testing with HTTP Requests: Best Practices 
+## Testing with HTTP Requests: Best Practices
+
+Testing is a critical stage of the API development life cycle and the type of
+tests executed will depend on the complexity of the API, time, budget, etc. It
+is vital to conduct robust tests to reveal any inconsistencies or defects in
+the API before it is shipped to a production server or interfaced with other
+platforms.
 
 ### GET
-- Test the GET method to confirm it returns the correct data.
-- Test a valid GET request to ensure it returns a 200 (OK) status code or 404 (NOT FOUND) if invalid 
-- Ensure you test every endpoint fetching data within your API before deployment to a production server. 
+
+* Test the GET method to confirm it returns the correct data
+* Test a valid GET request to ensure it returns a 200 (OK) status code or 404 (NOT FOUND) if invalid
+* Ensure you test every endpoint fetching data within your API before deployment to a production server
 
 ### POST
-- Test the POST method to confirm it creates a resource and returns a 200(OK) code and/or 201(CREATED) code if valid. If invalid, look for a 4xx error status code. 
-- You can use the GET method to see the outcome of the POST operation. 
+
+* Test the POST method to confirm it creates a resource and returns a 200(OK)
+  code and/or 201(CREATED) code if valid. If invalid, look for a 4xx error
+  status code
+* You can use the GET method to see the outcome of the POST operation
 
 ### PUT & PATCH
-- The PUT and PATCH update methods should be tested to ensure that a 200(OK) status code or 204(NO CONTENT) is returned for a successful transaction. If unsuccessful, look for a 4xx error status code. 
+
+* The PUT and PATCH update methods should be tested to ensure that a 200(OK)
+  status code or 204(NO CONTENT) is returned for a successful transaction. If
+  unsuccessful, look for a 4xx error status code
 
 ### DELETE
-- Test the DELETE request to certify it returns a 4xx error code if a DELETE operation is executed against an invalid or non-existent resource. 
-- Test the DELETE request to confirm it returns a 200(OK) for a successful operation. 
-- Tests for the DELETE method **must not** be done with data residing on a production or live data store. 
 
-<!-- theme: info -->
-> Testing is a critical stage of the API development life cycle and the type of tests executed will depend on the complexity of the API, time, budget, etc. It is vital to conduct robust tests to reveal any inconsistencies or defects in the API before it is shipped to a production server or interfaced with other platforms.  
+* Test the DELETE request to certify it returns a 4xx error code if a DELETE
+  operation is executed against an invalid or non-existent resource
+* Test the DELETE request to confirm it returns a 200(OK) for a successful
+  operation
+* Tests for the DELETE method **must not** be done with data residing on a
+  production or live data store
+  
+  ---
+  **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)
+

articles/testing/variables-context.md

@@ -28,7 +28,6 @@ To accomplish this, we would capture/set the `$.ctx.userId` property to `output.
 
 The capture UI in the step editor makes it easy to set `$.ctx` values. You can use values from the step output or input, including headers, response bodies, etc.
 
-<!-- theme: info --> 
 > Multiple captures can be applied to the same step, to set multiple `$.ctx` values.
 
 ### With Scripting
@@ -91,11 +90,11 @@ $.ctx.get('myVariable');
 Where the braces (`{}`) are absent, and we are using the `get()` method for
 retrieving the context variable under the `myVariable` key.
 
-***
+---
+**Related Articles**
+- [Using Variables Overview](/testing/using-variables/overview)
+- [$$.env (Environment)](/testing/using-variables/environment)
+
+
 
-**Related**
 
-* [Environment Overview](../editor/environments.md)
-* [Environment Configuration](../editor/editor-configuration.md)
-* [Variables Overview](./variables-overview.md)
-* [Context Variables](./variables-context.md)

articles/testing/variables-environment.md

@@ -3,7 +3,7 @@
 <!--(FIXME - SHOW CLICKING THROUGH ENVIRONMENTS IN UI)-->
 
 > If you have not already done so, we recommend reviewing the
-[Environments](../editor/environments.md) article before continuing.
+[Environments](/platform/editor-basics/environments) article before continuing.
 
 Environment variables in Stoplight allow you to dynamically retrieve information
 in a scenario from the active environment. This makes it possible to
@@ -14,7 +14,7 @@ populate based on the current environment.
 
 ### With the Editor Configuration
 
-For information on managing project environments, please review the [environment](../editor/environments.md) article.
+For information on managing project environments, please review the [environment](/platform/editor-basics/editor-configuration) article.
 
 ### With Captures
 
@@ -24,7 +24,7 @@ Say you have a scenario step that sends an HTTP request to authenticate a new us
 
 > Environment variables set via captures are only added to the user's private
   variables, and are not sent to Stoplight. See the [Environment
-  section](../editor/environments.md) for more information.
+  section](/platform/editor-basics/environments) for more information.
 
 ### With Scripting
 
@@ -46,7 +46,7 @@ argument (`y`) to the environment under the string value of the first argument
 
 > Environment variables set via script are only added to the user's private
   variables, and are not sent to Stoplight. See the [Environment
-  section](../editor/environments.md) for more information.
+  section](/platform/editor-basics/environments) for more information.
 
 ## Using Environment Variables
 
@@ -84,10 +84,9 @@ Where the braces (`{}`) are absent, and we are using the `get()` method for
 retrieving the environment variable under the `myVariable` key.
 
 ***
+**Related Articles**
+- [Editor Configuration](/platform/editor-basics/editor-configuration)
+- [Environments](/platform/editor-basics/environments)
+- [Using Variables Overview](/testing/using-variables/overview)
+- [$.ctx(Context)](/testing/using-variables/context)
 
-**Related**
-
-* [Environment Overview](../editor/environments.md)
-* [Environment Configuration](../editor/editor-configuration.md)
-* [Variables Overview](./variables-overview.md)
-* [Context Variables](./variables-context.md)

articles/testing/variables-overview.md

@@ -3,7 +3,7 @@
 Variables in Stoplight provide a powerful and intuitive way to dynamically set, 
 update, and retrieve information at any step in a Scenario.
 
-Variables are stored in an [environment](../editor/environments.md). You can define one or more environments,
+Variables are stored in an [environment](/platform/editor-basics/environments). You can define one or more environments,
 each with their own variables. This makes it easy to quickly swap out sets of 
 variables during testing.
 
@@ -18,13 +18,12 @@ so that the host can quickly be changed to test multiple server locations (devel
 
 There are two scopes for variables, which affect how and when they can be used.
 
-* __Environment Variables__ - Environment variables are scoped to the project, and are shared amongst all steps in your test run. They are persisted between test runs, and are great for data that does not change often (hostnames, ports, etc). See [here](./variables-environment.md) for more information on how to use environment variables.
+* __Environment Variables__ - Environment variables are scoped to the project, and are shared amongst all steps in your test run. They are persisted between test runs, and are great for data that does not change often (hostnames, ports, etc). See [here](/testing/using-variables/environment) for more information on how to use environment variables.
 
-* __Context Variables__ - Context variables are scoped to the scenario, and are reset on every test run. They are useful to persist test and application state between scenario steps. Context variables are great for temporary information that is only relevant to the current test run. For example, you might store a newly created `userId` returned in your first step, to be used in the second step. This `userId` changes on every test run, which makes it a good context variable candidate. See [here](./variables-context.md) for more information on how to use context variables.
+* __Context Variables__ - Context variables are scoped to the scenario, and are reset on every test run. They are useful to persist test and application state between scenario steps. Context variables are great for temporary information that is only relevant to the current test run. For example, you might store a newly created `userId` returned in your first step, to be used in the second step. This `userId` changes on every test run, which makes it a good context variable candidate. See [here](/testing/using-variables/context) for more information on how to use context variables.
 
 ***
 
-**Related**
-
-* [Environment Variables](./variables-environment.md)
-* [Context Variables](./variables-context.md)
+**Related Articles**
+- [$$.env (Environment)](/testing/using-variables/environment)
+- [$.ctx(Context)](/testing/using-variables/context)