diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md
index d6c0e624dfb0025c8bdd120267a534191c268a8a..6aa7be93c01d60029c2a96eed1c3d73d1bfa6413 100644
--- a/doc/api/deploy_keys.md
+++ b/doc/api/deploy_keys.md
@@ -1,4 +1,4 @@
-## Deploy Keys
+# Deploy Keys
### List deploy keys
diff --git a/doc/api/groups.md b/doc/api/groups.md
index f5f5d7690509cccd3184caefb53284d4c32222b2..1dbb93f9082d38a807ec47120ae9d2aa5cd265c8 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -1,3 +1,5 @@
+# Groups
+
## List project groups
Get a list of groups. (As user: my groups, as admin: all groups)
diff --git a/doc/api/issues.md b/doc/api/issues.md
index d18506f9ce6a6c4836a4305087f0a8f16913393e..c769d7bb69abdbb5904d9eda12fbc115606a6c74 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -1,3 +1,5 @@
+# Issues
+
## List issues
Get all issues created by authenticated user. This function takes pagination parameters
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index d68f34971f1be9bb948bd44e55e75b6acdaa1060..284c2befe6fff2f24086019a177a0e50e1631dfb 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -1,3 +1,5 @@
+# Merge requests
+
## List merge requests
Get all merge requests for this project.
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 2a2ef4b79b1d205b408cd379f6a74c9c9ed8ecbc..b0f355b9a0c88c0d92a9769daab19f01a0866896 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -1,3 +1,5 @@
+# Milestones
+
## List project milestones
Returns a list of project milestones.
diff --git a/doc/api/notes.md b/doc/api/notes.md
index e9ad6e00c73164c1c009e0afa8e43045f396ba4e..6d140643fcbc6b00ff840320692420ec2e2aa742 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -1,3 +1,5 @@
+# Notes
+
Notes can be wall notes or comments on snippets, issues or merge requests.
## Wall
diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md
index e16e1e845963ea298b3b58c078f66e9f822eeda2..7a49827233422b75eb323b42cc7709b9a41f1d72 100644
--- a/doc/api/project_snippets.md
+++ b/doc/api/project_snippets.md
@@ -1,3 +1,5 @@
+# Project snippets
+
## List snippets
Get a list of project snippets.
diff --git a/doc/api/projects.md b/doc/api/projects.md
index ffaba0af7fe40ed9d113c1fac61ecb56ac161247..ae2b8365e80fc771540d954d4c20c06bb73ac712 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -1,4 +1,4 @@
-## Projects
+# Projects
### List projects
diff --git a/doc/api/repositories.md b/doc/api/repositories.md
index e9120e17bb82de27db4c4adc926945489988f317..ecb0fa3f6a0d1e873db488388dd510398d1bbee7 100644
--- a/doc/api/repositories.md
+++ b/doc/api/repositories.md
@@ -1,3 +1,5 @@
+# Repositories
+
## List project repository tags
Get a list of repository tags from a project, sorted by name in reverse alphabetical order.
diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md
index b215cc25001978bd567aef36d7fd92318e97147d..820ae71361dfa50bdd3a5c32145eb25b5e6ff746 100644
--- a/doc/api/repository_files.md
+++ b/doc/api/repository_files.md
@@ -1,4 +1,6 @@
-# CRUD for repository files
+# Repository files
+
+## CRUD for repository files
## Create, read, update and delete repository files using this API
diff --git a/doc/api/session.md b/doc/api/session.md
index 0be5af79dad924a4faa98fbe9db962bef06bdab3..2e717a2ea77999d9023b3131d1c3705315f379ff 100644
--- a/doc/api/session.md
+++ b/doc/api/session.md
@@ -1,3 +1,5 @@
+# Session
+
Login to get private token
```
diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md
index d4c45ea9bbd9f3caef8f5333fb4c2ec7abf2fb1f..0d33aee21339f03c785c56372264ec3bbf911d01 100644
--- a/doc/api/system_hooks.md
+++ b/doc/api/system_hooks.md
@@ -1,3 +1,5 @@
+# System hooks
+
All methods require admin authorization.
The url endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks).
diff --git a/doc/api/users.md b/doc/api/users.md
index 2b927c30777349fcf78f68319058c17d08cf4bfc..c185cf6478a3e5e3537ceb3886be1d5266a41ec3 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -1,3 +1,5 @@
+# Users
+
## List users
Get a list of users.
diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md
index bf8183729e7fb689e3fcdba8ddc8a40f9e9ae6e7..270ad3b0b86b29c4c388741cb8779d524200a584 100644
--- a/doc/install/database_mysql.md
+++ b/doc/install/database_mysql.md
@@ -1,3 +1,5 @@
+# Database Mysql
+
## Note
We do not recommend using MySQL due to various issues. For example, case [(in)sensitivity](https://dev.mysql.com/doc/refman/5.0/en/case-sensitivity.html) and [problems](http://bugs.mysql.com/bug.php?id=65830) that [suggested](http://bugs.mysql.com/bug.php?id=50909) [fixes](http://bugs.mysql.com/bug.php?id=65830) [have](http://bugs.mysql.com/bug.php?id=63164).
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 44f5a28fde5e1309e62def117221360532622cfc..73fef0dadfeba05de01300cd67bd7b8764f7b6f0 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -1,3 +1,5 @@
+# Installation
+
# Select Version to Install
Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install. In most cases
this should be the highest numbered stable branch (example shown below).
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index fd2dd16cd8eb4cad399e0638b0655d8428c06c50..2830a75df52bbc6c4a0efef78506fe2a933ef72f 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -1,4 +1,6 @@
-# Operating Systems
+# Requirements
+
+## Operating Systems
GitLab is developed for the Linux operating system. For the installations options and instructions please see [the installation section of the readme](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/README.md#installation).
diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md
index fb8d52e6bd41fa2eb9e365b77555f5a0ee384b5e..eb808d8a761fd4e26e16156811deb6f950090a74 100644
--- a/doc/legal/corporate_contributor_license_agreement.md
+++ b/doc/legal/corporate_contributor_license_agreement.md
@@ -1,3 +1,5 @@
+# Corporate contributor license agreement
+
You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions.
1. Definitions.
diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md
index 7ac9d6e4cde7834cfdbd135dde29d3b6ec4bdb5c..95cbed7e75bb72db3d93120156234c120e87aa31 100644
--- a/doc/legal/individual_contributor_license_agreement.md
+++ b/doc/legal/individual_contributor_license_agreement.md
@@ -1,3 +1,5 @@
+# Individual contributor license agreement
+
You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions.
1. Definitions.
diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md
index e7ebc613431c6b71cf1d100cf14f3b35b83befa7..47cb04cdb0484a188bf2823cab9346ad79c90538 100644
--- a/doc/markdown/markdown.md
+++ b/doc/markdown/markdown.md
@@ -1,3 +1,5 @@
+# Markdown
+
----------------------------------------------
Table of Contents
diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md
index 9a3dcefe5698f8f054fbaede291e7acb75658bb1..840bb90163b1ec3e015fbc39a507432db1c48c7c 100644
--- a/doc/permissions/permissions.md
+++ b/doc/permissions/permissions.md
@@ -1,3 +1,5 @@
+# Permissions
+
Users have different abilities depending on the access level they have in a particular group or project.
If a user is both in a project group and in the project itself, the highest permission level is used.
If a user is a GitLab administrator they receive all permissions.
diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md
index bb23a4bfd96faa4371f6e75f5436972ed5827872..1714a7eeae48b69696c9404f697f8957010508be 100644
--- a/doc/public_access/public_access.md
+++ b/doc/public_access/public_access.md
@@ -1,3 +1,5 @@
+# Public access
+
Gitlab allows you to open selected projects to be accessed **publicly** or **internally**.
Projects with either of these visibility levels will be listen in the [public access directory](/public).
Internal projects will only be available to authenticated users.
diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md
index bdff6ad5da8f07d4a4436f4237592d18bbbd11cf..f0be2b6a44187ba19c7c065445d5429d6be3a2d9 100644
--- a/doc/raketasks/backup_restore.md
+++ b/doc/raketasks/backup_restore.md
@@ -1,3 +1,5 @@
+# Backup restore
+
### Create a backup of the GitLab system
Creates a backup archive of the database and all repositories. This archive will be saved in backup_path (see `config/gitlab.yml`).
diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md
index 99809ef434df7212d31a144f09596ae2c67c8011..b0b82754da688f1dbfec64ee4e978b908bffe8fc 100644
--- a/doc/raketasks/cleanup.md
+++ b/doc/raketasks/cleanup.md
@@ -1,3 +1,5 @@
+# Cleanup
+
### Remove garbage from filesystem. Important! Data loss!
Remove namespaces(dirs) from `/home/git/repositories` if they don't exist in GitLab database.
diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md
index e11328dc5ce7d15e257d9391f748c35f06e46ab4..628bd373b8d7c09f4160ca6f9943b5651e06d018 100644
--- a/doc/raketasks/import.md
+++ b/doc/raketasks/import.md
@@ -1,3 +1,5 @@
+# Import
+
### Import bare repositories into GitLab project instance
Notes:
diff --git a/doc/raketasks/maintenance.md b/doc/raketasks/maintenance.md
index 907c9352c59763aea7d1670b2e4afacd3375dfc3..da58962499b7156af7f8c0c884888061af630c4e 100644
--- a/doc/raketasks/maintenance.md
+++ b/doc/raketasks/maintenance.md
@@ -1,3 +1,5 @@
+# Maintenance
+
### Gather information about GitLab and the system it runs on
This command gathers information about your GitLab installation and the System
diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md
index e82320829166a73d5d24ff06e13128cf8ea9aac6..d5b173fde65b116600486bbc278a60e17639faf0 100644
--- a/doc/raketasks/user_management.md
+++ b/doc/raketasks/user_management.md
@@ -1,3 +1,5 @@
+# User management
+
### Add user as a developer to all projects
```bash
diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md
index 1ca5bacb9d104050c6317ce8e76a46759c6eca32..4ffbf5f8698a6102cc9d262dde7963dca5263204 100644
--- a/doc/raketasks/web_hooks.md
+++ b/doc/raketasks/web_hooks.md
@@ -1,3 +1,5 @@
+# Web hooks
+
### Add a web hook for **ALL** projects:
RAILS_ENV=production bundle exec rake gitlab:web_hook:add URL="http://example.com/hook"
diff --git a/doc/release/monthly.md b/doc/release/monthly.md
index 5e85fe0825ef7b8504e60cabc1f4eafc72a4eef0..71cd56a099983ff9f6fdc2a7508cd3cf806132e5 100644
--- a/doc/release/monthly.md
+++ b/doc/release/monthly.md
@@ -1,4 +1,5 @@
# Monthly Release
+
NOTE: This is a guide for GitLab developers.
# **15th - Code Freeze & Release Manager**
diff --git a/doc/release/patch.md b/doc/release/patch.md
index 30bb39b4e49d617cf488153b050bca3515cdf549..6d8866a0cfbe74787a91d90ac00c328e8b543247 100644
--- a/doc/release/patch.md
+++ b/doc/release/patch.md
@@ -1,4 +1,5 @@
# Things to do when doing a patch release
+
NOTE: This is a guide for GitLab developers. If you are trying to install GitLab see the latest stable [installation guide](install/installation.md) and if you are trying to upgrade, see the [upgrade guides](update).
## When to do a patch release
diff --git a/doc/release/security.md b/doc/release/security.md
index 2fe0a948ad2fe95433d374fcd4f3383c307a6505..ac2f79dfb9284ff872927b31a3909b67036183e3 100644
--- a/doc/release/security.md
+++ b/doc/release/security.md
@@ -1,4 +1,5 @@
# Things to do when doing an out-of-bound security release
+
NOTE: This is a guide for GitLab developers. If you are trying to install GitLab see the latest stable [installation guide](install/installation.md) and if you are trying to upgrade, see the [upgrade guides](update).
## When to do a security release
diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md
index a0d02b1650f3e4453451fb1de424a1e665267dbd..9e863bbd19018778a272451c55f20f4e550d1ff0 100644
--- a/doc/security/rack_attack.md
+++ b/doc/security/rack_attack.md
@@ -1,3 +1,5 @@
+# Rack attack
+
To prevent abusive clients doing damage GitLab uses rack-attack gem.
If you installed or upgraded GitLab by following the official guides this should be enabled by default.
If you are missing `config/initializers/rack_attack.rb` the following steps need to be taken in order to enable protection for your GitLab instance:
@@ -16,4 +18,4 @@ If you want more restrictive/relaxed throttle rule change the `limit` or `period
In case you find throttling is not enough to protect you against abusive clients, rack-attack gem offers IP whitelisting, blacklisting, Fail2ban style filter and tracking.
-For more information on how to use these options check out [rack-attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md).
\ No newline at end of file
+For more information on how to use these options check out [rack-attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md).
diff --git a/doc/ssh/deploy_keys.md b/doc/ssh/deploy_keys.md
index c7125b7949e7be3e9029f87857d3a7f0e203876a..e113160c9bc1ef637455bf90c1f2eae014fda702 100644
--- a/doc/ssh/deploy_keys.md
+++ b/doc/ssh/deploy_keys.md
@@ -1,3 +1,5 @@
+# Deploy keys
+
Deploy keys allow read-only access one or multiple projects with a single SSH key.
This is really useful for cloning repositories to your Continuous Integration (CI) server.
diff --git a/doc/ssh/ssh.md b/doc/ssh/ssh.md
index 0a38bc16b49ce85171a49203fb6fd471785eb8c6..f89b6a14ce1c4110b744ba5e86e69db2fd6779d8 100644
--- a/doc/ssh/ssh.md
+++ b/doc/ssh/ssh.md
@@ -1,3 +1,5 @@
+# SSH keys
+
SSH key allows you to establish a secure connection between your computer and GitLab
diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md
index 5c8daf466ab4382cfae0cc64b430e10482bd97cb..5a1a32c1edbd03fa35f2b6e4ac2a04f15d444d76 100644
--- a/doc/system_hooks/system_hooks.md
+++ b/doc/system_hooks/system_hooks.md
@@ -1,3 +1,5 @@
+# System hooks
+
Your GitLab instance can perform HTTP POST requests on the following events: `create_project`, `delete_project`, `create_user`, `delete_user` and `change_team_member`.
System hooks can be used, e.g. for logging or changing information in a LDAP server.
diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md
index 4c06bc4d44401718e15b0b6b7f199c165241a247..19a60db00ad34d4d65ecebf90c0692047380d353 100644
--- a/doc/web_hooks/web_hooks.md
+++ b/doc/web_hooks/web_hooks.md
@@ -1,3 +1,5 @@
+# Web hooks
+
Project web hooks allow you to trigger an URL if new code is pushed or a new issue is created.
---
diff --git a/doc/workflow/authorization_for_merge_requests.md b/doc/workflow/authorization_for_merge_requests.md
index 4e07d7c04c5dc021f10ee751d5941320424543a8..cc7031b11e143642f6dd9f81751edf7cc248e772 100644
--- a/doc/workflow/authorization_for_merge_requests.md
+++ b/doc/workflow/authorization_for_merge_requests.md
@@ -1,3 +1,5 @@
+# Authorization for Merge requests
+
There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project.
## Protected branch flow
diff --git a/doc/workflow/project_features.md b/doc/workflow/project_features.md
index 64f4ddaa1255aa87dfe5f2c0c43b905fa161d8bf..ec2c273db01ee643217d2dffe0a8c3ab0ad6c7ea 100644
--- a/doc/workflow/project_features.md
+++ b/doc/workflow/project_features.md
@@ -1,3 +1,5 @@
+# Project features
+
When in a Project -> Settings, you will find Features on the bottom of the page that you can toggle.
Below you will find a more elaborate explanation of each of these.
diff --git a/doc/workflow/workflow.md b/doc/workflow/workflow.md
index bb232e9d5c57d733cc06c19b4f4aeb3d2bbc287f..8186cd53b200fb1992adacaf7e52ebe99c3ca35b 100644
--- a/doc/workflow/workflow.md
+++ b/doc/workflow/workflow.md
@@ -1,3 +1,5 @@
+# Workflow
+
1. Clone project
```bash