15 files changed, 79 insertions, 46 deletions
diff --git a/doc/ci/README.md b/doc/ci/README.md
index ec0ddfbea75..12404eddbe2 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -1,3 +1,7 @@
+---
+comments: false
+---
+
 # GitLab Continuous Integration (GitLab CI)
 
 ![Pipeline graph](img/cicd_pipeline_infograph.png)
diff --git a/doc/ci/docker/README.md b/doc/ci/docker/README.md
index 99669a9272a..b0e01d74f7e 100644
--- a/doc/ci/docker/README.md
+++ b/doc/ci/docker/README.md
@@ -1,3 +1,7 @@
+---
+comments: false
+---
+
 # Docker integration
 
 - [Using Docker Images](using_docker_images.md)
diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md
index b8f9988e3ef..7aa7de97c43 100644
--- a/doc/ci/enable_or_disable_ci.md
+++ b/doc/ci/enable_or_disable_ci.md
@@ -1,4 +1,4 @@
-## Enable or disable GitLab CI/CD
+# How to enable or disable GitLab CI/CD
 
 To effectively use GitLab CI/CD, you need a valid [`.gitlab-ci.yml`](yaml/README.md)
 file present at the root directory of your project and a
@@ -21,7 +21,7 @@ individually under each project's settings, or site-wide by modifying the
 settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations
 respectively.
 
-### Per-project user setting
+## Per-project user setting
 
 The setting to enable or disable GitLab CI/CD can be found under your project's
 **Settings > General > Permissions**. Choose one of "Disabled", "Only team members"
@@ -29,7 +29,7 @@ or "Everyone with access" and hit **Save changes** for the settings to take effe
 
 ![Sharing & Permissions settings](../user/project/settings/img/sharing_and_permissions_settings.png)
 
-### Site-wide admin setting
+## Site-wide admin setting
 
 You can disable GitLab CI/CD site-wide, by modifying the settings in `gitlab.yml`
 and `gitlab.rb` for source and Omnibus installations respectively.
diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md
index f094546c3bd..d05b4db953a 100644
--- a/doc/ci/examples/README.md
+++ b/doc/ci/examples/README.md
@@ -1,3 +1,7 @@
+---
+comments: false
+---
+
 # GitLab CI Examples
 
 A collection of `.gitlab-ci.yml` files is maintained at the [GitLab CI Yml project][gitlab-ci-templates].
diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md
index b9f0485290e..bed379b0254 100644
--- a/doc/ci/examples/deployment/composer-npm-deploy.md
+++ b/doc/ci/examples/deployment/composer-npm-deploy.md
@@ -1,4 +1,4 @@
-## Running Composer and NPM scripts with deployment via SCP
+# Running Composer and NPM scripts with deployment via SCP in GitLab CI/CD
 
 This guide covers the building dependencies of a PHP project while compiling assets via an NPM script.
 
@@ -39,13 +39,13 @@ In this particular case, the `npm deploy` script is a Gulp script that does the
 
 All these operations will put all files into a `build` folder, which is ready to be deployed to a live server.
 
-### How to transfer files to a live server?
+## How to transfer files to a live server
 
 You have multiple options: rsync, scp, sftp and so on. For now, we will use scp.
 
 To make this work, you need to add a GitLab Secret Variable (accessible on _gitlab.example/your-project-name/variables_). That variable will be called `STAGING_PRIVATE_KEY` and it's the  **private** ssh key of your server.
 
-#### Security tip
+### Security tip
 
 Create a user that has access **only** to the folder that needs to be updated!
 
@@ -69,7 +69,7 @@ In order, this means that:
 
 And this is basically all you need in the `before_script` section.
 
-## How to deploy things?
+## How to deploy things
 
 As we stated above, we need to deploy the `build` folder from the docker image to our server. To do so, we create a new job:
 
@@ -88,7 +88,7 @@ stage_deploy:
     - ssh -p22 server_user@server_host "rm -rf htdocs/wp-content/themes/_old"
 ```
 
-### What's going on here?
+Here's the breakdown:
 
 1. `only:dev` means that this build will run only when something is pushed to the `dev` branch. You can remove this block completely and have everything be ran on every push (but probably this is something you don't want)
 2. `ssh-add ...` we will add that private key you added on the web UI to the docker container
@@ -99,7 +99,7 @@ stage_deploy:
 
 What's the deal with the artifacts? We just tell GitLab CI to keep the `build` directory (later on, you can download that as needed).
 
-#### Why we do it this way?
+### Why we do it this way
 
 If you're using this only for stage server, you could do this in two steps:
 
@@ -112,7 +112,7 @@ The problem is that there will be a small period of time when you won't have the
 
 So we use so many steps because we want to make sure that at any given time we have a functional app in place.
 
-## Where to go next?
+## Where to go next
 
 Since this was a WordPress project, I gave real life code snippets. Some ideas you can pursuit:
 
diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md
index 73aebaf6d7f..0f7ed055e79 100644
--- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md
+++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md
@@ -1,10 +1,13 @@
-## Test and Deploy a python application
+# Test and Deploy a python application with GitLab CI/CD
+
 This example will guide you how to run tests in your Python application and deploy it automatically as Heroku application.
 
-You can checkout the example [source](https://gitlab.com/ayufan/python-getting-started) and check [CI status](https://gitlab.com/ayufan/python-getting-started/builds?scope=all).
+You can checkout the [example source](https://gitlab.com/ayufan/python-getting-started).
+
+## Configure project
 
-### Configure project
 This is what the `.gitlab-ci.yml` file looks like for this project:
+
 ```yaml
 test:
   script:
@@ -41,21 +44,25 @@ This project has three jobs:
 2. `staging` - used to automatically deploy staging environment every push to `master` branch
 3. `production` - used to automatically deploy production environmnet for every created tag
 
-### Store API keys
+## Store API keys
+
 You'll need to create two variables in `Project > Variables`:
 1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
 2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
 
 Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
 
-### Create Heroku application
+## Create Heroku application
+
 For each of your environments, you'll need to create a new Heroku application.
 You can do this through the [Dashboard](https://dashboard.heroku.com/).
 
-### Create runner
+## Create Runner
+
 First install [Docker Engine](https://docs.docker.com/installation/).
-To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner). 
+To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner).
 You can use public runners available on `gitlab.com`, but you can register your own:
+
 ```
 gitlab-ci-multi-runner register \
   --non-interactive \
diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
index 6fa64a67e82..10fd2616fab 100644
--- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
+++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md
@@ -1,10 +1,13 @@
-## Test and Deploy a ruby application
+# Test and Deploy a ruby application with GitLab CI/CD
+
 This example will guide you how to run tests in your Ruby on Rails application and deploy it automatically as Heroku application.
 
 You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://gitlab.com/ayufan/ruby-getting-started/builds?scope=all).
 
-### Configure project
+## Configure the project
+
 This is what the `.gitlab-ci.yml` file looks like for this project:
+
 ```yaml
 test:
   script:
@@ -36,23 +39,28 @@ This project has three jobs:
 2. `staging` - used to automatically deploy staging environment every push to `master` branch
 3. `production` - used to automatically deploy production environment for every created tag
 
-### Store API keys
-You'll need to create two variables in `Project > Variables`:
+## Store API keys
+
+You'll need to create two variables in your project's **Settings > CI/CD > Variables**:
+
 1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
 2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
 
 Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
 
-### Create Heroku application
+## Create Heroku application
+
 For each of your environments, you'll need to create a new Heroku application.
 You can do this through the [Dashboard](https://dashboard.heroku.com/).
 
-### Create runner
+## Create Runner
+
 First install [Docker Engine](https://docs.docker.com/installation/).
 To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner).
 You can use public runners available on `gitlab.com`, but you can register your own:
+
 ```
-gitlab-ci-multi-runner register \
+gitlab-runner register \
   --non-interactive \
   --url "https://gitlab.com/" \
   --registration-token "PROJECT_REGISTRATION_TOKEN" \
@@ -62,6 +70,6 @@ gitlab-ci-multi-runner register \
   --docker-postgres latest
 ```
 
-With the command above, you create a runner that uses [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses [postgres](https://hub.docker.com/r/_/postgres/) database.
+With the command above, you create a Runner that uses [ruby:2.2](https://hub.docker.com/r/_/ruby/) image and uses [postgres](https://hub.docker.com/r/_/postgres/) database.
 
 To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
diff --git a/doc/ci/examples/test-clojure-application.md b/doc/ci/examples/test-clojure-application.md
index 56b746ce025..3b1026d174f 100644
--- a/doc/ci/examples/test-clojure-application.md
+++ b/doc/ci/examples/test-clojure-application.md
@@ -1,10 +1,10 @@
-## Test a Clojure application
+# Test a Clojure application with GitLab CI/CD
 
 This example will guide you how to run tests in your Clojure application.
 
 You can checkout the example [source](https://gitlab.com/dzaporozhets/clojure-web-application) and check [CI status](https://gitlab.com/dzaporozhets/clojure-web-application/builds?scope=all).
 
-### Configure project
+## Configure the project
 
 This is what the `.gitlab-ci.yml` file looks like for this project:
 
@@ -23,13 +23,13 @@ before_script:
   - lein deps
   - lein migratus migrate
 
-test: 
-  script: 
+test:
+  script:
     - lein test
 ```
 
-In before script we install JRE and [Leiningen](http://leiningen.org/). 
-Sample project uses [migratus](https://github.com/yogthos/migratus) library to manage database migrations. 
+In before script we install JRE and [Leiningen](http://leiningen.org/).
+Sample project uses [migratus](https://github.com/yogthos/migratus) library to manage database migrations.
 So we added database migration as last step of `before_script` section
 
 You can use public runners available on `gitlab.com` for testing your application with such configuration.
diff --git a/doc/ci/examples/test-phoenix-application.md b/doc/ci/examples/test-phoenix-application.md
index 150698ca04b..f6c81b076bc 100644
--- a/doc/ci/examples/test-phoenix-application.md
+++ b/doc/ci/examples/test-phoenix-application.md
@@ -1,9 +1,9 @@
-## Test a Phoenix application
+# Test a Phoenix application with GitLab CI/CD
 
 This example demonstrates the integration of Gitlab CI with Phoenix, Elixir and
 Postgres.
 
-### Add `.gitlab-ci.yml` file to project
+## Add `.gitlab-ci.yml` to project
 
 The following `.gitlab-ci.yml` should be added in the root of your
 repository to trigger CI:
@@ -36,7 +36,7 @@ run your migrations.
 
 Finally, the test `script` will run your tests.
 
-### Update the Config Settings
+## Update the Config Settings
 
 In `config/test.exs`, update the database hostname:
 
@@ -45,12 +45,12 @@ config :my_app, MyApp.Repo,
   hostname: if(System.get_env("CI"), do: "postgres", else: "localhost"),
 ```
 
-### Add the Migrations Folder
+## Add the Migrations Folder
 
 If you do not have any migrations yet, you will need to create an empty
 `.gitkeep` file in `priv/repo/migrations`.
 
-### Sources
+## Sources
 
 - https://medium.com/@nahtnam/using-phoenix-on-gitlab-ci-5a51eec81142
 - https://davejlong.com/ci-with-phoenix-and-gitlab/
diff --git a/doc/ci/permissions/README.md b/doc/ci/permissions/README.md
index 42eb59f84c8..80d8e46f29c 100644
--- a/doc/ci/permissions/README.md
+++ b/doc/ci/permissions/README.md
@@ -1,3 +1 @@
-# Users Permissions
-
 This document was moved to [user/permissions.md](../../user/permissions.md#gitlab-ci).
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
index 2d56b2540ef..f621bf07251 100644
--- a/doc/ci/quick_start/README.md
+++ b/doc/ci/quick_start/README.md
@@ -1,4 +1,4 @@
-# Getting started with GitLab CI
+# Getting started with GitLab CI/CD
 
 >**Note:** Starting from version 8.0, GitLab [Continuous Integration][ci] (CI)
 is fully integrated into GitLab itself and is [enabled] by default on all
diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md
index 8b51d112a2c..df66810a838 100644
--- a/doc/ci/runners/README.md
+++ b/doc/ci/runners/README.md
@@ -1,4 +1,4 @@
-# Runners
+# Configuring GitLab Runners
 
 In GitLab CI, Runners run the code defined in [`.gitlab-ci.yml`](../yaml/README.md).
 They are isolated (virtual) machines that pick up jobs through the coordinator
diff --git a/doc/ci/services/README.md b/doc/ci/services/README.md
index 4b79461d55c..d94b472b768 100644
--- a/doc/ci/services/README.md
+++ b/doc/ci/services/README.md
@@ -1,4 +1,8 @@
-## GitLab CI Services
+---
+comments: false
+---
+
+# GitLab CI Services
 
 GitLab CI uses the `services` keyword to define what docker containers should
 be linked with your base image. Below is a list of examples you may use.
diff --git a/doc/ci/services/docker-services.md b/doc/ci/services/docker-services.md
index df36ebaf7d4..787c5e462e4 100644
--- a/doc/ci/services/docker-services.md
+++ b/doc/ci/services/docker-services.md
@@ -1,5 +1,9 @@
-## GitLab CI Services
+---
+comments: false
+---
 
-+ [Using MySQL](mysql.md)
-+ [Using PostgreSQL](postgres.md)
-+ [Using Redis](redis.md)
+# GitLab CI Services
+
+- [Using MySQL](mysql.md)
+- [Using PostgreSQL](postgres.md)
+- [Using Redis](redis.md)
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index 73568757aaa..b503b7c06fd 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -1,4 +1,4 @@
-# Variables
+# GitLab CI/CD Variables
 
 When receiving a job from GitLab CI, the [Runner] prepares the build environment.
 It starts by setting a list of **predefined variables** (environment variables)