Restructure some docs (cypress-io#2579)

* Update contributing guide about deleting docs

* Rename intelligent code completion to IDE integration / move troubleshooting into its own guide

* Fix a bunch of broken links

* Some other minor updates pulled over from other PR

* Update debugging guide with link to Troubleshooting

CONTRIBUTING.md

@@ -104,9 +104,19 @@ To add a page such as a new guide or API documentation:
 - Link to your new page in the [`sidebar.yml`](/source/_data/sidebar.yml).
 - Add translations for the sidebar link for each supported language (for English, this is located in [`en.yml`](/themes/cypress/languages/en.yml)).
 - Build the documentation site locally so that you can visually inspect your new page and the links to it.
-- Commit the new file using git - we auto-generate the doc to display within each supported language, this auto-generation depends on the file existing in git.
+- **REQUIRED**: Commit the new file using git - we auto-generate the doc to display within each supported language, this auto-generation depends on the file existing in git.
 - Submit a [pull request](#Pull-Requests) for your change.
 
+### Deleting Pages
+
+To delete a page:
+
+- Delete the page from the relevant directory under [`source`](/source).
+- Remove the link from the the [`sidebar.yml`](/source/_data/sidebar.yml).
+- Remove the translations for the sidebar link for each supported language (for English, this is located in [`en.yml`](/themes/cypress/languages/en.yml)).
+- **REQUIRED**: Commit the change using git - we auto-remove the doc within each supported language, this auto-generation depends on the file being deleted in git, the build will not work until this is commited.
+- Build the documentation site locally so that you can visually inspect and make sure it was properly deleted.
+
 #### A Worked Example
 
 Let's imagine that the Cypress team has just added a new command called `privateState` and you've picked up the task to document it.

source/_changelogs/3.4.0.md

@@ -24,7 +24,7 @@
 - Environment variables for Semaphore 2.0 are now captured when recording tests to the Dashboard. Fixes {% issue 4671 %}.
 - We now capture environment variables set from Concourse CI when recording tests to the Dashboard. Fixes {% issue 4376 %}.
 - We replaced capturing environment variables from SnapCI (which is no longer available) to instead capture ones set from GoCD when recording tests to the Dashboard. Fixes {% issue 2680 %}.
-- The {% url "JSON schema file" https://on.cypress.io/cypress.schema.json %} used for {% url "intelligent code completion" https://on.cypress.io/intelligent-code-completion#Configuration %} for the Cypress configuration file has been updated to match our documentation.
+- The {% url "JSON schema file" https://on.cypress.io/cypress.schema.json %} used for {% url "intelligent code completion" IDE-integration#Intelligent-Code-Completion %} for the Cypress configuration file has been updated to match our documentation.
 
 **Documentation Changes:**
 

source/_changelogs/4.0.0.md

@@ -48,7 +48,7 @@ Cypress 4.0.0 includes support for {% url "Mozilla Firefox" https://www.mozilla.
 - The browser icons in the Test Runner now display as images with the proper branding. Addresses {% issue 6188 %}.
 - We updated the styling of browser dropdown in the Test Runner to look more like a button. Addresses {% issue 6298 %}.
 - The timer in the Test Runner now always displays at a consistent length. Addresses {% issue 6168 %}.
-- You can print debug information about the memory & CPU usage of Cypress, which can be accessed by enabling the {% url "`cypress:server:util:process_profiler` debug stream" debugging#Log-memory-and-CPU-usage %}. Addresses {% issue 6169 %}.
+- You can print debug information about the memory & CPU usage of Cypress, which can be accessed by enabling the {% url "`cypress:server:util:process_profiler` debug stream" troubleshooting#Log-memory-and-CPU-usage %}. Addresses {% issue 6169 %}.
 - We added types for plugin events. Addresses {% issue 6322 %}.
 
 **Dependency Updates**

source/_data/sidebar.yml

@@ -36,7 +36,7 @@ guides:
     cross-browser-testing: cross-browser-testing.html
     web-security: web-security.html
   tooling:
-    intelligent-code-completion: intelligent-code-completion.html
+    IDE-integration: IDE-integration.html
     plugins-guide: plugins-guide.html
     reporters: reporters.html
     typescript-support: typescript-support.html
@@ -51,6 +51,7 @@ guides:
     error-messages: error-messages.html
     bundled-tools: bundled-tools.html
     trade-offs: trade-offs.html
+    troubleshooting: troubleshooting.html
     changelog: changelog.html
     migration-guide: migration-guide.html
     roadmap: roadmap.html

source/guides/core-concepts/introduction-to-cypress.md

@@ -805,7 +805,8 @@ All DOM based commands automatically wait for their elements to exist in the DOM
 You don't need to write {% url "`.should('exist')`" should %} after a DOM based command, unless you chain extra `.should()` assertions.
 {% endnote %}
 
-{% note danger "Negative DOM assertions" %}
+#### Negative DOM assertions
+
 If you chain any `.should()` command, the default `.should('exist')` is not asserted. This does not matter for most *positive* assertions, such as `.should('have.class')`, because those imply existence in the first place, but if you chain *negative* assertions ,such as `.should('not.have.class')`, they will pass even if the DOM element doesn't exist:
 
 ```js
@@ -822,9 +823,6 @@ cy.get('.does-not-exist').should(($element) => {
 })
 ```
 
-There's an {% url 'open discussion' https://github.com/cypress-io/cypress/issues/205 %} about this behavior.
-{% endnote %}
-
 These rules are pretty intuitive, and most commands give you the flexibility to override or bypass the default ways they can fail, typically by passing a `{force: true}` option.
 
 ### Example #1: Existence and Actionability

source/guides/core-concepts/test-runner.md

@@ -39,15 +39,15 @@ Each command, assertion, or error, when clicked on, displays extra information i
 
 For certain commands like {% url `cy.route()` route %}, {% url `cy.stub()` stub %}, and {% url `cy.spy()` spy %}, an extra instrument panel is displayed above the test to give more information about the state of your tests.
 
-## Routes:
+## Routes
 
 {% imgTag /img/guides/instrument-panel-routes.png "Routes Instrument Panel" %}
 
-## Stubs:
+## Stubs
 
 {% imgTag /img/guides/instrument-panel-stubs.png "Stubs Instrument Panel" %}
 
-## Spies:
+## Spies
 
 {% imgTag /img/guides/instrument-panel-spies.png "Spies Instrument Panel" %}
 

source/guides/dashboard/projects.md

@@ -73,7 +73,7 @@ If you're using source control, we recommend that you check your `cypress.json`,
 export CYPRESS_PROJECT_ID={projectId}
 ```
 
-## Record key {% fa fa-key %}
+## Record key
 
 The record key is used to authenticate that your project is *allowed* to record tests to the Dashboard Service. As long as your record key stays *private*, nobody will be able to record test runs for your project - even if they have your `projectId`.
 

source/guides/getting-started/writing-your-first-test.md

@@ -219,7 +219,7 @@ Now we can assert something about this new page!
 {% video local /img/snippets/first-test-click-30fps.mp4 %}
 
 {% note info %}
-{% fa fa-magic %} You can see IntelliSense in your spec files by adding a single special comment line. Read about {% url 'Intelligent Code Completion' intelligent-code-completion#Triple-slash-directives %}.
+{% fa fa-magic %} You can see IntelliSense in your spec files by adding a single special comment line. Read about {% url 'Intelligent Code Completion' IDE-integration#Triple-slash-directives %}.
 {% endnote %}
 
 ## {% fa fa-check-square-o %} Step 4: Make an assertion
@@ -229,8 +229,8 @@ Let's make an assertion about something on the new page we clicked into. Perhaps
 Here's what that looks like:
 
 ```js
-describe('My First Test', function() {
-  it('clicking "type" navigates to a new url', function() {
+describe('My First Test', () => {
+  it('clicking "type" navigates to a new url', () => {
     cy.visit('https://example.cypress.io')
 
     cy.contains('type').click()
@@ -250,8 +250,8 @@ We can continue the interactions and assertions in this test by adding another c
 We can use {% url "`cy.get()`" get %} to select an element based on a CSS class. Then we can use the {% url "`.type()`" type %} command to enter text into the selected input. Finally, we can verify that the value of the input reflects the text that was typed with another {% url "`.should()`" should %}.
 
 ```js
-describe('My First Test', function() {
-  it('Gets, types and asserts', function() {
+describe('My First Test', () => {
+  it('Gets, types and asserts', () => {
     cy.visit('https://example.cypress.io')
 
     cy.contains('type').click()
@@ -431,7 +431,7 @@ Now Cypress provides us a UI (similar to debugger) to step forward through each
 
 {% imgTag /img/guides/first-test-paused.png "Test Runner shows label saying 'Paused' with Command Log showing 'Pause'" %}
 
-## In action
+### In action
 
 {% video local /img/snippets/first-test-debugging-30fps.mp4 %}
 
@@ -496,7 +496,7 @@ describe('My First Test', function() {
 # Next steps
 
 - Start {% url 'testing your app' testing-your-app %}.
-- Set up {% url 'intelligent code completion' intelligent-code-completion %} for Cypress commands and assertions.
+- Set up {% url 'intelligent code completion' IDE-integration#Intelligent-Code-Completion %} for Cypress commands and assertions.
 - Search Cypress's documentation to quickly find what you need.
 
 {% imgTag /img/guides/search-box.png "Use the search box to find relevant documentation" %}

source/guides/guides/command-line.md

@@ -115,7 +115,7 @@ You can also choose a browser by supplying a path:
 cypress run --browser /usr/bin/chromium
 ```
 
-{% url "Having trouble with browser detection? Check out the debugging guide" debugging#Launching-browsers %}
+{% url "Having trouble with browser detection? Check out our troubleshooting guide" troubleshooting#Launching-browsers %}
 
 ### `cypress run --ci-build-id <id>`
 
@@ -371,7 +371,7 @@ If found, the specified browser will be added to the list of available browsers
 
 Currently, only browsers in the Chrome family are supported (including the new Chromium-based Microsoft Edge and Brave).
 
-{% url "Having trouble launching a browser? Check out the debugging guide" debugging#Launching-browsers %}
+{% url "Having trouble launching a browser? Check out our troubleshooting guide" troubleshooting#Launching-browsers %}
 
 ### `cypress open --config <config>`