Merge branch 'docs/no-comments-ee' into 'master'

Exclude comments from specific docs

See merge request gitlab-org/gitlab-ee!3248

doc/README.md

 ---
 toc: false
+comments: false
 ---
 
 # GitLab Documentation

doc/administration/auth/README.md

+---
+comments: false
+---
+
 # Authentication and Authorization
 
 GitLab integrates with the following external authentication and authorization

doc/ci/README.md

+---
+comments: false
+---
+
 # GitLab Continuous Integration (GitLab CI)
 
 ![Pipeline graph](img/cicd_pipeline_infograph.png)

doc/ci/docker/README.md

+---
+comments: false
+---
+
 # Docker integration
 
 - [Using Docker Images](using_docker_images.md)

doc/ci/enable_or_disable_ci.md

-## 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.

doc/ci/examples/README.md

+---
+comments: false
+---
+
 # GitLab CI Examples
 
 A collection of `.gitlab-ci.yml` files is maintained at the [GitLab CI Yml project][gitlab-ci-templates].

doc/ci/examples/deployment/composer-npm-deploy.md

-## 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:
 

doc/ci/examples/test-and-deploy-python-application-to-heroku.md

-## 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 \

doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md

-## 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.

doc/ci/examples/test-clojure-application.md

-## 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.

doc/ci/examples/test-phoenix-application.md

-## 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/

doc/ci/permissions/README.md

-# Users Permissions
-
 This document was moved to [user/permissions.md](../../user/permissions.md#gitlab-ci).

doc/ci/quick_start/README.md

-# 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

doc/ci/runners/README.md

-# 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

doc/ci/services/README.md

-## 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.

doc/ci/services/docker-services.md

-## 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)

doc/ci/variables/README.md

-# 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)

doc/development/README.md

+---
+comments: false
+---
+
 # GitLab development guides
 
 ## Get started!

doc/development/testing_guide/testing_rake_tasks.md

-## Testing Rake tasks
+# Testing Rake tasks
 
 To make testing Rake tasks a little easier, there is a helper that can be included
 in lieu of the standard Spec helper. Instead of `require 'spec_helper'`, use

doc/development/ux_guide/users.md

-## UX Personas
+# UX Personas
+
 * [Nazim Ramesh](#nazim-ramesh)
     - Small to medium size organisations using GitLab CE
 * [James Mackey](#james-mackey)
@@ -7,16 +8,16 @@
 * [Karolina Plaskaty](#karolina-plaskaty)
     - Using GitLab.com for personal/hobby projects
     - Would like to use GitLab at work
-    - Working for a medium to large size organisation  
+    - Working for a medium to large size organisation
 
-<hr>
+---
 
-### Nazim Ramesh
+## Nazim Ramesh
 - Small to medium size organisations using GitLab CE
 
 <img src="img/nazim-ramesh.png" width="300px">
 
-#### Demographics 
+### Demographics
 
 - **Age**<br>32 years old
 - **Location**<br>Germany
@@ -26,7 +27,7 @@
 - **Frequently used programming languages**<br>JavaScript, SQL, PHP
 - **Hobbies / interests**<br>Functional programming, open source, gaming, web development and web security.
 
-#### Motivations
+### Motivations
 Nazim works for a software development company which currently hires around 80 people. When Nazim first joined the company, the engineering team were using Subversion (SVN) as their primary form of source control. However, Nazim felt SVN was not flexible enough to work with many feature branches and noticed that developers with less experience of source control struggled with the central-repository nature of SVN. Armed with a wishlist of features, Nazim began comparing source control tools. A search for “self-hosted Git server repository management” returned GitLab. In his own words, Nazim explains why he wanted the engineering team to start using GitLab:
 
 >
@@ -39,48 +40,48 @@ In his role as a full-stack web developer, Nazim could recommend products that h
 “The biggest challenge...why should we change anything at all from the status quo? We needed to switch from SVN to Git. They knew they needed to learn Git and a Git workflow...using Git was scary to my colleagues...they thought it was more complex than SVN to use.”
 >
 
-Undeterred, Nazim decided to migrate a couple of projects across to GitLab. 
+Undeterred, Nazim decided to migrate a couple of projects across to GitLab.
 
 >
 “Old SVN users couldn’t see the benefits of Git at first. It took a month or two to convince them.”
 >
 
-Slowly, by showing his colleagues how easy it was to use Git, the majority of the team’s projects were migrated to GitLab. 
+Slowly, by showing his colleagues how easy it was to use Git, the majority of the team’s projects were migrated to GitLab.
 
-The engineering team have been using GitLab CE for around 2 years now. Nazim credits himself as being entirely responsible for his company’s decision to move to GitLab. 
+The engineering team have been using GitLab CE for around 2 years now. Nazim credits himself as being entirely responsible for his company’s decision to move to GitLab.
 
-#### Frustrations
-##### Adoption to GitLab has been slow
+### Frustrations
+#### Adoption to GitLab has been slow
 Not only has the engineering team had to get to grips with Git, they’ve also had to adapt to using GitLab. Due to lack of training and existing skills in other tools, the full feature set of GitLab CE is not being utilised. Nazim sold GitLab to his manager as an ‘all in one’ tool which would replace multiple tools used within the company, thus saving costs. Nazim hasn’t had the time to integrate the legacy tools to GitLab and he’s struggling to convince his peers to change their habits.
 
-##### Missing Features
+#### Missing Features
 Nazim’s company want GitLab to be able to do everything. There isn’t a large budget for software, so they’re selective about what tools are implemented. It needs to add real value to the company. In order for GitLab to be widely adopted and to meet the requirements of different roles within the company, it needs a host of features. When an individual within Nazim’s company wants to know if GitLab has a specific feature or does a particular thing, Nazim is the person to ask. He becomes the point of contact to investigate, build or sometimes just raise the feature request. Nazim gets frustrated when GitLab isn’t able to do what he or his colleagues need it to do.
 
-##### Regressions and bugs
+#### Regressions and bugs
 Nazim often has to calm down his colleagues, when a release contains regressions or new bugs. As he puts it “every new version adds something awesome, but breaks something”. He feels that “old issues for "minor" annoyances get quickly buried in the mass of open issues and linger for a very long time. More generally, I have the feeling that GitLab focus on adding new functionalities, but overlook a bunch of annoying minor regressions or introduced bugs.” Due to limited resource and expertise within the team, not only is it difficult to remain up-to-date with the frequent release cycle, it’s also counterproductive to fix workflows every month.
 
-##### Uses too much RAM and CPU
+#### Uses too much RAM and CPU
 >
 “Memory usages mean that if we host it from a cloud based host like AWS, we spend almost as much on the instance as what we would pay GitHub”
 >
 
-##### UI/UX
+#### UI/UX
 GitLab’s interface initially attracted Nazim when he was comparing version control software. He thought it would help his less technical colleagues to adapt to using Git and perhaps, GitLab could be rolled out to other areas of the business, beyond engineering. However, using GitLab’s interface daily has left him frustrated at the lack of personalisation / control over his user experience. He’s also regularly lost in a maze of navigation. Whilst he acknowledges that GitLab listens to its users and that the interface is improving, he becomes annoyed when the changes are too progressive. “Too frequent UI changes. Most of them tend to turn out great after a few cycles of fixes, but the frequency is still far too high for me to feel comfortable to always stay on the current release.”
 
-#### Goals 
+### Goals
 * To convince his colleagues to fully adopt GitLab CE, thus improving workflow and collaboration.
 * To use a feature rich version control platform that covers all stages of the development lifecycle, in order to reduce dependencies on other tools.
 * To use an intuitive and stable product, so he can spend more time on his core job responsibilities and less time bug-fixing, guiding colleagues, etc.
 
-<hr>
+---
 
-### James Mackey
+## James Mackey
 - Medium to large size organisations using CE or EE
 - Small organisations using EE
 
 <img src="img/james-mackey.png" width="300px">
 
-#### Demographics
+### Demographics
 
 - **Age**<br>36 years old
 - **Location**<br>US
@@ -90,7 +91,7 @@ GitLab’s interface initially attracted Nazim when he was comparing version con
 - **Frequently used programming languages**<br>JavaScript, SQL, Node.js, Java, PHP, Python
 - **Hobbies / interests**<br>DevOps, open source, web development, science, automation and electronics.
 
-#### Motivations
+### Motivations
 James works for a research company which currently hires around 800 staff. He began using GitLab.com back in 2013 for his own open source, hobby projects and loved “the simplicity of installation, administration and use”. After using GitLab for over a year, he began to wonder about using it at work. James explains:
 
 >
@@ -99,7 +100,7 @@ James works for a research company which currently hires around 800 staff. He be
 
 James and his colleagues also reviewed competitor products including GitHub Enterprise, but they found it “less innovative and with considerable costs...GitLab had the features we wanted at a much lower cost per head than GitHub”.
 
-The company James works for provides employees with a discretionary budget to spend how they want on software, so James and his team decided to upgrade to EE. 
+The company James works for provides employees with a discretionary budget to spend how they want on software, so James and his team decided to upgrade to EE.
 
 James feels partially responsible for his organisation’s decision to start using GitLab.
 
@@ -107,33 +108,33 @@ James feels partially responsible for his organisation’s decision to start usi
 “It's still up to the teams themselves [to decide] which tools to use. We just had a great experience moving our daily development to GitLab, so other teams have followed the path or are thinking about switching.”
 >
 
-#### Frustrations
-##### Third Party Integration
+### Frustrations
+#### Third Party Integration
 Some of GitLab EE’s features are too basic, in particular, issues boards which do not have the level of reporting that James and his team need. Subsequently, they still need to use GitLab EE in conjunction with other tools, such as JIRA. Whilst James feels it isn’t essential for GitLab to meet all his needs (his company are happy for him to use, and pay for, multiple tools), he sometimes isn’t sure what is/isn’t possible with plugins and what level of custom development he and his team will need to do.
 
-##### UX/UI
+#### UX/UI
 James and his team use CI quite heavily for several projects. Whilst they’ve welcomed improvements to the builds and pipelines interface, they still have some difficulty following build process on the different tabs under Pipelines. Some confusion has arisen from not knowing where to find different pieces of information or how to get to the next stages logs from the current stage’s log output screen. They feel more intuitive linking and flow may alleviate the problem. Generally, they feel GitLab’s navigation needs to reviewed and optimised.
 
-##### Permissions
+#### Permissions
 >
 “There is no granular control over user or group permissions. The permissions for a project are too tightly coupled to the permissions for Gitlab CI/build pipelines.”
 >
 
-#### Goals 
+### Goals
 * To be able to integrate third party tools easily with GitLab EE and to create custom integrations and patches where needed.
 * To use GitLab EE primarily for code hosting, merge requests, continuous integration and issue management. James and his team want to be able to understand and use these particular features easily.
 * To able to share one instance of GitLab EE with multiple teams across the business. Advanced user management, the ability to separate permissions on different parts of the source code, etc are important to James.
 
-<hr>
+---
 
-### Karolina Plaskaty
+## Karolina Plaskaty
 - Using GitLab.com for personal/hobby projects
 - Would like to use GitLab at work
-- Working for a medium to large size organisation   
+- Working for a medium to large size organisation
 
 <img src="img/karolina-plaskaty.png" width="300px">
 
-#### Demographics
+### Demographics
 
 - **Age**<br>26 years old
 - **Location**<br>UK
@@ -143,22 +144,22 @@ James and his team use CI quite heavily for several projects. Whilst they’ve w
 - **Frequently used programming languages**<br>JavaScript and SQL
 - **Hobbies / interests**<br>Web development, mobile development, UX, open source, gaming and travel.
 
-#### Motivations
+### Motivations
 Karolina has been using GitLab.com for around a year. She roughly spends 8 hours every week programming, of that, 2 hours is spent contributing to open source projects. Karolina contributes to open source projects to gain programming experience and to give back to the community. She likes GitLab.com for its free private repositories and range of features which provide her with everything she needs for her personal projects. Karolina is also a massive fan of GitLab’s values and the fact that it isn’t a “behemoth of a company”.  She explains that “displaying every single thing (doc, culture, assumptions, development...) in the open gives me greater confidence to choose Gitlab personally and to recommend it at work.”  She’s also an avid reader of GitLab’s blog.
 
 Karolina works for a software development company which currently hires around 500 people. Karolina would love to use GitLab at work but the company has used GitHub Enterprise for a number of years. She describes management at her company as “old fashioned” and explains that it’s “less of a technical issue and more of a cultural issue” to convince upper management to move to GitLab. Karolina is also relatively new to the company so she’s apprehensive about pushing too hard to change version control platforms.
 
-#### Frustrations
-##### Unable to use GitLab at work
+### Frustrations
+#### Unable to use GitLab at work
 Karolina wants to use GitLab at work but isn’t sure how to approach the subject with management. In her current role, she doesn’t feel that she has the authority to request GitLab.
 
-##### Performance
+#### Performance
 GitLab.com is frequently slow and unavailable. Karolina has also heard that GitLab is a “memory hog”  which has deterred her from running GitLab on her own machine for just hobby / personal projects.
 
-##### UX/UI
+#### UX/UI
 Karolina has an interest in UX and therefore has strong opinions about how GitLab should look and feel. She feels the interface is cluttered, “it has too many links/buttons” and the navigation “feels a bit weird sometimes. I get lost if I don’t pay attention.” As Karolina also enjoys contributing to open-source projects, it’s important to her that GitLab is well designed for public repositories, she doesn’t feel that GitLab currently achieves this.
 
-#### Goals 
+### Goals
 * To develop her programming experience and to learn from other developers.
 * To contribute to both her own and other open source projects.
-* To use a fast and intuitive version control platform.
\ No newline at end of file
+* To use a fast and intuitive version control platform.

doc/gitlab-basics/README.md

+---
+comments: false
+---
+
 # GitLab basics
 
 Step-by-step guides on the basics of working with Git and GitLab.

doc/install/README.md

+---
+comments: false
+---
+
 # Installation
 
 GitLab can be installed via various ways. Check the [installation methods][methods]

doc/install/relative_url.md

-## Install GitLab under a relative URL
+# Install GitLab under a relative URL
 
-_**Note:**
+NOTE: **Note:**
 This document describes how to run GitLab under a relative URL for installations
 from source. If you are using an Omnibus package,
 [the steps are different][omnibus-rel]. Use this guide along with the
 [installation guide](installation.md) if you are installing GitLab for the
-first time._
+first time.
 
 ---
 
@@ -33,7 +33,7 @@ serve GitLab under a relative URL is:
 
 After all the changes you need to recompile the assets and [restart GitLab].
 
-### Relative URL requirements
+## Relative URL requirements
 
 If you configure GitLab with a relative URL, the assets (JavaScript, CSS, fonts,
 images, etc.) will need to be recompiled, which is a task which consumes a lot
@@ -43,11 +43,11 @@ least 2GB of RAM available on your system, while we recommend 4GB RAM, and 4 or
 
 See the [requirements](requirements.md) document for more information.
 
-### Enable relative URL in GitLab
+## Enable relative URL in GitLab
 
-_**Note:**
+NOTE: **Note:**
 Do not make any changes to your web server configuration file regarding
-relative URL. The relative URL support is implemented by GitLab Workhorse._
+relative URL. The relative URL support is implemented by GitLab Workhorse.
 
 ---
 
@@ -115,7 +115,7 @@ Make sure to follow all steps below:
 
 1. [Restart GitLab][] for the changes to take effect.
 
-### Disable relative URL in GitLab
+## Disable relative URL in GitLab
 
 To disable the relative URL:
 

doc/integration/README.md

+---
+comments: false
+---
+
 # GitLab Integration
 
 GitLab integrates with multiple third-party services to allow external issue

doc/intro/README.md

+---
+comments: false
+---
+
 # Get started with GitLab
 
 ## Organize

doc/legal/README.md

+---
+comments: false
+---
+
 # Legal
 
 - [Corporate contributor license agreement](corporate_contributor_license_agreement.md)

doc/migrate_ci_to_ce/README.md

@@ -372,8 +372,10 @@ CREATE TABLE
 ```
 
 To fix that you need to apply this SQL statement before doing final backup:
-```
-# Omnibus
+
+```sql
+## Omnibus GitLab
+
 gitlab-ci-rails dbconsole <<EOF
 -- ALTER TABLES - DROP DEFAULTS
 ALTER TABLE ONLY ci_application_settings ALTER COLUMN id DROP DEFAULT;
@@ -427,7 +429,8 @@ ALTER TABLE ONLY ci_variables ALTER COLUMN id SET DEFAULT nextval('ci_variables_
 ALTER TABLE ONLY ci_web_hooks ALTER COLUMN id SET DEFAULT nextval('ci_web_hooks_id_seq'::regclass);
 EOF
 
-# Source
+## Source installations
+
 cd /home/gitlab_ci/gitlab-ci
 sudo -u gitlab_ci -H bundle exec rails dbconsole production <<EOF
 ... COPY SQL STATEMENTS FROM ABOVE ...

doc/raketasks/README.md

+---
+comments: false
+---
+
 # Rake tasks
 
 - [Backup restore](backup_restore.md)

doc/security/README.md

+---
+comments: false
+---
+
 # Security
 
 - [Password length limits](password_length_limits.md)

doc/ssh/README.md

-# SSH
+# GitLab and SSH keys
 
 Git is a distributed version control system, which means you can work locally
 but you can also share or "push" your changes to other servers.
@@ -114,7 +114,7 @@ custom name continue onto the next step.
 
     If you manually copied your public SSH key make sure you copied the entire
     key starting with `ssh-rsa` and ending with your email.
-    
+
 1. Optionally you can test your setup by running `ssh -T git@example.com`
    (replacing `example.com` with your GitLab domain) and verifying that you
    receive a `Welcome to GitLab` message.
@@ -172,7 +172,7 @@ dummy user account.
 If you are a project master or owner, you can add a deploy key in the
 project settings under the section 'Repository'. Specify a title for the new
 deploy key and paste a public SSH key. After this, the machine that uses
-the corresponding private SSH key has read-only or read-write (if enabled) 
+the corresponding private SSH key has read-only or read-write (if enabled)
 access to the project.
 
 You can't add the same deploy key twice using the form.
@@ -232,7 +232,7 @@ something is wrong with your SSH setup.
 
 - Ensure that you generated your SSH key pair correctly and added the public SSH
   key to your GitLab profile
-- Try manually registering your private SSH key using `ssh-agent` as documented 
+- Try manually registering your private SSH key using `ssh-agent` as documented
   earlier in this document
 - Try to debug the connection by running `ssh -Tv git@example.com`
   (replacing `example.com` with your GitLab domain)

doc/university/README.md

+---
+comments: false
+---
+
 # GitLab University
 
 GitLab University is the best place to learn about **Version Control with Git and GitLab**.

doc/university/bookclub/booklist.md

+---
+comments: false
+---
+
 # Books
 
 List of books and resources, that may be worth reading.

doc/university/bookclub/index.md

+---
+comments: false
+---
+
 # The GitLab Book Club
 
 The Book Club is a casual meet-up to read and discuss books we like.

doc/university/glossary/README.md

-## What is the Glossary
+---
+comments: false
+---
+
+# What is the Glossary
 
 This contains a simplified list and definitions of some of the terms that you will encounter in your day to day activities when working with GitLab.
 Please add any terms that you discover that you think would be useful for others.

doc/university/high-availability/aws/README.md

+---
+comments: false
+---
+
 
 # High Availability on AWS
 

doc/university/process/README.md

+---
+comments: false
+---
+
 ---
 title: University | Process
 ---
 
-## Suggesting improvements
+# Suggesting improvements
 
 If you would like to teach a class or participate or help in any way please
 submit a merge request and assign it to [Job](https://gitlab.com/u/JobV).

doc/university/support/README.md

+---
+comments: false
+---
 
-## Support Boot Camp
+
+# Support Boot Camp
 
 **Goal:** Prepare new Service Engineers at GitLab
 

doc/university/training/end-user/README.md

+---
+comments: false
+---
+
 
 # Training
 

doc/university/training/gitlab_flow.md

+---
+comments: false
+---
+
 # GitLab Flow
 
 - A simplified branching strategy

doc/university/training/index.md

+---
+comments: false
+---
+
 # GitLab Training Material
 
 All GitLab training material is stored in markdown format. Slides are

doc/university/training/topics/additional_resources.md

-## Additional Resources
+---
+comments: false
+---
+
+# Additional Resources
 
 1. GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/)
 2. GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis)

doc/university/training/topics/agile_git.md

+---
+comments: false
+---
+
 # Agile and Git
 
 ----------

doc/university/training/topics/bisect.md

+---
+comments: false
+---
+
 # Bisect	  	
 
 ----------

doc/university/training/topics/cherry_picking.md

+---
+comments: false
+---
+
 # Cherry Pick
 
 ----------

doc/university/training/topics/env_setup.md

+---
+comments: false
+---
+
 # Configure your environment
 
 ----------

doc/university/training/topics/explore_gitlab.md

+---
+comments: false
+---
+
 # Explore GitLab projects
 
 ----------

doc/university/training/topics/feature_branching.md

+---
+comments: false
+---
+
 # Feature branching
 
 ----------

doc/university/training/topics/getting_started.md

+---
+comments: false
+---
+
 # Getting Started
 
 ----------

doc/university/training/topics/git_add.md

+---
+comments: false
+---
+
 # Git Add
 
 ----------

doc/university/training/topics/git_intro.md

+---
+comments: false
+---
+
 # Git introduction
 
 ----------

doc/university/training/topics/git_log.md

+---
+comments: false
+---
+
 # Git Log
 
 ----------

doc/university/training/topics/gitlab_flow.md

+---
+comments: false
+---
+
 # GitLab Flow
 
 ----------

doc/university/training/topics/merge_conflicts.md

+---
+comments: false
+---
+
 # Merge conflicts
 
 ----------

doc/university/training/topics/merge_requests.md

+---
+comments: false
+---
+
 # Merge requests
 
 ----------

doc/university/training/topics/rollback_commits.md

+---
+comments: false
+---
+
 # Rollback Commits
 
 ----------

doc/university/training/topics/stash.md

+---
+comments: false
+---
+
 # Git Stash
 
 ----------

doc/university/training/topics/subtree.md

-## Subtree
+---
+comments: false
+---
 
-----------
-
-## Subtree
+# Subtree
 
 * Used when there are nested repositories.
 * Not recommended when the amount of dependencies is too large

doc/university/training/topics/tags.md

+---
+comments: false
+---
+
 # Tags
 
 ----------

doc/university/training/topics/unstage.md

+---
+comments: false
+---
+
 # Unstage
 
 ----------

doc/university/training/user_training.md

+---
+comments: false
+---
+
 # GitLab Git Workshop
 
 ---

doc/update/10.0-to-10.1.md

+---
+comments: false
+---
+
 # From 10.0 to 10.1
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/2.6-to-3.0.md

+---
+comments: false
+---
+
 # From 2.6 to 3.0
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/2.6-to-3.0.md) for the most up to date instructions.*
 

doc/update/2.9-to-3.0.md

+---
+comments: false
+---
+
 # From 2.9 to 3.0
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/2.9-to-3.0.md) for the most up to date instructions.*
 

doc/update/3.0-to-3.1.md

+---
+comments: false
+---
+
 # From 3.0 to 3.1
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/3.0-to-3.1.md) for the most up to date instructions.*
 

doc/update/3.1-to-4.0.md

+---
+comments: false
+---
+
 # From 3.1 to 4.0
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/3.1-to-4.0.md) for the most up to date instructions.*
 

doc/update/4.0-to-4.1.md

+---
+comments: false
+---
+
 # From 4.0 to 4.1
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/4.0-to-4.1.md) for the most up to date instructions.*
 

doc/update/4.1-to-4.2.md

+---
+comments: false
+---
+
 # From 4.1 to 4.2
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/4.1-to-4.2.md) for the most up to date instructions.*
 

doc/update/4.2-to-5.0.md

+---
+comments: false
+---
+
 # From 4.2 to 5.0
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/4.2-to-5.0.md) for the most up to date instructions.*
 

doc/update/5.0-to-5.1.md

+---
+comments: false
+---
+
 # From 5.0 to 5.1
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.0-to-5.1.md) for the most up to date instructions.*
 

doc/update/5.1-to-5.2.md

+---
+comments: false
+---
+
 # From 5.1 to 5.2
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.1-to-5.2.md) for the most up to date instructions.*
 

doc/update/5.1-to-5.4.md

+---
+comments: false
+---
+
 # From 5.1 to 5.4
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.1-to-5.4.md) for the most up to date instructions.*
 

doc/update/5.1-to-6.0.md

+---
+comments: false
+---
+
 # From 5.1 to 6.0
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.1-to-6.0.md) for the most up to date instructions.*
 

doc/update/5.2-to-5.3.md

+---
+comments: false
+---
+
 # From 5.2 to 5.3
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.2-to-5.3.md) for the most up to date instructions.*
 

doc/update/5.3-to-5.4.md

+---
+comments: false
+---
+
 # From 5.3 to 5.4
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.3-to-5.4.md) for the most up to date instructions.*
 

doc/update/5.4-to-6.0.md

+---
+comments: false
+---
+
 # From 5.4 to 6.0
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.4-to-6.0.md) for the most up to date instructions.*
 

doc/update/6.0-to-6.1.md

+---
+comments: false
+---
+
 # From 6.0 to 6.1
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.0-to-6.1.md) for the most up to date instructions.*
 

doc/update/6.1-to-6.2.md

+---
+comments: false
+---
+
 # From 6.1 to 6.2
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.1-to-6.2.md) for the most up to date instructions.*
 

doc/update/6.2-to-6.3.md

+---
+comments: false
+---
+
 # From 6.2 to 6.3
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.2-to-6.3.md) for the most up to date instructions.*
 

doc/update/6.3-to-6.4.md

+---
+comments: false
+---
+
 # From 6.3 to 6.4
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.3-to-6.4.md) for the most up to date instructions.*
 

doc/update/6.4-to-6.5.md

+---
+comments: false
+---
+
 # From 6.4 to 6.5
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.4-to-6.5.md) for the most up to date instructions.*
 

doc/update/6.5-to-6.6.md

+---
+comments: false
+---
+
 # From 6.5 to 6.6
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.5-to-6.6.md) for the most up to date instructions.*
 

doc/update/6.6-to-6.7.md

+---
+comments: false
+---
+
 # From 6.6 to 6.7
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.6-to-6.7.md) for the most up to date instructions.*
 

doc/update/6.7-to-6.8.md

+---
+comments: false
+---
+
 # From 6.7 to 6.8
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.7-to-6.8.md) for the most up to date instructions.*
 

doc/update/6.8-to-6.9.md

+---
+comments: false
+---
+
 # From 6.8 to 6.9
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.8-to-6.9.md) for the most up to date instructions.*
 

doc/update/6.9-to-7.0.md

+---
+comments: false
+---
+
 # From 6.9 to 7.0
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.9-to-7.0.md) for the most up to date instructions.*
 

doc/update/6.x-or-7.x-to-7.14.md

+---
+comments: false
+---
+
 # From 6.x or 7.x to 7.14
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.x-or-7.x-to-7.14.md) for the most up to date instructions.*
 

doc/update/7.0-to-7.1.md

+---
+comments: false
+---
+
 # From 7.0 to 7.1
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.0-to-7.1.md) for the most up to date instructions.*
 

doc/update/7.1-to-7.2.md

+---
+comments: false
+---
+
 # From 7.1 to 7.2
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.1-to-7.2.md) for the most up to date instructions.*
 

doc/update/7.10-to-7.11.md

+---
+comments: false
+---
+
 # From 7.10 to 7.11
 
 ### 0. Stop server

doc/update/7.11-to-7.12.md

+---
+comments: false
+---
+
 # From 7.11 to 7.12
 
 ### 0. Double-check your Git version

doc/update/7.12-to-7.13.md

+---
+comments: false
+---
+
 # From 7.12 to 7.13
 
 ### 0. Double-check your Git version

doc/update/7.13-to-7.14.md

+---
+comments: false
+---
+
 # From 7.13 to 7.14
 
 ### 0. Double-check your Git version

doc/update/7.14-to-8.0.md

+---
+comments: false
+---
+
 # From 7.14 to 8.0
 
 ### 0. Double-check your Git version

doc/update/7.2-to-7.3.md

+---
+comments: false
+---
+
 # From 7.2 to 7.3
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.2-to-7.3.md) for the most up to date instructions.*
 

doc/update/7.3-to-7.4.md

+---
+comments: false
+---
+
 # From 7.3 to 7.4
 *Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.3-to-7.4.md) for the most up to date instructions.*
 

doc/update/7.4-to-7.5.md

+---
+comments: false
+---
+
 # From 7.4 to 7.5
 
 ### 0. Stop server

doc/update/7.5-to-7.6.md

+---
+comments: false
+---
+
 # From 7.5 to 7.6
 
 ### 0. Stop server

doc/update/7.6-to-7.7.md

+---
+comments: false
+---
+
 # From 7.6 to 7.7
 
 ### 0. Stop server

doc/update/7.7-to-7.8.md

+---
+comments: false
+---
+
 # From 7.7 to 7.8
 
 ### 0. Stop server

doc/update/7.8-to-7.9.md

+---
+comments: false
+---
+
 # From 7.8 to 7.9
 
 ### 0. Stop server

doc/update/7.9-to-7.10.md

+---
+comments: false
+---
+
 # From 7.9 to 7.10
 
 ### 0. Stop server

doc/update/8.0-to-8.1.md

+---
+comments: false
+---
+
 # From 8.0 to 8.1
 
 **NOTE:** GitLab 8.0 introduced several significant changes related to

doc/update/8.1-to-8.2.md

+---
+comments: false
+---
+
 # From 8.1 to 8.2
 
 **NOTE:** GitLab 8.0 introduced several significant changes related to

doc/update/8.10-to-8.11.md

+---
+comments: false
+---
+
 # From 8.10 to 8.11
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.11-to-8.12.md

+---
+comments: false
+---
+
 # From 8.11 to 8.12
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.12-to-8.13.md

+---
+comments: false
+---
+
 # From 8.12 to 8.13
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.13-to-8.14.md

+---
+comments: false
+---
+
 # From 8.13 to 8.14
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.14-to-8.15.md

+---
+comments: false
+---
+
 # From 8.14 to 8.15
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.15-to-8.16.md

+---
+comments: false
+---
+
 # From 8.15 to 8.16
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.16-to-8.17.md

+---
+comments: false
+---
+
 # From 8.16 to 8.17
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.17-to-9.0.md

+---
+comments: false
+---
+
 # From 8.17 to 9.0
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.2-to-8.3.md

+---
+comments: false
+---
+
 # From 8.2 to 8.3
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.3-to-8.4.md

+---
+comments: false
+---
+
 # From 8.3 to 8.4
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.4-to-8.5.md

+---
+comments: false
+---
+
 # From 8.4 to 8.5
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.5-to-8.6.md

+---
+comments: false
+---
+
 # From 8.5 to 8.6
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.6-to-8.7.md

+---
+comments: false
+---
+
 # From 8.6 to 8.7
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.7-to-8.8.md

+---
+comments: false
+---
+
 # From 8.7 to 8.8
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.8-to-8.9.md

+---
+comments: false
+---
+
 # From 8.8 to 8.9
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/8.9-to-8.10.md

+---
+comments: false
+---
+
 # From 8.9 to 8.10
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/9.0-to-9.1.md

+---
+comments: false
+---
+
 # From 9.0 to 9.1
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/9.1-to-9.2.md

+---
+comments: false
+---
+
 # From 9.1 to 9.2
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/9.2-to-9.3.md

+---
+comments: false
+---
+
 # From 9.2 to 9.3
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/9.3-to-9.4.md

+---
+comments: false
+---
+
 # From 9.3 to 9.4
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/9.4-to-9.5.md

+---
+comments: false
+---
+
 # From 9.4 to 9.5
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/9.5-to-10.0.md

+---
+comments: false
+---
+
 # From 9.5 to 10.0
 
 Make sure you view this update guide from the tag (version) of GitLab you would

doc/update/patch_versions.md

+---
+comments: false
+---
+
 # Universal update guide for patch versions
 
 ## Select Version to Install

doc/update/upgrader.md

+---
+comments: false
+---
+
 # GitLab Upgrader (deprecated)
 
 *DEPRECATED* We recommend to [switch to the Omnibus package and repository server](https://about.gitlab.com/update/) instead of using this script.

doc/workflow/README.md

+---
+comments: false
+---
+
 # Workflow
 
 - [Automatic issue closing](../user/project/issues/automatic_issue_closing.md)

doc/workflow/gitlab_flow.md

 ![GitLab Flow](gitlab_flow.png)
 
-## Introduction
+# Introduction to GitLab Flow
 
 Version management with git makes branching and merging much easier than older versioning systems such as SVN.
 This allows a wide variety of branching strategies and workflows.