Reorg CE Docs landing page

3 files changed, 214 insertions, 95 deletions

diff --git a/doc/README.md b/doc/README.md
index fb393aa09a1..6406040da4b 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,80 +1,195 @@
 # GitLab Community Edition
 
-All technical content published by GitLab lives in the documentation, including:
+[GitLab](https://about.gitlab.com/) is a Git-based fully featured platform
+for software development.
 
-- **General Documentation**
-  - [User docs](#user-documentation): general documentation dedicated to regular users of GitLab
-  - [Admin docs](#administrator-documentation): general documentation dedicated to administrators of GitLab instances
-  - [Contributor docs](#contributor-documentation): general documentation on how to develop and contribute to GitLab
-- [GitLab University](university/README.md): guides to learn Git and GitLab
-  through courses and videos.
+**GitLab Community Edition (CE)** is an opensource product, self-hosted, free to use.
+All [GitLab products](https://about.gitlab.com/products/) contain the features
+available in GitLab CE. Premium features are available in
+[GitLab Enterprise Edition (EE)](https://about.gitlab.com/gitlab-ee/).
 
-## User documentation
+----
 
-- [Account Security](user/profile/account/two_factor_authentication.md) Securing your account via two-factor authentication, etc.
-- [API](api/README.md) Automate GitLab via a simple and powerful API.
-- [CI/CD](ci/README.md) GitLab Continuous Integration (CI) and Continuous Delivery (CD) getting started, `.gitlab-ci.yml` options, and examples.
-- [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry.
-- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and  merge requests.
-- [Git Attributes](user/project/git_attributes.md) Managing Git attributes using a `.gitattributes` file.
-- [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf) Download a PDF describing the most used Git operations.
-- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab.
-- [GitLab basics](gitlab-basics/README.md) Find step by step how to start working on your commandline and on GitLab.
-- [GitLab Pages](user/project/pages/index.md) Using GitLab Pages.
+Shortcuts to GitLab's most visited docs:
+
+| [GitLab CI](ci/README.md) | Other |
+| :----- | :----- |
+| [Quick start guide](ci/quick_start/README.md) | [API](api/README.md) |
+| [Configuring `.gitlab-ci.yml`](ci/yaml/README.md) | [SSH authentication](ssh/README.md) |
+| [Using Docker images](ci/docker/using_docker_images.md) | [GitLab Pages](user/project/pages/index.md) |
+
+## Getting started with GitLab
+
+- [GitLab Basics](gitlab-basics/README.md): Start working on your command line and on GitLab.
+- [GitLab Workflow](workflow/README.md): Enhance your workflow with the best of GitLab Workflow.
+  - See also [GitLab Workflow - an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/).
+- [GitLab Markdown](user/markdown.md): GitLab's advanced formatting system (GitLab Flavored Markdown).
+- [GitLab Slash Commands](user/project/slash_commands.md): Textual shortcuts for common actions on issues or merge requests that are usually done by clicking buttons or dropdowns in GitLab's UI.
+
+### User account
+
+- [Authentication](topics/authentication/index.md): Account security with two-factor authentication, setup your ssh keys and deploy keys for secure access to your projects.
+- [Profile settings](profile/README.md): Manage your profile settings, two factor authentication and more.
+- [User permissions](user/permissions.md): Learn what each role in a project (external/guest/reporter/developer/master/owner) can do.
+
+### Projects and groups
+
+- [Create a project](gitlab-basics/create-project.md)
+- [Fork a project](gitlab-basics/fork-project.md)
 - [Importing and exporting projects between instances](user/project/settings/import_export.md).
-- [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
-- [Markdown](user/markdown.md) GitLab's advanced formatting system.
-- [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab.
-- [Permissions](user/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do.
-- [Profile Settings](profile/README.md)
-- [Project Services](user/project/integrations/project_services.md) Integrate a project with external services, such as CI and chat.
-- [Public access](public_access/public_access.md) Learn how you can allow public and internal access to projects.
+- [Project access](public_access/public_access.md): Setting up your project's visibility to public, internal, or private.
+- [Groups](workflow/groups.md): Organize your projects in groups.
+  - [Create a group](gitlab-basics/create-group.md)
+  - [GitLab Subgroups](user/group/subgroups/index.md)
 - [Search through GitLab](user/search/index.md): Search for issues, merge requests, projects, groups, todos, and issues in Issue Boards.
-- [Snippets](user/snippets.md) Snippets allow you to create little bits of code.
-- [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects.
-- [Webhooks](user/project/integrations/webhooks.md) Let GitLab notify you when new code has been pushed to your project.
-- [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN.
+
+### Repository
+
+Manage files and branches from the UI (user interface):
+
+- Files
+  - [Create a file](user/project/repository/web_editor.md#create-a-file)
+  - [Upload a file](user/project/repository/web_editor.md#upload-a-file)
+  - [File templates](user/project/repository/web_editor.md#template-dropdowns)
+  - [Create a directory](user/project/repository/web_editor.md#create-a-directory)
+  - [Start a merge request](user/project/repository/web_editor.md#tips) (when committing via UI)
+- Branches
+  - [Create a branch](user/project/repository/web_editor.md#create-a-new-branch)
+  - [Protected branches](user/project/protected_branches.md#protected-branches)
+
+### Issues and Merge Requests (MRs)
+
+- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and  merge requests.
+- Issues
+  - [Create an issue](gitlab-basics/create-issue.md#how-to-create-an-issue-in-gitlab)
+  - [Confidential Issues](user/project/issues/confidential_issues.md)
+  - [Automatic issue closing](user/project/issues/automatic_issue_closing.md)
+  - [Issue Boards](user/project/issue_board.md)
+- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests.
+- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles.
+- [Merge Requests](user/project/merge_requests/index.md)
+  - [Work In Progress Merge Requests](user/project/merge_requests/work_in_progress_merge_requests.md)
+  - [Merge Request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue): Resolve discussions, move discussions in a merge request to an issue, only allow merge requests to be merged if all discussions are resolved.
+  - [Checkout merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally)
+  - [Cherry-pick](user/project/merge_requests/cherry_pick_changes.md)
+- [Milestones](user/project/milestones/index.md): Organize issues and merge requests into a cohesive group, optionally setting a due date.
+- [Todos](workflow/todos.md): A chronological list of to-dos that are waiting for your input, all in a simple dashboard.
+
+### Git and GitLab
+
+- [Git](topics/git/index.md): Getting started with Git, branching strategies, Git LFS, advanced use.
+- [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf): Download a PDF describing the most used Git operations.
+- [GitLab Flow](workflow/gitlab_flow.md): explore the best of Git with the GitLab Flow strategy.
+
+### Migrate and import your projects from other platforms
+
+- [Importing to GitLab](workflow/importing/README.md): Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
+- [Migrating from SVN](workflow/importing/migrating_from_svn.md): Convert a SVN repository to Git and GitLab.
+
+## GitLab's superpowers
+
+Take a step ahead and dive into GitLab's advanced features.
+
+- [GitLab Pages](user/project/pages/index.md): Build, test, and deploy your static website with GitLab Pages.
+- [Snippets](user/snippets.md): Snippets allow you to create little bits of code.
+- [Wikis](workflow/project_features.md#wiki): Enhance your repository documentation with built-in wikis.
+
+### Continuous Integration, Delivery, and Deployment
+
+- [GitLab CI](ci/README.md): Explore the features and capabilities of Continuous Integration, Continuous Delivery, and Continuous Deployment with GitLab.
+  - [Auto Deploy](ci/autodeploy/index.md): Configure GitLab CI for the deployment of your application.
+  - [Review Apps](ci/review_apps/index.md): Preview changes to your app right from a merge request.
+- [GitLab Cycle Analytics](user/project/cycle_analytics.md): Cycle Analytics measures the time it takes to go from an [idea to production](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have.
+- [GitLab Container Registry](user/project/container_registry.md): Learn how to use GitLab's built-in Container Registry.
+
+### Automation
+
+- [API](api/README.md): Automate GitLab via a simple and powerful API.
+- [GitLab Webhooks](user/project/integrations/webhooks.md): Let GitLab notify you when new code has been pushed to your project.
+
+### Integrations
+
+- [Project Services](user/project/integrations/project_services.md): Integrate a project with external services, such as CI and chat.
+- [GitLab Integration](integration/README.md): Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication.
+
+----
 
 ## Administrator documentation
 
-- [Access restrictions](user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols) Define which Git access protocols can be used to talk to GitLab
-- [Authentication/Authorization](administration/auth/README.md) Configure external authentication with LDAP, SAML, CAS and additional Omniauth providers.
-- [Container Registry](administration/container_registry.md) Configure Docker Registry with GitLab.
-- [Custom Git hooks](administration/custom_hooks.md) Custom Git hooks (on the filesystem) for when webhooks aren't enough.
-- [Debugging Tips](administration/troubleshooting/debug.md) Tips to debug problems when things go wrong
-- [Environment Variables](administration/environment_variables.md) to configure GitLab.
-- [Git LFS configuration](workflow/lfs/lfs_administration.md)
-- [GitLab Pages configuration](administration/pages/index.md) Configure GitLab Pages.
-- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics.
-- [GitLab performance monitoring with Prometheus](administration/monitoring/prometheus/index.md) Configure GitLab and Prometheus for measuring performance metrics.
-- [Header logo](customization/branded_page_and_email_header.md) Change the logo on the overall page and email header.
-- [High Availability](administration/high_availability/README.md) Configure multiple servers for scaling or high availability.
-- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast.
-- [Install](install/README.md) Requirements, directory structures and installation from source.
-- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter.
-- [Issue closing pattern](administration/issue_closing_pattern.md) Customize how to close an issue from commit messages.
-- [Koding](administration/integration/koding.md) Set up Koding to use with GitLab.
-- [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars.
-- [Log system](administration/logs.md) Log system.
-- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
-- [Monitoring uptime](user/admin_area/monitoring/health_check.md) Check the server status using the health check endpoint.
-- [Operations](administration/operations.md) Keeping GitLab up and running.
-- [Polling](administration/polling.md) Configure how often the GitLab UI polls for updates
-- [Raketasks](raketasks/README.md) Backups, maintenance, automatic webhook setup and the importing of projects.
-- [Reply by email](administration/reply_by_email.md) Allow users to comment on issues and merge requests by replying to notification emails.
-- [Repository checks](administration/repository_checks.md) Periodic Git repository checks.
-- [Repository storage paths](administration/repository_storage_paths.md) Manage the paths used to store repositories.
-- [Request Profiling](administration/monitoring/performance/request_profiling.md) Get a detailed profile on slow requests.
-- [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components.
-- [Security](security/README.md) Learn what you can do to further secure your GitLab instance.
-- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md) Debug when Sidekiq appears hung and is not processing jobs.
-- [System hooks](system_hooks/system_hooks.md) Notifications when users, projects and keys are changed.
-- [Update](update/README.md) Update guides to upgrade your installation.
+Learn how to administer your GitLab instance. Regular users don't
+have access to GitLab administration tools and settings.
+
+### Install, update, upgrade, migrate
+
+- [Install](install/README.md): Requirements, directory structures and installation from source.
+- [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/): Integrate [Mattermost](https://about.mattermost.com/) with your GitLab installation.
+- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md): If you have an old GitLab installation (older than 8.0), follow this guide to migrate your existing GitLab CI data to GitLab CE/EE.
+- [Restart GitLab](administration/restart_gitlab.md): Learn how to restart GitLab and its components.
+- [Update](update/README.md): Update guides to upgrade your installation.
+
+### User permissions
+
+- [Access restrictions](user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab
+- [Authentication/Authorization](topics/authentication/index.md#gitlab-administrators): Enforce 2FA, configure external authentication with LDAP, SAML, CAS and additional Omniauth providers.
+
+### GitLab admins' superpowers
+
+- [Container Registry](administration/container_registry.md): Configure Docker Registry with GitLab.
+- [Custom Git hooks](administration/custom_hooks.md): Custom Git hooks (on the filesystem) for when webhooks aren't enough.
+- [Git LFS configuration](workflow/lfs/lfs_administration.md): Learn how to use LFS under GitLab.
+- [GitLab Pages configuration](administration/pages/index.md): Configure GitLab Pages.
+- [High Availability](administration/high_availability/README.md): Configure multiple servers for scaling or high availability.
 - [User cohorts](user/admin_area/user_cohorts.md) View user activity over time.
-- [Web terminals](administration/integration/terminal.md) Provide terminal access to environments from within GitLab.
-- [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page.
+- [Web terminals](administration/integration/terminal.md): Provide terminal access to environments from within GitLab.
+- GitLab CI
+    - [CI admin settings](user/admin_area/settings/continuous_integration.md): Define max artifacts size and expiration time.
+
+### Integrations
+
+- [Integrations](integration/README.md): How to integrate with systems such as JIRA, Redmine, Twitter.
+- [Koding](administration/integration/koding.md): Set up Koding to use with GitLab.
+- [Mattermost](user/project/integrations/mattermost.md): Set up GitLab with Mattermost.
+
+### Monitoring
+
+- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md): Configure GitLab and InfluxDB for measuring performance metrics.
+- [GitLab performance monitoring with Prometheus](administration/monitoring/prometheus/index.md): Configure GitLab and Prometheus for measuring performance metrics.
+- [Monitoring uptime](user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint.
+
+### Performance
+
+- [Housekeeping](administration/housekeeping.md): Keep your Git repository tidy and fast.
+- [Operations](administration/operations.md): Keeping GitLab up and running.
+- [Polling](administration/polling.md): Configure how often the GitLab UI polls for updates.
+- [Request Profiling](administration/monitoring/performance/request_profiling.md): Get a detailed profile on slow requests.
+
+### Customization
+
+- [Adjust your instance's timezone](workflow/timezone.md): Customize the default time zone of GitLab.
+- [Environment variables](administration/environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab.
+- [Header logo](customization/branded_page_and_email_header.md): Change the logo on the overall page and email header.
+- [Issue closing pattern](administration/issue_closing_pattern.md): Customize how to close an issue from commit messages.
+- [Libravatar](customization/libravatar.md): Use Libravatar instead of Gravatar for user avatars.
+- [Welcome message](customization/welcome_message.md): Add a custom welcome message to the sign-in page.
+
+### Admin tools
+
+- [Raketasks](raketasks/README.md): Backups, maintenance, automatic webhook setup and the importing of projects.
+    - [Backup and restore](raketasks/backup_restore.md): Backup and restore your GitLab instance.
+- [Reply by email](administration/reply_by_email.md): Allow users to comment on issues and merge requests by replying to notification emails.
+- [Repository checks](administration/repository_checks.md): Periodic Git repository checks.
+- [Repository storage paths](administration/repository_storage_paths.md): Manage the paths used to store repositories.
+- [Security](security/README.md): Learn what you can do to further secure your GitLab instance.
+- [System hooks](system_hooks/system_hooks.md): Notifications when users, projects and keys are changed.
+
+### Troubleshooting
+
+- [Debugging tips](administration/troubleshooting/debug.md): Tips to debug problems when things go wrong
+- [Log system](administration/logs.md): Where to look for logs.
+- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md): Debug when Sidekiq appears hung and is not processing jobs.
 
 ## Contributor documentation
 
-- [Development](development/README.md) All styleguides and explanations how to contribute.
-- [Legal](legal/README.md) Contributor license agreements.
+- [Development](development/README.md): All styleguides and explanations how to contribute.
+- [Legal](legal/README.md): Contributor license agreements.
+- [Writing documentation](development/writing_documentation.md): Contributing to GitLab Docs.
diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md
index 8f9ef054949..2e7782736ff 100644
--- a/doc/migrate_ci_to_ce/README.md
+++ b/doc/migrate_ci_to_ce/README.md
@@ -1,4 +1,4 @@
-## Migrate GitLab CI to GitLab CE or EE
+# Migrate GitLab CI to GitLab CE or EE
 
 Beginning with version 8.0 of GitLab Community Edition (CE) and Enterprise
 Edition (EE), GitLab CI is no longer its own application, but is instead built
@@ -12,7 +12,7 @@ is not possible.**
 We recommend that you read through the entire migration process in this
 document before beginning.
 
-### Overview
+## Overview
 
 In this document we assume you have a GitLab server and a GitLab CI server. It
 does not matter if these are the same machine.
@@ -26,7 +26,7 @@ can be online for most of the procedure; the only GitLab downtime (if any) is
 during the upgrade to 8.0. Your CI service will be offline from the moment you
 upgrade to 8.0 until you finish the migration procedure.
 
-### Before upgrading
+## Before upgrading
 
 If you have GitLab CI installed using omnibus-gitlab packages but **you don't want to migrate your existing data**:
 
@@ -38,12 +38,12 @@ run `sudo gitlab-ctl reconfigure` and you can reach CI at `gitlab.example.com/ci
 
 If you want to migrate your existing data, continue reading.
 
-#### 0. Updating Omnibus from versions prior to 7.13
+### 0. Updating Omnibus from versions prior to 7.13
 
 If you are updating from older versions you should first update to 7.14 and then to 8.0.
 Otherwise it's pretty likely that you will encounter problems described in the [Troubleshooting](#troubleshooting).
 
-#### 1. Verify that backups work
+### 1. Verify that backups work
 
 Make sure that the backup script on both servers can connect to the database.
 
@@ -73,7 +73,7 @@ sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=r
 If this fails you need to fix it before upgrading to 8.0. Also see
 https://about.gitlab.com/getting-help/
 
-#### 2. Check source and target database types
+### 2. Check source and target database types
 
 Check what databases you use on your GitLab server and your CI server.
   Look for the 'adapter:' line. If your CI server and your GitLab server use
@@ -102,7 +102,7 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production
 ```
 
-#### 3. Storage planning
+### 3. Storage planning
 
 Decide where to store CI build traces on GitLab server. GitLab CI uses
   files on disk to store CI build traces. The default path for these build
@@ -111,34 +111,34 @@ traces is `/var/opt/gitlab/gitlab-ci/builds` (Omnibus) or
 a special location, or if you are using NFS, you should make sure that you
 store build traces on the same storage as your Git repositories.
 
-### I. Upgrading
+## I. Upgrading
 
 From this point on, GitLab CI will be unavailable for your end users.
 
-#### 1. Upgrade GitLab to 8.0
+### 1. Upgrade GitLab to 8.0
 
 First upgrade your GitLab server to version 8.0:
 https://about.gitlab.com/update/
 
-#### 2. Disable CI on the GitLab server during the migration
+### 2. Disable CI on the GitLab server during the migration
 
 After you update, go to the admin panel and temporarily disable CI.  As
   an administrator, go to **Admin Area** -> **Settings**, and under
 **Continuous Integration** uncheck **Disable to prevent CI usage until rake
 ci:migrate is run (8.0 only)**.
 
-#### 3. CI settings are now in GitLab
+### 3. CI settings are now in GitLab
 
 If you want to use custom CI settings (e.g. change where builds are
   stored), please update `/etc/gitlab/gitlab.rb` (Omnibus) or
 `/home/git/gitlab/config/gitlab.yml` (Source).
 
-#### 4. Upgrade GitLab CI to 8.0
+### 4. Upgrade GitLab CI to 8.0
 
 Now upgrade GitLab CI to version 8.0. If you are using Omnibus packages,
   this may have already happened when you upgraded GitLab to 8.0.
 
-#### 5. Disable GitLab CI on the CI server
+### 5. Disable GitLab CI on the CI server
 
 Disable GitLab CI after upgrading to 8.0.
 
@@ -154,9 +154,9 @@ cd /home/gitlab_ci/gitlab-ci
 sudo -u gitlab_ci -H bundle exec whenever --clear-crontab RAILS_ENV=production
 ```
 
-### II. Moving data
+## II. Moving data
 
-#### 1. Database encryption key
+### 1. Database encryption key
 
 Move the database encryption key from your CI server to your GitLab
   server. The command below will show you what you need to copy-paste to your
@@ -174,7 +174,7 @@ cd /home/gitlab_ci/gitlab-ci
 sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production
 ```
 
-#### 2. SQL data and build traces
+### 2. SQL data and build traces
 
 Create your final CI data export. If you are converting from MySQL to
   PostgreSQL, add ` MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When
@@ -192,7 +192,7 @@ cd /home/gitlab_ci/gitlab-ci
 sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production
 ```
 
-#### 3. Copy data to the GitLab server
+### 3. Copy data to the GitLab server
 
 If you were running GitLab and GitLab CI on the same server you can skip this
 step.
@@ -209,7 +209,7 @@ ssh -A ci_admin@ci_server.example
 scp /path/to/12345_gitlab_ci_backup.tar gitlab_admin@gitlab_server.example:~
 ```
 
-#### 4. Move data to the GitLab backups folder
+### 4. Move data to the GitLab backups folder
 
 Make the CI data archive discoverable for GitLab. We assume below that you
 store backups in the default path, adjust the command if necessary.
@@ -223,7 +223,7 @@ sudo mv /path/to/12345_gitlab_ci_backup.tar /var/opt/gitlab/backups/
 sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/
 ```
 
-#### 5. Import the CI data into GitLab.
+### 5. Import the CI data into GitLab.
 
 This step will delete any existing CI data on your GitLab server. There should
 be no CI data yet because you turned CI on the GitLab server off earlier.
@@ -239,7 +239,7 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rake ci:migrate RAILS_ENV=production
 ```
 
-#### 6. Restart GitLab
+### 6. Restart GitLab
 
 ```
 # On your GitLab server:
@@ -251,7 +251,7 @@ sudo gitlab-ctl restart sidekiq
 sudo service gitlab reload
 ```
 
-### III. Redirecting traffic
+## III. Redirecting traffic
 
 If you were running GitLab CI with Omnibus packages and you were using the
 internal NGINX configuration your CI service should now be available both at
@@ -261,7 +261,7 @@ If you installed GitLab CI from source we now need to configure a redirect in
 NGINX so that existing CI runners can keep using the old CI server address, and
 so that existing links to your CI server keep working.
 
-#### 1. Update Nginx configuration
+### 1. Update Nginx configuration
 
 To ensure that your existing CI runners are able to communicate with the
 migrated installation, and that existing build triggers still work, you'll need
@@ -317,22 +317,22 @@ You should also make sure that you can:
 1. `curl https://YOUR_GITLAB_SERVER_FQDN/` from your previous GitLab CI server.
 1. `curl https://YOUR_CI_SERVER_FQDN/` from your GitLab CE (or EE) server.
 
-#### 2. Check Nginx configuration
+### 2. Check Nginx configuration
 
     sudo nginx -t
 
-#### 3. Restart Nginx
+### 3. Restart Nginx
 
     sudo /etc/init.d/nginx restart
 
-#### Restore from backup
+### Restore from backup
 
 If something went wrong and you need to restore a backup, consult the [Backup
 restoration](../raketasks/backup_restore.md) guide.
 
-### Troubleshooting
+## Troubleshooting
 
-#### show:secrets problem (Omnibus-only)
+### show:secrets problem (Omnibus-only)
 If you see errors like this:
 ```
 Missing `secret_key_base` or `db_key_base` for 'production' environment. The secrets will be generated and stored in `config/secrets.yml`
@@ -343,7 +343,7 @@ Errno::EACCES: Permission denied @ rb_sysopen - config/secrets.yml
 This can happen if you are updating from versions prior to 7.13 straight to 8.0.
 The fix for this is to update to Omnibus 7.14 first and then update it to 8.0.
 
-#### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds
+### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds
 To fix that issue you have to change builds/ folder permission before doing final backup:
 ```
 sudo chown -R gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds
@@ -354,7 +354,7 @@ Then before executing `ci:migrate` you need to fix builds folder permission:
 sudo chown git:git /var/opt/gitlab/gitlab-ci/builds
 ```
 
-#### Problems when importing CI database to GitLab
+### Problems when importing CI database to GitLab
 If you were migrating CI database from MySQL to PostgreSQL manually you can see errors during import about missing sequences:
 ```
 ALTER SEQUENCE
diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md
index b99ba317a43..d13066c9015 100644
--- a/doc/topics/git/index.md
+++ b/doc/topics/git/index.md
@@ -17,6 +17,10 @@ We've gathered some resources to help you to get the best from Git with GitLab.
 - [Start using Git on the command line](../../gitlab-basics/start-using-git.md)
 - [Command Line basic commands](../../gitlab-basics/command-line-commands.md)
 - [GitLab Git Cheat Sheet (download)](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf)
+- Commits
+  - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) 
+  - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit)
+  - [Squashing commits](../../workflow/gitlab_flow.md#squashing-commits-with-rebase)
 - **Articles:**
   - [Git Tips & Tricks](https://about.gitlab.com/2016/12/08/git-tips-and-tricks/)
   - [Eight Tips to help you work better with Git](https://about.gitlab.com/2015/02/19/8-tips-to-help-you-work-better-with-git/)