Update docs to markdown style guide.

28 files changed, 381 insertions, 387 deletions

diff --git a/doc/update/2.6-to-3.0.md b/doc/update/2.6-to-3.0.md
index d7047d8eb19..6aabbe095dc 100644
--- a/doc/update/2.6-to-3.0.md
+++ b/doc/update/2.6-to-3.0.md
@@ -1,10 +1,10 @@
 # From 2.6 to 3.0
 
-### 1. Stop server & resque
+## 1. Stop server & resque
 
     sudo service gitlab stop
 
-### 2. Update code & db
+## 2. Update code & db
 
 
 ```bash
@@ -54,10 +54,8 @@ sudo -u git -H sed -i "s/\(GIT_CONFIG_KEYS\s*=>*\s*\).\{2\}/\\1'\.\*'/g" /home/g
 # Check app status
 sudo -u gitlab bundle exec rake gitlab:app:status RAILS_ENV=production
 
-
 ```
 
-
-### 3. Start all
+## 3. Start all
 
     sudo service gitlab start
diff --git a/doc/update/2.9-to-3.0.md b/doc/update/2.9-to-3.0.md
index af929e027a4..8af86b0dc98 100644
--- a/doc/update/2.9-to-3.0.md
+++ b/doc/update/2.9-to-3.0.md
@@ -1,10 +1,10 @@
 # From 2.9 to 3.0
 
-### 1. Stop server & resque
+## 1. Stop server & resque
 
     sudo service gitlab stop
 
-### 2. Follow instructions
+## 2. Follow instructions
 
 ```bash
 
@@ -31,7 +31,6 @@ sudo -u git -H sed -i 's/\(GL_GITCONFIG_KEYS\s*=>*\s*\).\{2\}/\\1"\.\*"/g' /home
 sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production
 ```
 
-
-### 3. Start all
+## 3. Start all
 
     sudo service gitlab start
diff --git a/doc/update/3.0-to-3.1.md b/doc/update/3.0-to-3.1.md
index 5f06f818d10..3206df3499b 100644
--- a/doc/update/3.0-to-3.1.md
+++ b/doc/update/3.0-to-3.1.md
@@ -1,26 +1,22 @@
 # From 3.0 to 3.1
 
-__IMPORTANT!__
+**IMPORTANT!**
 
-In this release __we moved Resque jobs under own gitlab namespace__.
+In this release **we moved Resque jobs under own gitlab namespace**
 
-Despite a lot of advantages it requires from our users to __replace gitolite post-receive hook with new one__.
+Despite a lot of advantages it requires from our users to **replace gitolite post-receive hook with new one**.
 
-Most of projects has post-receive file as symlink to gitolite `/home/git/.gitolite/hooks/post-receive`.
-But some of them may have a real file. In this case you should rewrite it with symlink to gitolite hook.
+Most of projects has post-receive file as symlink to gitolite `/home/git/.gitolite/hooks/post-receive`. But some of them may have a real file. In this case you should rewrite it with symlink to gitolite hook.
 
 I wrote a bash script which will do it automatically for you. Just make sure all path inside is valid for you
 
-- - -
-
-### 1. Stop server & resque
+## 1. Stop server & resque
 
     sudo service gitlab stop
 
-### 2. Update GitLab
+## 2. Update GitLab
 
 ```bash
-
 # Get latest code
 sudo -u gitlab -H git fetch
 sudo -u gitlab -H git checkout v3.1.0
@@ -35,12 +31,11 @@ sudo -u gitlab -H bundle install --without development test postgres sqlite
 # Migrate db
 sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production
 
-
 ```
 
-### 3. Update post-receive hooks
+## 3. Update post-receive hooks
 
-#### Gitolite 3
+### Gitolite 3
 
 Step 1: Rewrite post-receive hook
 
@@ -60,7 +55,7 @@ sudo -u gitlab -H vim lib/support/rewrite-hooks.sh
 sudo -u git -H lib/support/rewrite-hooks.sh
 ```
 
-#### Gitolite v2
+### Gitolite v2
 
 Step 1: rewrite post-receive hook for gitolite 2
 
@@ -71,7 +66,6 @@ sudo chown git:git /home/git/share/gitolite/hooks/common/post-receive
 
 Step 2: Replace symlinks in project to valid place
 
-
     #!/bin/bash
     src="/home/git/repositories"
     for dir in `ls "$src/"`
@@ -90,19 +84,13 @@ Step 2: Replace symlinks in project to valid place
       fi
     done
 
-
-### 4. Check app status
+## 4. Check app status
 
 ```bash
-
 # Check APP Status
 sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production
-
-
-
 ```
 
-
-### 5. Start all
+## 5. Start all
 
     sudo service gitlab start
diff --git a/doc/update/3.1-to-4.0.md b/doc/update/3.1-to-4.0.md
index c5ae3a40a76..165f4e6a308 100644
--- a/doc/update/3.1-to-4.0.md
+++ b/doc/update/3.1-to-4.0.md
@@ -2,25 +2,22 @@
 
 ## Important changes
 
-* Support for SQLite was dropped
-* Support for gitolite 2 was dropped
-* Projects are organized in namespaces
-* The GitLab post-receive hook needs to be updated
-* The configuration file needs to be updated
-* Availability of `python2` executable
+- Support for SQLite was dropped
+- Support for Gitolite 2 was dropped
+- Projects are organized in namespaces
+- The GitLab post-receive hook needs to be updated
+- The configuration file needs to be updated
+- Availability of `python2` executable
 
-Most of projects has post-receive file as symlink to gitolite `/home/git/.gitolite/hooks/post-receive`.
-But some of them may have a real file. In this case you should rewrite it with symlink to gitolite hook.
+Most of projects has post-receive file as symlink to Gitolite `/home/git/.gitolite/hooks/post-receive`. But some of them may have a real file. In this case you should rewrite it with symlink to Gitolite hook.
 
 I wrote a bash script which will do it automatically for you. Just make sure all path inside is valid for you
 
-- - -
-
-### 1. Stop GitLab & Resque
+## 1. Stop GitLab & Resque
 
     sudo service gitlab stop
 
-### 2. Update GitLab
+## 2. Update GitLab
 
 ```bash
 
@@ -43,8 +40,7 @@ sudo -u gitlab -H bundle exec rake gitlab:enable_namespaces RAILS_ENV=production
 
 ```
 
-### 3. Update post-receive hooks  (Requires gitolite v3 )
-
+## 3. Update post-receive hooks  (Requires Gitolite v3 )
 
 Step 1: Rewrite post-receive hook
 
@@ -63,9 +59,7 @@ sudo -u gitlab -H vim lib/support/rewrite-hooks.sh
 sudo -u git -H lib/support/rewrite-hooks.sh
 ```
 
-
-### 4. Replace config with new one
-
+## 4. Replace config with new one
 
     # backup old one
     sudo -u gitlab -H cp config/gitlab.yml config/gitlab.yml.old
@@ -76,9 +70,7 @@ sudo -u git -H lib/support/rewrite-hooks.sh
     # edit it
     sudo -u gitlab -H vim config/gitlab.yml
 
-
-### 5. Disable ssh known_host check for own domain
-
+## 5. Disable ssh known_host check for own domain
 
     echo "Host localhost
        StrictHostKeyChecking no
@@ -88,12 +80,10 @@ sudo -u git -H lib/support/rewrite-hooks.sh
        StrictHostKeyChecking no
        UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config
 
-
-### 6. Check GitLab's status
+## 6. Check GitLab's status
 
     sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production
 
-
-### 7. Start GitLab & Resque
+## 7. Start GitLab & Resque
 
     sudo service gitlab start
diff --git a/doc/update/4.0-to-4.1.md b/doc/update/4.0-to-4.1.md
index 324af7597b2..d5e5d62fb15 100644
--- a/doc/update/4.0-to-4.1.md
+++ b/doc/update/4.0-to-4.1.md
@@ -2,18 +2,16 @@
 
 ## Important changes
 
-* Resque replaced with Sidekiq
-* New options for configuration file added
-* Init.d script should be updated
-* __requires ruby1.9.3-p327__
+- Resque replaced with Sidekiq
+- New options for configuration file added
+- Init.d script should be updated
+- **requires ruby1.9.3-p327**
 
-- - -
-
-### 1. Stop GitLab & Resque
+## 1. Stop GitLab & Resque
 
     sudo service gitlab stop
 
-### 2. Update GitLab
+## 2. Update GitLab
 
 ```bash
 # Set the working directory
@@ -31,7 +29,7 @@ sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production
 
 ```
 
-### 3. Replace init.d script with a new one
+## 3. Replace init.d script with a new one
 
 ```
 # backup old one
@@ -43,15 +41,15 @@ sudo chmod +x /etc/init.d/gitlab
 
 ```
 
-### 4. Check GitLab's status
+## 4. Check GitLab's status
 
     sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production
 
 
-### 5. Start GitLab & Sidekiq
+## 5. Start GitLab & Sidekiq
 
     sudo service gitlab start
 
-### 6. Remove old init.d script
+## 6. Remove old init.d script
 
     sudo rm /etc/init.d/gitlab.old
diff --git a/doc/update/4.1-to-4.2.md b/doc/update/4.1-to-4.2.md
index 3aaf17b7727..5ee8e8781e9 100644
--- a/doc/update/4.1-to-4.2.md
+++ b/doc/update/4.1-to-4.2.md
@@ -1,10 +1,10 @@
 # From 4.1 to 4.2
 
-### 1. Stop server & resque
+## 1. Stop server & Resque
 
     sudo service gitlab stop
 
-### 2. Update code & db
+## 2. Update code & DB
 
 ```bash
 
@@ -24,15 +24,12 @@ sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production
 
 ```
 
-
-### 3. Check GitLab's status
+## 3. Check GitLab's status
 
 ```bash
 sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production
 ```
 
-
-
-### 4. Start all
+## 4. Start all
 
     sudo service gitlab start
diff --git a/doc/update/4.2-to-5.0.md b/doc/update/4.2-to-5.0.md
index f8fb607e016..230c1e88b23 100644
--- a/doc/update/4.2-to-5.0.md
+++ b/doc/update/4.2-to-5.0.md
@@ -1,32 +1,32 @@
 # From 4.2 to 5.0
 
 ## Warning
+
 GitLab 5.0 is affected by critical security vulnerability CVE-2013-4490.
 
 ## Important changes
 
-* We don't use `gitlab` user any more. Everything will be moved to `git` user
-* __requires ruby1.9.3__
-
+- We don't use `gitlab` user any more. Everything will be moved to `git` user
+- **requires ruby1.9.3**
 
-__0. Stop gitlab__
+## 0. Stop gitlab
 
     sudo service gitlab stop
 
-__1. add bash to git user__
+## 1. add bash to git user
 
 ```
 sudo chsh -s /bin/bash git
 ```
 
-__2. git clone gitlab-shell__
+## 2. git clone gitlab-shell
 
 ```
 cd /home/git/
 sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git /home/git/gitlab-shell
 ```
 
-__3. setup gitlab-shell__
+## 3. setup gitlab-shell
 
 ```bash
 # chmod all repos and files under git
@@ -55,7 +55,7 @@ ruby -v
 exit
 ```
 
-__4. Copy gitlab instance to git user__
+## 4. Copy gitlab instance to git user
 
 ```bash
 sudo cp -R /home/gitlab/gitlab /home/git/gitlab
@@ -66,7 +66,7 @@ sudo rm -rf /home/gitlab/gitlab-satellites
 sudo rm /tmp/gitlab.socket
 ```
 
-__5. Update gitlab to recent version__
+## 5. Update gitlab to recent version
 
 ```bash
 cd /home/git/gitlab
@@ -110,7 +110,7 @@ sudo chmod -R u+rwX  /home/git/gitlab/tmp/pids
 
 ```
 
-__6. Update init.d script and nginx config__
+## 6. Update init.d script and nginx config
 
 ```bash
 # init.d
@@ -127,14 +127,11 @@ sudo -u git -H cp /home/git/gitlab/config/unicorn.rb.example /home/git/gitlab/co
 sudo vim /etc/nginx/sites-enabled/gitlab
 sudo service nginx restart
 
-
 ```
 
-__7. Start gitlab instance__
+## 7. Start GitLab instance
 
 ```
-
-
 sudo service gitlab start
 
 # check if unicorn and sidekiq started
@@ -145,7 +142,7 @@ ps aux | grep sidekiq
 
 ```
 
-__8. Check installation__
+## 8. Check installation
 
 
 ```bash
@@ -164,5 +161,4 @@ sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
 
 ```
 
-
-__P.S. If everything works as expected you can remove gitlab user from system__
+**P.S. If everything works as expected you can remove gitlab user from system**
diff --git a/doc/update/5.0-to-5.1.md b/doc/update/5.0-to-5.1.md
index ba56507dd81..628d8bc7dfa 100644
--- a/doc/update/5.0-to-5.1.md
+++ b/doc/update/5.0-to-5.1.md
@@ -1,18 +1,19 @@
 # From 5.0 to 5.1
 
 ## Warning
+
 GitLab 5.1 is affected by critical security vulnerability CVE-2013-4490.
 
-## Release notes:
+## Release notes
 
-* `unicorn` replaced with `puma`
-* merge request cached diff will be truncated
+- `unicorn` replaced with `puma`
+- merge request cached diff will be truncated
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -20,7 +21,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout 5-1-stable
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -33,8 +34,7 @@ sudo -u git -H cp config.yml.example config.yml
 sudo -u git -H vi config.yml
 ```
 
-
-### 4. Install libs, migrations etc
+## 4. Install libs, migrations etc
 
 ```bash
 cd /home/git/gitlab
@@ -47,7 +47,7 @@ sudo -u git -H bundle exec rake migrate_merge_requests RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 ```
 
-### 5. Update init.d script with a new one
+## 5. Update init.d script with a new one
 
 ```bash
 # init.d
@@ -56,9 +56,9 @@ sudo curl --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-rec
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 6. Mysql grant privileges
+## 6. MySQL grant privileges
 
-Only if you are using mysql:
+Only if you are using MySQL:
 
 ```bash
 mysql -u root -p
@@ -66,6 +66,6 @@ mysql> GRANT LOCK TABLES ON `gitlabhq_production`.* TO 'gitlab'@'localhost';
 mysql> \q
 ```
 
-### 7. Start application
+## 7. Start application
 
     sudo service gitlab start
diff --git a/doc/update/5.1-to-5.2.md b/doc/update/5.1-to-5.2.md
index 466c815195f..c37f20ce55e 100644
--- a/doc/update/5.1-to-5.2.md
+++ b/doc/update/5.1-to-5.2.md
@@ -1,9 +1,10 @@
 # From 5.1 to 5.2
 
 ## Warning
+
 GitLab 5.2 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489.
 
-### 0. Backup
+## 0. Backup
 
 It's useful to make a backup just in case things go south:
 (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
@@ -13,11 +14,11 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -25,7 +26,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout 5-2-stable
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -33,7 +34,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.4.0
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -49,12 +50,12 @@ sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 ```
 
-### 5. Update config files
+## 5. Update config files
 
-* Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/puma.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/puma.rb.example but with your settings.
 
-### 6. Update Init script
+## 6. Update Init script
 
 ```bash
 cd /home/git/gitlab
@@ -63,7 +64,7 @@ sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 7. Create uploads directory
+## 7. Create uploads directory
 
 ```bash
 cd /home/git/gitlab
@@ -71,12 +72,12 @@ sudo -u git -H mkdir public/uploads
 sudo chmod -R u+rwX  public/uploads
 ```
 
-### 8. Start application
+## 8. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 9. Check application status
+## 9. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -91,10 +92,10 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (5.1)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 5.0 to 5.1`](5.0-to-5.1.md), except for the database migration 
-(The backup is already migrated to the previous version)
 
-### 2. Restore from the backup:
+Follow the [`upgrade guide from 5.0 to 5.1`](5.0-to-5.1.md), except for the database migration (the backup is already migrated to the previous version).
+
+### 2. Restore from the backup
 
 ```bash
 cd /home/git/gitlab
diff --git a/doc/update/5.1-to-5.4.md b/doc/update/5.1-to-5.4.md
index 56f4854daf0..53dbfd00ad4 100644
--- a/doc/update/5.1-to-5.4.md
+++ b/doc/update/5.1-to-5.4.md
@@ -1,21 +1,21 @@
 # From 5.1 to 5.4
+
 Also works starting from 5.2.
 
-### 0. Backup
+## 0. Backup
 
-It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
+It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version):
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -23,7 +23,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout 5-4-stable # Latest version of 5-4-stable addresses CVE-2013-4489
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -31,7 +31,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -47,12 +47,12 @@ sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 ```
 
-### 5. Update config files
+## 5. Update config files
 
-* Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings.
 
-### 6. Update Init script
+## 6. Update Init script
 
 ```bash
 sudo rm /etc/init.d/gitlab
@@ -60,7 +60,7 @@ sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 7. Create uploads directory
+## 7. Create uploads directory
 
 ```bash
 cd /home/git/gitlab
@@ -68,13 +68,12 @@ sudo -u git -H mkdir public/uploads
 sudo chmod -R u+rwX  public/uploads
 ```
 
-
-### 8. Start application
+## 8. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 9. Check application status
+## 9. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -89,8 +88,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (5.3)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 5.2 to 5.3`](5.2-to-5.3.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 5.2 to 5.3`](5.2-to-5.3.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
diff --git a/doc/update/5.1-to-6.0.md b/doc/update/5.1-to-6.0.md
index 5b74b1f893d..11afc75f0f3 100644
--- a/doc/update/5.1-to-6.0.md
+++ b/doc/update/5.1-to-6.0.md
@@ -1,26 +1,34 @@
 # From 5.1 to 6.0
 
 ## Warning
+
 GitLab 6.0 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489.
 
-### Deprecations
+## Deprecations
 
-#### Global projects
+### Global projects
 
 The root (global) namespace for projects is deprecated.
-So you need to move all your global projects under groups or users manually before update or they will be automatically moved to the project owner namespace during the update. When a project is moved all its members will receive an email with instructions how to update their git remote url. Please make sure you disable sending email when you do a test of the upgrade.
 
-#### Teams
+So you need to move all your global projects under groups or users manually before update or they will be automatically moved to the project owner namespace during the update. When a project is moved all its members will receive an email with instructions how to update their git remote URL. Please make sure you disable sending email when you do a test of the upgrade.
+
+### Teams
 
 We introduce group membership in 6.0 as a replacement for teams.
+
 The old combination of groups and teams was confusing for a lot of people.
+
 And when the members of a team where changed this wasn't reflected in the project permissions.
+
 In GitLab 6.0 you will be able to add members to a group with a permission level for each member.
+
 These group members will have access to the projects in that group.
+
 Any changes to group members will immediately be reflected in the project permissions.
+
 You can even have multiple owners for a group, greatly simplifying administration.
 
-### 0. Backup
+## 0. Backup
 
 It's useful to make a backup just in case things go south:
 (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
@@ -30,11 +38,11 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -42,7 +50,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout 6-0-stable
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -50,14 +58,14 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.7.9
 ```
 
-### 4. Install additional packages
+## 4. Install additional packages
 
 ```bash
 # For reStructuredText markup language support install required package:
 sudo apt-get install python-docutils
 ```
 
-### 5. Install libs, migrations, etc.
+## 5. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -83,14 +91,14 @@ sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 ```
 
-### 6. Update config files
+## 6. Update config files
 
 Note: We switched from Puma in GitLab 5.x to unicorn in GitLab 6.0.
 
-* Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/masterconfig/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/masterconfig/unicorn.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/masterconfig/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/masterconfig/unicorn.rb.example but with your settings.
 
-### 7. Update Init script
+## 7. Update Init script
 
 ```bash
 cd /home/git/gitlab
@@ -99,7 +107,7 @@ sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 8. Create uploads directory
+## 8. Create uploads directory
 
 ```bash
 cd /home/git/gitlab
@@ -107,12 +115,12 @@ sudo -u git -H mkdir -p public/uploads
 sudo chmod -R u+rwX  public/uploads
 ```
 
-### 9. Start application
+## 9. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 10. Check application status
+## 10. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -127,8 +135,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (5.1)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 5.0 to 5.1`](5.0-to-5.1.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 5.0 to 5.1`](5.0-to-5.1.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
@@ -137,20 +145,24 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
 
-### Troubleshooting
+## Troubleshooting
+
 The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following commands can be run in the rails console to look for 'bad' data.
 
-All project owners should have an owner
+All project owners should have an owner:
+
 ```
 Project.all.select { |project| project.owner.blank? }
 ```
 
-Every user should have a namespace
+Every user should have a namespace:
+
 ```
 User.all.select { |u| u.namespace.blank? }
 ```
 
-Projects in the global namespace should not conflict with projects in the owner namespace
+Projects in the global namespace should not conflict with projects in the owner namespace:
+
 ```
 Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? }
 ```
diff --git a/doc/update/5.2-to-5.3.md b/doc/update/5.2-to-5.3.md
index e3c3016db64..e39e18d4211 100644
--- a/doc/update/5.2-to-5.3.md
+++ b/doc/update/5.2-to-5.3.md
@@ -1,23 +1,23 @@
 # From 5.2 to 5.3
 
 ## Warning
+
 GitLab 5.3 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489.
 
-### 0. Backup
+## 0. Backup
 
-It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
+It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version):
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -25,7 +25,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout 5-3-stable
 ```
 
-### 3. Install libs, migrations, etc.
+## 3. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -41,12 +41,12 @@ sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 ```
 
-### 4. Update config files
+## 4. Update config files
 
-* Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/puma.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/puma.rb.example but with your settings.
 
-### 5. Update Init script
+## 5. Update Init script
 
 ```bash
 sudo rm /etc/init.d/gitlab
@@ -54,12 +54,12 @@ sudo curl --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlabhq/5
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 6. Start application
+## 6. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 7. Check application status
+## 7. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -74,8 +74,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (5.2)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 5.1 to 5.2`](5.1-to-5.2.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 5.1 to 5.2`](5.1-to-5.2.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
diff --git a/doc/update/5.3-to-5.4.md b/doc/update/5.3-to-5.4.md
index 213ce77ec38..e1749f133b3 100644
--- a/doc/update/5.3-to-5.4.md
+++ b/doc/update/5.3-to-5.4.md
@@ -1,20 +1,19 @@
 # From 5.3 to 5.4
 
-### 0. Backup
+## 0. Backup
 
-It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
+It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version):
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -22,7 +21,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout 5-4-stable # Latest version of 5-4-stable addresses CVE-2013-4489
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -30,7 +29,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -46,12 +45,12 @@ sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 ```
 
-### 5. Update config files
+## 5. Update config files
 
-* Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings.
 
-### 6. Update Init script
+## 6. Update Init script
 
 ```bash
 sudo rm /etc/init.d/gitlab
@@ -59,12 +58,12 @@ sudo curl --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlabhq/5
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 7. Start application
+## 7. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 8. Check application status
+## 8. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -79,8 +78,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (5.3)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 5.2 to 5.3`](5.2-to-5.3.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 5.2 to 5.3`](5.2-to-5.3.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
diff --git a/doc/update/5.4-to-6.0.md b/doc/update/5.4-to-6.0.md
index c289fcb57fd..7bf7bce6aa0 100644
--- a/doc/update/5.4-to-6.0.md
+++ b/doc/update/5.4-to-6.0.md
@@ -1,40 +1,47 @@
 # From 5.4 to 6.0
 
 ## Warning
+
 GitLab 6.0 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489.
 
-### Deprecations
+## Deprecations
 
-#### Global projects
+### Global projects
 
 The root (global) namespace for projects is deprecated.
+
 So you need to move all your global projects under groups or users manually before update or they will be automatically moved to the project owner namespace during the update. When a project is moved all its members will receive an email with instructions how to update their git remote url. Please make sure you disable sending email when you do a test of the upgrade.
 
-#### Teams
+### Teams
 
 We introduce group membership in 6.0 as a replacement for teams.
+
 The old combination of groups and teams was confusing for a lot of people.
+
 And when the members of a team where changed this wasn't reflected in the project permissions.
+
 In GitLab 6.0 you will be able to add members to a group with a permission level for each member.
+
 These group members will have access to the projects in that group.
+
 Any changes to group members will immediately be reflected in the project permissions.
+
 You can even have multiple owners for a group, greatly simplifying administration.
 
-### 0. Backup
+## 0. Backup
 
-It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
+It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version):
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -42,7 +49,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout 6-0-stable
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -50,14 +57,14 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.7.9
 ```
 
-### 4. Install additional packages
+## 4. Install additional packages
 
 ```bash
 # For reStructuredText markup language support install required package:
 sudo apt-get install python-docutils
 ```
 
-### 5. Install libs, migrations, etc.
+## 5. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -83,14 +90,14 @@ sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 ```
 
-### 6. Update config files
+## 6. Update config files
 
 Note: We switched from Puma in GitLab 5.4 to unicorn in GitLab 6.0.
 
-* Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/unicorn.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/unicorn.rb.example but with your settings.
 
-### 7. Update Init script
+## 7. Update Init script
 
 ```bash
 sudo rm /etc/init.d/gitlab
@@ -98,12 +105,12 @@ sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 8. Start application
+## 8. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 9. Check application status
+## 9. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -115,20 +122,24 @@ To make sure you didn't miss anything run a more thorough check with:
 
 If all items are green, then congratulations upgrade complete!
 
-### Troubleshooting
+## Troubleshooting
+
 The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following commands can be run in the rails console to look for 'bad' data.
 
-All project owners should have an owner
+All project owners should have an owner:
+
 ```
 Project.all.select { |project| project.owner.blank? }
 ```
 
-Every user should have a namespace
+Every user should have a namespace:
+
 ```
 User.all.select { |u| u.namespace.blank? }
 ```
 
-Projects in the global namespace should not conflict with projects in the owner namespace
+Projects in the global namespace should not conflict with projects in the owner namespace:
+
 ```
 Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? }
 ```
diff --git a/doc/update/6.0-to-6.1.md b/doc/update/6.0-to-6.1.md
index b4cc9203587..36c7f04f635 100644
--- a/doc/update/6.0-to-6.1.md
+++ b/doc/update/6.0-to-6.1.md
@@ -1,32 +1,33 @@
 # From 6.0 to 6.1
 
 ## Warning
+
 GitLab 6.1 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489.
 
-# In 6.1 we remove a lot of deprecated code.
-# You should update to 6.0 before installing 6.1 so all the necessary conversions are run.
+**In 6.1 we remove a lot of deprecated code.**
+
+**You should update to 6.0 before installing 6.1 so all the necessary conversions are run.**
 
-### Deprecations
+## Deprecations
 
-#### Global issue numbers
+### Global issue numbers
 
-In 6.1 issue numbers are project specific. This means all issues are renumbered and get a new number in their url. If you use an old issue number url and the issue number does not exist yet you are redirected to the new one. This conversion does not trigger if the old number already exists for this project, this is unlikely but will happen with old issues and large projects.
+In 6.1 issue numbers are project specific. This means all issues are renumbered and get a new number in their URL. If you use an old issue number URL and the issue number does not exist yet you are redirected to the new one. This conversion does not trigger if the old number already exists for this project, this is unlikely but will happen with old issues and large projects.
 
-### 0. Backup
+## 0. Backup
 
-It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
+It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version):
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -35,7 +36,7 @@ sudo -u git -H git checkout 6-1-stable
 # For GitLab Enterprise Edition: sudo -u git -H git checkout 6-1-stable-ee
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -43,7 +44,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.7.9
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -62,12 +63,12 @@ sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
 ```
 
-### 5. Update config files
+## 5. Update config files
 
-* Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/unicorn.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/unicorn.rb.example but with your settings.
 
-### 6. Update Init script
+## 6. Update Init script
 
 ```bash
 sudo rm /etc/init.d/gitlab
@@ -75,12 +76,12 @@ sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 7. Start application
+## 7. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 8. Check application status
+## 8. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -96,8 +97,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (6.0)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 5.4 to 6.0`](5.4-to-6.0.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 5.4 to 6.0`](5.4-to-6.0.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
diff --git a/doc/update/6.0-to-6.8.md b/doc/update/6.0-to-6.8.md
index 5c71e99aa52..0205d0d2e22 100644
--- a/doc/update/6.0-to-6.8.md
+++ b/doc/update/6.0-to-6.8.md
@@ -1,15 +1,16 @@
 # From 6.0 to 6.8
 
-# In 6.1 we remove a lot of deprecated code.
-# You should update to 6.0 before installing 6.1 or higher so all the necessary conversions are run.
+**In 6.1 we remove a lot of deprecated code.**
 
-### Deprecations
+**You should update to 6.0 before installing 6.1 or higher so all the necessary conversions are run.**
 
-#### Global issue numbers
+## Deprecations
 
-As of 6.1 issue numbers are project specific. This means all issues are renumbered and get a new number in their url. If you use an old issue number url and the issue number does not exist yet you are redirected to the new one. This conversion does not trigger if the old number already exists for this project, this is unlikely but will happen with old issues and large projects.
+## Global issue numbers
 
-### 0. Backup
+As of 6.1 issue numbers are project specific. This means all issues are renumbered and get a new number in their URL. If you use an old issue number URL and the issue number does not exist yet you are redirected to the new one. This conversion does not trigger if the old number already exists for this project, this is unlikely but will happen with old issues and large projects.
+
+## 0. Backup
 
 It's useful to make a backup just in case things go south:
 (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
@@ -19,18 +20,18 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H git fetch --all
 ```
 
-For Gitlab Community Edition:
+For GitLab Community Edition:
 
 ```bash
 sudo -u git -H git checkout 6-8-stable
@@ -45,14 +46,14 @@ sudo -u git -H git checkout 6-8-stable-ee
 ```
 
 
-### 3. Install additional packages
+## 3. Install additional packages
 
 ```bash
 # Add support for lograte for better log file handling
 sudo apt-get install logrotate
 ```
 
-### 4. Update gitlab-shell
+## 4. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -60,7 +61,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.9.3 # Addresses multiple critical security vulnerabilities
 ```
 
-### 5. Install libs, migrations, etc.
+## 5. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -85,7 +86,7 @@ sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS
 sudo chmod u+rwx,g+rx,o-rwx /home/git/gitlab-satellites
 ```
 
-### 6. Update config files
+## 6. Update config files
 
 TIP: to see what changed in gitlab.yml.example in this release use next command: 
 
@@ -108,18 +109,18 @@ sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers
 sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab
 ```
 
-### 7. Update Init script
+## 7. Update Init script
 
 ```bash
 sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 ```
 
-### 8. Start application
+## 8. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 9. Check application status
+## 9. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -135,8 +136,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (6.0)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 5.4 to 6.0`](5.4-to-6.0.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 5.4 to 6.0`](5.4-to-6.0.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
@@ -146,4 +147,5 @@ sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
 
 ## Login issues after upgrade?
-If running in https mode, be sure to read [Can't Verify csrf token authenticity](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide#cant-verify-csrf-token-authenticitycant-get-past-login-pageredirected-to-login-page) 
+
+If running in HTTPS mode, be sure to read [Can't Verify CSRF token authenticity](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide#cant-verify-csrf-token-authenticitycant-get-past-login-pageredirected-to-login-page) 
diff --git a/doc/update/6.1-to-6.2.md b/doc/update/6.1-to-6.2.md
index c618e599dcb..9ab53aae24b 100644
--- a/doc/update/6.1-to-6.2.md
+++ b/doc/update/6.1-to-6.2.md
@@ -1,22 +1,21 @@
 # From 6.1 to 6.2
 
-# You should update to 6.1 before installing 6.2 so all the necessary conversions are run.
+**You should update to 6.1 before installing 6.2 so all the necessary conversions are run.**
 
-### 0. Backup
+## 0. Backup
 
-It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
+It's useful to make a backup just in case things go south: (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version).
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -25,7 +24,7 @@ sudo -u git -H git checkout 6-2-stable # Latest version of 6-2-stable addresses
 # For GitLab Enterprise Edition: sudo -u git -H git checkout 6-2-stable-ee
 ```
 
-### 3. Update gitlab-shell
+## 3. Update gitlab-shell
 
 ```bash
 cd /home/git/gitlab-shell
@@ -33,14 +32,14 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities
 ```
 
-### 4. Install additional packages
+## 4. Install additional packages
 
 ```bash
 # Add support for lograte for better log file handling
 sudo apt-get install logrotate
 ```
 
-### 5. Install libs, migrations, etc.
+## 5. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -58,29 +57,33 @@ sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production
 sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
 ```
 
-### 6. Update config files
+## 6. Update config files
 
-TIP: to see what changed in gitlab.yml.example in this release use next command: 
+TIP: to see what changed in `gitlab.yml.example` in this release use next command: 
 
 ```
 git diff 6-1-stable:config/gitlab.yml.example 6-2-stable:config/gitlab.yml.example
 ```
 
-* Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/unicorn.rb.example but with your settings.
-* Copy rack attack middleware config
+-   Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/gitlab.yml.example but with your settings.
 
-```bash
-sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb
-```
-* Uncomment `config.middleware.use Rack::Attack` in `/home/git/gitlab/config/application.rb`
-* Set up logrotate
+-   Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/unicorn.rb.example but with your settings.
+
+-   Copy rack attack middleware config:
+
+    ```bash
+    sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb
+    ```
+
+-   Uncomment `config.middleware.use Rack::Attack` in `/home/git/gitlab/config/application.rb`
+
+-   Set up logrotate.
 
 ```bash
 sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab
 ```
 
-### 7. Update Init script
+## 7. Update Init script
 
 ```bash
 sudo rm /etc/init.d/gitlab
@@ -88,12 +91,12 @@ sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 8. Start application
+## 8. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 9. Check application status
+## 9. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -108,8 +111,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (6.1)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 6.0 to 6.1`](6.0-to-6.1.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 6.0 to 6.1`](6.0-to-6.1.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
diff --git a/doc/update/6.2-to-6.3.md b/doc/update/6.2-to-6.3.md
index 7f916047369..dfe2e551b36 100644
--- a/doc/update/6.2-to-6.3.md
+++ b/doc/update/6.2-to-6.3.md
@@ -1,22 +1,21 @@
 # From 6.2 to 6.3
 
-## Requires version: 6.1 or 6.2
+**Requires version: 6.1 or 6.2.**
 
-### 0. Backup
+## 0. Backup
 
-It's useful to make a backup just in case things go south:
-(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
+It's useful to make a backup just in case things go south: (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version)
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -25,7 +24,7 @@ sudo -u git -H git checkout 6-3-stable
 # For GitLab Enterprise Edition: sudo -u git -H git checkout 6-3-stable-ee
 ```
 
-### 3. Update gitlab-shell (and its config)
+## 3. Update gitlab-shell (and its config)
 
 ```bash
 cd /home/git/gitlab-shell
@@ -33,9 +32,9 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities
 ```
 
-The Gitlab-shell config changed recently, so check for config file changes and make `/home/git/gitlab-shell/config.yml` the same as https://github.com/gitlabhq/gitlab-shell/blob/master/config.yml.example
+The Gitlab-shell config changed recently, so check for config file changes and make `/home/git/gitlab-shell/config.yml` the same as <https://github.com/gitlabhq/gitlab-shell/blob/master/config.yml.example>
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -54,7 +53,7 @@ sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production
 sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production
 ```
 
-### 5. Update config files
+## 5. Update config files
 
 TIP: to see what changed in gitlab.yml.example in this release use next command: 
 
@@ -62,8 +61,8 @@ TIP: to see what changed in gitlab.yml.example in this release use next command:
 git diff 6-2-stable:config/gitlab.yml.example 6-3-stable:config/gitlab.yml.example
 ```
 
-* Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/gitlab.yml.example but with your settings.
-* Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/unicorn.rb.example but with your settings.
+- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/gitlab.yml.example but with your settings.
+- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/unicorn.rb.example but with your settings.
 
 ```bash
 # Copy rack attack middleware config
@@ -71,19 +70,19 @@ cd /home/git/gitlab
 sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb
 ```
 
-### 6. Update Init script
+## 6. Update Init script
 
 ```bash
 sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 sudo chmod +x /etc/init.d/gitlab
 ```
 
-### 7. Start application
+## 7. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 8. Check application status
+## 8. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -98,8 +97,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (6.2)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 6.1 to 6.2`](6.1-to-6.2.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 6.1 to 6.2`](6.1-to-6.2.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
diff --git a/doc/update/6.3-to-6.4.md b/doc/update/6.3-to-6.4.md
index cfe75a6f149..18dce9b5f93 100644
--- a/doc/update/6.3-to-6.4.md
+++ b/doc/update/6.3-to-6.4.md
@@ -1,19 +1,19 @@
 # From 6.3 to 6.4
 
-### 0. Backup
+## 0. Backup
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
 ```bash
 sudo service gitlab stop
 ````
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -22,7 +22,7 @@ sudo -u git -H git checkout 6-4-stable
 # For GitLab Enterprise Edition: sudo -u git -H git checkout 6-4-stable-ee
 ```
 
-### 3. Update gitlab-shell (and its config)
+## 3. Update gitlab-shell (and its config)
 
 ```bash
 cd /home/git/gitlab-shell
@@ -30,7 +30,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.8.0
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -52,14 +52,14 @@ sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS
 sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 ```
 
-### 5. Start application
+## 5. Start application
 
 ```bash
 sudo service gitlab start
 sudo service nginx restart
 ```
 
-### 6. Check application status
+## 6. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -78,8 +78,8 @@ If all items are green, then congratulations upgrade complete!
 ## Things went south? Revert to previous version (6.3)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 6.2 to 6.3`](6.2-to-6.3.md), except for the database migration 
-(The backup is already migrated to the previous version)
+
+Follow the [`upgrade guide from 6.2 to 6.3`](6.2-to-6.3.md), except for the database migration (the backup is already migrated to the previous version).
 
 ### 2. Restore from the backup:
 
diff --git a/doc/update/6.4-to-6.5.md b/doc/update/6.4-to-6.5.md
index c88be3582cf..1a95a98b6f2 100644
--- a/doc/update/6.4-to-6.5.md
+++ b/doc/update/6.4-to-6.5.md
@@ -1,24 +1,24 @@
 # From 6.4 to 6.5
 
-### 0. Backup
+## 0. Backup
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H git fetch --all
 ```
 
-For Gitlab Community Edition:
+For GitLab Community Edition:
 
 ```bash
 sudo -u git -H git checkout 6-5-stable
@@ -32,7 +32,7 @@ For GitLab Enterprise Edition:
 sudo -u git -H git checkout 6-5-stable-ee
 ```
 
-### 3. Update gitlab-shell (and its config)
+## 3. Update gitlab-shell (and its config)
 
 ```bash
 cd /home/git/gitlab-shell
@@ -40,7 +40,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.8.0
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -62,12 +62,12 @@ sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS
 sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 ```
 
-### 5. Start application
+## 5. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 6. Check application status
+## 6. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -82,13 +82,14 @@ If all items are green, then congratulations upgrade is complete!
 ## Things went south? Revert to previous version (6.4)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 6.3 to 6.4`](6.3-to-6.4.md), except for the database migration 
-(The backup is already migrated to the previous version)
 
-### 2. Restore from the backup:
+Follow the [`upgrade guide from 6.3 to 6.4`](6.3-to-6.4.md), except for the database migration (the backup is already migrated to the previous version).
+
+### 2. Restore from the backup
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
+
 If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above.
diff --git a/doc/update/6.5-to-6.6.md b/doc/update/6.5-to-6.6.md
index 589c18c27c2..ee6a5a9bdf2 100644
--- a/doc/update/6.5-to-6.6.md
+++ b/doc/update/6.5-to-6.6.md
@@ -1,24 +1,24 @@
 # From 6.5 to 6.6
 
-### 0. Backup
+## 0. Backup
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H git fetch --all
 ```
 
-For Gitlab Community Edition:
+For GitLab Community Edition:
 
 ```bash
 sudo -u git -H git checkout 6-6-stable
@@ -32,7 +32,7 @@ For GitLab Enterprise Edition:
 sudo -u git -H git checkout 6-6-stable-ee
 ```
 
-### 3. Update gitlab-shell (and its config)
+## 3. Update gitlab-shell (and its config)
 
 ```bash
 cd /home/git/gitlab-shell
@@ -40,7 +40,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.8.0
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -62,12 +62,12 @@ sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS
 sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab
 ```
 
-### 5. Start application
+## 5. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 6. Check application status
+## 6. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -82,6 +82,7 @@ If all items are green, then congratulations upgrade is complete!
 ## Things went south? Revert to previous version (6.5)
 
 ### 1. Revert the code to the previous version
+
 Follow the [`upgrade guide from 6.4 to 6.5`](6.4-to-6.5.md), except for the database migration 
 (The backup is already migrated to the previous version)
 
@@ -91,4 +92,5 @@ Follow the [`upgrade guide from 6.4 to 6.5`](6.4-to-6.5.md), except for the data
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
+
 If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above.
diff --git a/doc/update/6.6-to-6.7.md b/doc/update/6.6-to-6.7.md
index 3093923007a..1e3b7da12d4 100644
--- a/doc/update/6.6-to-6.7.md
+++ b/doc/update/6.6-to-6.7.md
@@ -1,17 +1,17 @@
 # From 6.6 to 6.7
 
-### 0. Backup
+## 0. Backup
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
@@ -32,7 +32,7 @@ For GitLab Enterprise Edition:
 sudo -u git -H git checkout 6-7-stable-ee
 ```
 
-### 3. Update gitlab-shell (and its config)
+## 3. Update gitlab-shell (and its config)
 
 ```bash
 cd /home/git/gitlab-shell
@@ -40,7 +40,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.9.1
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -72,13 +72,12 @@ sudo -u git -H gzip /home/git/gitlab-shell/gitlab-shell.log.1
 sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites
 ```
 
-
-### 5. Start application
+## 5. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 6. Check application status
+## 6. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -93,13 +92,14 @@ If all items are green, then congratulations upgrade is complete!
 ## Things went south? Revert to previous version (6.6)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 6.5 to 6.6`](6.5-to-6.6.md), except for the database migration 
-(The backup is already migrated to the previous version)
 
-### 2. Restore from the backup:
+Follow the [`upgrade guide from 6.5 to 6.6`](6.5-to-6.6.md), except for the database migration (the backup is already migrated to the previous version).
+
+### 2. Restore from the backup
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
 ```
+
 If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above.
diff --git a/doc/update/6.7-to-6.8.md b/doc/update/6.7-to-6.8.md
index 1afcb9f9c69..3c98896a9b2 100644
--- a/doc/update/6.7-to-6.8.md
+++ b/doc/update/6.7-to-6.8.md
@@ -1,26 +1,26 @@
 # From 6.7 to 6.8
 
-### 0. Backup
+## 0. Backup
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 ```
 
-### 1. Stop server
+## 1. Stop server
 
 ```bash
 sudo service gitlab stop
 ```
 
-### 2. Get latest code
+## 2. Get latest code
 
 ```bash
 cd /home/git/gitlab
 sudo -u git -H git fetch --all
 ```
 
-For Gitlab Community Edition:
+For GitLab Community Edition:
 
 ```bash
 sudo -u git -H git checkout 6-8-stable
@@ -34,7 +34,7 @@ For GitLab Enterprise Edition:
 sudo -u git -H git checkout 6-8-stable-ee
 ```
 
-### 3. Update gitlab-shell (and its config)
+## 3. Update gitlab-shell (and its config)
 
 ```bash
 cd /home/git/gitlab-shell
@@ -42,7 +42,7 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.9.3
 ```
 
-### 4. Install libs, migrations, etc.
+## 4. Install libs, migrations, etc.
 
 ```bash
 cd /home/git/gitlab
@@ -68,9 +68,9 @@ sudo chmod +x /etc/init.d/gitlab
 sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites
 ```
 
-### 5. Update config files
+## 5. Update config files
 
-#### New configuration options for gitlab.yml
+### New configuration options for gitlab.yml
 
 There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired.
 
@@ -78,24 +78,24 @@ There are new configuration options available for gitlab.yml. View them with the
 git diff 6-7-stable:config/gitlab.yml.example 6-8-stable:config/gitlab.yml.example
 ```
 
-#### MySQL? Remove reaping frequency
+### MySQL? Remove reaping frequency
 
 If you are using MySQL as a database, remove `reaping_frequency` from you database.yml to prevent crashes. [Relevant commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/5163a8fcb9cfd63435560fda00173b76df2ccc93).
 
-#### HTTPS? Disable gzip
+### HTTPS? Disable gzip
 
 If you are using HTTPS, disable gzip as in [this commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/563fec734912d81cd7caea6fa8ec2b397fb72a9b) to prevent BREACH attacks.
 
-#### Turn on asset compression
+### Turn on asset compression
 
 To improve performance, enable gzip asset compression as seen [in this commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/8af94ed75505f0253823b9b2d44320fecea5b5fb).
 
-### 6. Start application
+## 6. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 7. Check application status
+## 7. Check application status
 
 Check if GitLab and its environment are configured correctly:
 
@@ -110,10 +110,10 @@ If all items are green, then congratulations upgrade is complete!
 ## Things went south? Revert to previous version (6.7)
 
 ### 1. Revert the code to the previous version
-Follow the [`upgrade guide from 6.6 to 6.7`](6.6-to-6.7.md), except for the database migration 
-(The backup is already migrated to the previous version)
 
-### 2. Restore from the backup:
+Follow the [`upgrade guide from 6.6 to 6.7`](6.6-to-6.7.md), except for the database migration (the backup is already migrated to the previous version).
+
+### 2. Restore from the backup
 
 ```bash
 cd /home/git/gitlab
diff --git a/doc/update/README.md b/doc/update/README.md
index 9ce48a019e8..8c0cf5f7b26 100644
--- a/doc/update/README.md
+++ b/doc/update/README.md
@@ -1,5 +1,5 @@
-+ [The individual upgrade guides](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update)
-+ [Upgrader](upgrader.md)
-+ [Ruby](ruby.md)
-+ [Patch versions](patch_versions.md)
-+ [MySQL to PostgreSQL](mysql_to_postgresql.md)
+- [The individual upgrade guides](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update)
+- [Upgrader](upgrader.md)
+- [Ruby](ruby.md)
+- [Patch versions](patch_versions.md)
+- [MySQL to PostgreSQL](mysql_to_postgresql.md)
diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md
index 5083bef1e26..05c95679673 100644
--- a/doc/update/mysql_to_postgresql.md
+++ b/doc/update/mysql_to_postgresql.md
@@ -1,11 +1,6 @@
 # Migrating GitLab from MySQL to Postgres
 
-If you are replacing MySQL with Postgres while keeping GitLab on the same
-server all you need to do is to export from MySQL, import into Postgres and
-rebuild the indexes as described below. If you are also moving GitLab to
-another server, or if you are switching to omnibus-gitlab, you may want to use
-a GitLab backup file. The second part of this documents explains the procedure
-to do this.
+If you are replacing MySQL with Postgres while keeping GitLab on the same server all you need to do is to export from MySQL, import into Postgres and rebuild the indexes as described below. If you are also moving GitLab to another server, or if you are switching to omnibus-gitlab, you may want to use a GitLab backup file. The second part of this documents explains the procedure to do this.
 
 ## Export from MySQL and import into Postgres
 
@@ -27,18 +22,13 @@ psql -f databasename.psql -d gitlabhq_production
 sudo service gitlab start
 ```
 
-
 ## Rebuild indexes
 
-The lanyrd database converter script does not preserve all indexes, so we have
-to recreate them ourselves after migrating from MySQL. It is not necessary to
-shut down GitLab for this process.
-
+The lanyrd database converter script does not preserve all indexes, so we have to recreate them ourselves after migrating from MySQL. It is not necessary to shut down GitLab for this process.
 
 ### For non-omnibus installations
 
-On non-omnibus installations (distributed using Git) we retrieve the index
-declarations from version control using `git stash`.
+On non-omnibus installations (distributed using Git) we retrieve the index declarations from version control using `git stash`.
 
 ```
 # Clone the database converter on your Postgres-backed GitLab server
@@ -59,8 +49,7 @@ sudo -u git -H bundle exec rails runner -e production 'eval $stdin.read' < /tmp/
 
 ### For omnibus-gitlab installations
 
-On omnibus-gitlab we need to get the index declarations from a file called
-`schema.rb.bundled`. For versions older than 6.9, we need to download the file.
+On omnibus-gitlab we need to get the index declarations from a file called `schema.rb.bundled`. For versions older than 6.9, we need to download the file.
 
 ```
 # Clone the database converter on your Postgres-backed GitLab server
@@ -80,10 +69,7 @@ test -e /opt/gitlab/embedded/service/gitlab-rails/db/schema.rb.bundled || sudo /
 
 ## Converting a GitLab backup file from MySQL to Postgres
 
-GitLab backup files (<timestamp>_gitlab_backup.tar) contain a SQL dump.  Using
-the lanyrd database converter we can replace a MySQL database dump inside the
-tar file with a Postgres database dump. This can be useful if you are moving to
-another server.
+GitLab backup files (<timestamp>_gitlab_backup.tar) contain a SQL dump. Using the lanyrd database converter we can replace a MySQL database dump inside the tar file with a Postgres database dump. This can be useful if you are moving to another server.
 
 ```
 # Stop GitLab
diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md
index 2b947adaa13..c4a77d12800 100644
--- a/doc/update/patch_versions.md
+++ b/doc/update/patch_versions.md
@@ -1,4 +1,6 @@
-# Universal update guide for patch versions. For example from 6.2.0 to 6.2.1, also see the [semantic versioning specification](http://semver.org/).
+# Universal update guide for patch versions
+
+For example from 6.2.0 to 6.2.1, also see the [semantic versioning specification](http://semver.org/).
 
 ### 0. Backup
 
diff --git a/doc/update/ruby.md b/doc/update/ruby.md
index e98167f6b66..d1d9d3e77f5 100644
--- a/doc/update/ruby.md
+++ b/doc/update/ruby.md
@@ -2,28 +2,31 @@
 
 This guide explains how to update Ruby in case you installed it from source according to the [instructions](../install/installation.md#2-ruby).
 
-### 1. Look for Ruby versions
+## 1. Look for Ruby versions
+
 This guide will only update `/usr/local/bin/ruby`. You can see which Ruby binaries are installed on your system by running:
 
 ```bash
 ls -l $(which -a ruby)
 ```
 
-### 2. Stop GitLab
+## 2. Stop GitLab
 
 ```bash
 sudo service gitlab stop
 ```
 
-### 3. Install or update dependencies
+## 3. Install or update dependencies
+
 Here we are assuming you are using Debian/Ubuntu.
 
 ```bash
 sudo apt-get install build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl
 ```
 
-### 4. Download, compile and install Ruby
-Find the latest stable version of Ruby 1.9 or 2.0 at https://www.ruby-lang.org/en/downloads/ . We recommend at least 2.0.0-p353, which is patched against [CVE-2013-4164](https://www.ruby-lang.org/en/news/2013/11/22/heap-overflow-in-floating-point-parsing-cve-2013-4164/).
+## 4. Download, compile and install Ruby
+
+Find the latest stable version of Ruby 1.9 or 2.0 at <https://www.ruby-lang.org/en/downloads/>. We recommend at least 2.0.0-p353, which is patched against [CVE-2013-4164](https://www.ruby-lang.org/en/news/2013/11/22/heap-overflow-in-floating-point-parsing-cve-2013-4164/).
 
 ```bash
 cd /tmp
@@ -36,6 +39,7 @@ sudo gem install bundler
 ```
 
 ### 5. Reinstall GitLab gem bundle
+
 Just to be sure we will reinstall the gems used by GitLab. Note that the `bundle install` command [depends on your choice of database](../install/installation.md#install-gems).
 
 ```bash
@@ -44,11 +48,12 @@ sudo -u git -H rm -rf vendor/bundle  # remove existing Gem bundle
 sudo -u git -H bundle install --deployment --without development test mysql aws # Assuming PostgreSQL
 ```
 
-### 6. Start GitLab
+## 6. Start GitLab
+
 We are now ready to restart GitLab.
 
 ```bash
 sudo service gitlab start
 ```
 
-### Done
+## Done
diff --git a/doc/update/upgrader.md b/doc/update/upgrader.md
index 19faca4ec4e..00dc87e2f99 100644
--- a/doc/update/upgrader.md
+++ b/doc/update/upgrader.md
@@ -1,22 +1,25 @@
-# GitLab Upgrader 
+# GitLab Upgrader
 
 GitLab Upgrader - a ruby script that allows you easily upgrade GitLab to latest minor version.
+
 For example it can update your application from 6.4 to latest GitLab 6 version (like 6.6.1).
-You still need to create a a backup and manually restart GitLab after runnning the script but all other operations are done by this upgrade script.
+
+You still need to create a backup and manually restart GitLab after running the script but all other operations are done by this upgrade script.
+
 If you have local changes to your GitLab repository the script will stash them and you need to use `git stash pop` after running the script.
 
-__GitLab Upgrader is available only for GitLab version 6.4.2 or higher__
+**GitLab Upgrader is available only for GitLab version 6.4.2 or higher.**
 
-### 0. Backup
+## 0. Backup
 
     cd /home/git/gitlab
     sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production
 
-### 1. Stop server
+## 1. Stop server
 
     sudo service gitlab stop
 
-### 2. Run gitlab upgrade tool
+## 2. Run GitLab upgrade tool
 
     # Starting with GitLab version 7.0 upgrader script has been moved to bin directory
     cd /home/git/gitlab
@@ -25,12 +28,12 @@ __GitLab Upgrader is available only for GitLab version 6.4.2 or higher__
     # to perform a non-interactive install (no user input required) you can add -y
     # if [ -f bin/upgrade.rb ]; then sudo -u git -H ruby bin/upgrade.rb -y; else sudo -u git -H ruby script/upgrade.rb -y; fi
 
-### 3. Start application
+## 3. Start application
 
     sudo service gitlab start
     sudo service nginx restart
 
-### 4. Check application status
+## 4. Check application status
 
 Check if GitLab and its dependencies are configured correctly:
 
@@ -38,9 +41,10 @@ Check if GitLab and its dependencies are configured correctly:
 
 If all items are green, then congratulations upgrade is complete!
 
-### 5. Upgrade GitLab Shell (if needed)
+## 5. Upgrade GitLab Shell (if needed)
+
+If the `gitlab:check` task reports an outdated version of `gitlab-shell` you should upgrade it.
 
-If the `gitlab:check` task reports an outdated version of gitlab-shell you should upgrade it.
 Upgrade it by running the commands below after replacing 1.9.4 with the correct version number:
 
 ```
@@ -49,9 +53,10 @@ sudo -u git -H git fetch
 sudo -u git -H git checkout v1.9.4
 ```
 
-### One line upgrade command
+## One line upgrade command
 
 You've read through the entire guide and probably already did all the steps one by one.
+
 Here is a one line command with step 1 to 4 for the next time you upgrade:
 
 ```bash