Perform some documentation cleanup

docs/examples/gitlab.md

-## How to configure runner for GitLab CE integration tests (uses confined Docker executor)
+# How to configure GitLab Runner for GitLab CE integration tests
 
-### 1. Register the runner
+We will register the Runner using a confined Docker executor.
 
 The registration token can be found at `https://gitlab.com/project_namespace/project_name/runners`.
 You can export it as a variable and run the command below as is:
@@ -16,8 +16,6 @@ gitlab-ci-multi-runner register \
 --docker-postgres latest --docker-redis latest
 ```
 
-----
-
 You now have a GitLab CE integration testing instance with bundle caching.
 Push some commits to test it.
 

docs/executors/kubernetes.md

-# The Kubernetes executor (**EXPERIMENTAL**)
+# The Kubernetes executor
+
+>**Note:**
+This executor is **EXPERIMENTAL**.
 
 GitLab Runner can use Kubernetes to run builds on a kubernetes cluster. This is
 possible with the use of the **Kubernetes** executor.
@@ -12,13 +15,6 @@ yaml. The names for these containers are as follows:
 - The build container is `build`
 - The services containers are `svc-X` where `X` is `[0-9]+`
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Workflow
 
 The Kubernetes executor divides the build into multiple steps:

docs/executors/shell.md

@@ -5,18 +5,6 @@ locally to the machine that the Runner is installed. It supports all systems on
 which the Runner can be installed. That means that it's possible to use scripts
 generated for Bash, Windows PowerShell and Windows Batch.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Running as unprivileged user](#running-as-unprivileged-user)
-- [Security](#security)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 The scripts can be run as unprivileged user if the `--user` is added to the

docs/executors/ssh.md

@@ -7,17 +7,6 @@ is currently not supported.
 This is a simple executor that allows you to execute builds on a remote machine
 by executing commands over SSH.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Security](#security)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 To use the SSH executor you need to specify `executor = "ssh"` under the

docs/executors/virtualbox.md

 # VirtualBox
 
-> Note: The Parallels executor works the same as the VirtualBox executor. The
+>**Note:**
+The Parallels executor works the same as the VirtualBox executor. The
 caching feature is currently not supported.
 
 VirtualBox allows you to use VirtualBox's virtualization to provide a clean
@@ -8,19 +9,6 @@ build environment for every build. This executor supports all systems that can
 be run on VirtualBox. The only requirement is that the virtual machine exposes
 its SSH server and provide a bash-compatible shell.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Create a new base virtual machine](#create-a-new-base-virtual-machine)
-- [Create a new Runner](#create-a-new-runner)
-- [How it works](#how-it-works)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 The project's source code is checked out to: `~/builds/<namespace>/<project-name>`.

docs/faq/README.md

 # FAQ
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-
-- [1. Where are logs stored when run as a service?](#1-where-are-logs-stored-when-run-as-a-service)
-- [2. Run in `--debug` mode](#2-run-in---debug-mode)
-- [3. I get a PathTooLongException during my builds on Windows](#3-i-get-a-pathtoolongexception-during-my-builds-on-windows)
-- [4. I'm seeing `x509: certificate signed by unknown authority`](#4-im-seeing-x509-certificate-signed-by-unknown-authority)
-- [5. I get `Permission Denied` when accessing the `/var/run/docker.sock`](#5-i-get-permission-denied-when-accessing-the-varrundockersock)
-- [6. The Docker executor gets timeout when building Java project.](#6-the-docker-executor-gets-timeout-when-building-java-project)
-- [7. I get 411 when uploading artifacts.](#7-i-get-411-when-uploading-artifacts)
-- [8. I can't run Windows BASH scripts; I'm getting `The system cannot find the batch label specified - buildscript`.](#8-i-cant-run-windows-bash-scripts-im-getting-the-system-cannot-find-the-batch-label-specified---buildscript)
-- [9. My gitlab runner is on Windows. How can I get colored output on the web terminal?](#9-my-gitlab-runner-is-on-windows-how-can-i-get-colored-output-on-the-web-terminal)
-- [10. "warning: You appear to have cloned an empty repository."](#10-warning-you-appear-to-have-cloned-an-empty-repository)
-- [11. `"launchctl" failed: exit status 112, Could not find domain for`](#11-launchctl-failed-exit-status-112-could-not-find-domain-for)
-- [12. `Failed to authorize rights (0x1) with status: -60007.`](#12-failed-to-authorize-rights-0x1-with-status--60007)
-- [13. `The service did not start due to a logon failure` error when starting service on Windows](#13-the-service-did-not-start-due-to-a-logon-failure-error-when-starting-service-on-windows)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+Some Frequently Asked Questions about GitLab Runner.
 
 ## 1. Where are logs stored when run as a service?
 
@@ -241,4 +224,4 @@ and the service should be started properly.
 
 [microsoft-manually-set-seservicelogonright]: https://technet.microsoft.com/en-us/library/dn221981
 [microsoft-ntrights-download]: https://www.microsoft.com/en-us/download/details.aspx?id=17657
-[microsoft-ntrights-usage-on-win7]: https://technet.microsoft.com/en-us/library/dd548356(WS.10).aspx
+[microsoft-ntrights-usage-on-win7]: https://technet.microsoft.com/en-us/library/dd548356(WS.10).aspx
\ No newline at end of file

docs/install/autoscaling.md

@@ -5,22 +5,6 @@
 For an overview of the auto-scale architecture, take a look at the
 [comprehensive documentation on auto-scaling](../configuration/autoscale.md).
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Prepare the environment](#prepare-the-environment)
-- [Prepare the Docker Registry and Cache Server](#prepare-the-docker-registry-and-cache-server)
-    - [Install Docker Registry](#install-docker-registry)
-    - [Install the cache server](#install-the-cache-server)
-- [Configure GitLab Runner](#configure-gitlab-runner)
-- [Upgrading the Runner](#upgrading-the-runner)
-- [Manage the Docker Machines](#manage-the-docker-machines)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Prepare the environment
 
 In order to use the auto-scale feature, Docker and GitLab Runner must be

docs/install/bleeding-edge.md

-## Bleeding edge releases (development)
+# Bleeding edge releases
 
-### Download the standalone binaries
+>**Note:**
+These are the latest, probably untested releases of GitLab Runner built straight
+from `master` branch. Use at your own risk.
+
+## Download the standalone binaries
 
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-linux-386
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-linux-amd64
@@ -13,13 +17,13 @@
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-freebsd-amd64
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-freebsd-arm
 
-You can then run the runner with:
+You can then run the Runner with:
 ```bash
 chmod +x gitlab-ci-multi-runner-linux-amd64
 ./gitlab-ci-multi-runner-linux-amd64 run
 ```
 
-### Download one of the packages for Debian or Ubuntu
+## Download one of the packages for Debian or Ubuntu
 
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/deb/gitlab-ci-multi-runner_i386.deb
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/deb/gitlab-ci-multi-runner_amd64.deb
@@ -31,7 +35,7 @@ You can then install it with:
 dpkg -i gitlab-ci-multi-runner_386.deb
 ```
 
-### Download one of the packages for RedHat or CentOS
+## Download one of the packages for RedHat or CentOS
 
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/rpm/gitlab-ci-multi-runner_i686.rpm
 * https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/rpm/gitlab-ci-multi-runner_amd64.rpm
@@ -43,7 +47,7 @@ You can then install it with:
 rpm -i gitlab-ci-multi-runner_386.rpm
 ```
 
-### Download any other tagged release
+## Download any other tagged release
 
 Simply replace `master` with either `tag` (v0.2.0 or 0.4.2) or `latest` (the latest
 stable). For a list of tags see <https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tags>.

docs/install/docker.md

-## Run gitlab-runner in a container
+# Run GitLab Runner in a container
 
-### Docker image installation and configuration
+This is how you can run GitLab Runner inside a Docker container.
+
+## Docker image installation and configuration
 
 Install Docker first:
 
@@ -8,7 +10,7 @@ Install Docker first:
 curl -sSL https://get.docker.com/ | sh
 ```
 
-We need to mount a config volume into our gitlab-runner container to
+We need to mount a config volume into our `gitlab-runner` container to
 be used for configs and other resources:
 
 ```bash
@@ -18,7 +20,7 @@ docker run -d --name gitlab-runner --restart always \
   gitlab/gitlab-runner:latest
 ```
 
-OR you can use a config container to mount your custom data volume:
+Or, you can use a config container to mount your custom data volume:
 
 ```bash
 docker run -d --name gitlab-runner-config \
@@ -31,7 +33,7 @@ docker run -d --name gitlab-runner --restart always \
     gitlab/gitlab-runner:latest
 ```
 
-If you plan on using Docker as the method of spawning runners, you will need to
+If you plan on using Docker as the method of spawning Runners, you will need to
 mount your docker socket like this:
 
 ```bash
@@ -66,7 +68,7 @@ The runner should is started already and you are ready to build your projects!
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
-### Update
+## Update
 
 Pull the latest version:
 
@@ -92,7 +94,7 @@ docker run -d --name gitlab-runner --restart always \
 **Note**: you need to use the same method for mounting you data volume as you
     did originally (`-v /srv/gitlab-runner/config:/etc/gitlab-runner` or `--volumes-from gitlab-runner`)
 
-### Installing Trusted SSL Server Certificates
+## Installing trusted SSL server certificates
 
 If your GitLab CI server is using self-signed SSL certificates then you should
 make sure the GitLab CI server certificate is trusted by the gitlab-ci-multi-runner
@@ -108,7 +110,7 @@ want gitlab-ci-multi-runner to trust. The gitlab-ci-multi-runner container will
 import the `ca.crt` file on startup so if your container is already running you
 may need to restart it for the changes to take effect.
 
-### Alpine Linux
+## Alpine Linux
 
 You can also use alternative [Alpine Linux](https://www.alpinelinux.org/) based image with much smaller footprint:
 ```
@@ -120,7 +122,7 @@ gitlab/gitlab-runner    alpine              7c431ac8f30f        13 hours ago
 
 The original `gitlab/gitlab-runner:latest` is based on Ubuntu 14.04 LTS.
 
-### SELinux
+## SELinux
 
 Some distributions (CentOS, RedHat, Fedora) use SELinux by default to enhance the security of the underlying system.
 
@@ -135,10 +137,10 @@ Install the `selinux-dockersock` and to resolve the issue: https://github.com/dp
 1. Run docker with `:Z` on volumes:
 
 ```bash
-    docker run -d --name gitlab-runner --restart always \
-      -v /var/run/docker.sock:/var/run/docker.sock \
-      -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
-      gitlab/gitlab-runner:latest
+docker run -d --name gitlab-runner --restart always \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
+  gitlab/gitlab-runner:latest
 ```
 
 More information about the cause and resolution can be found here:

docs/install/freebsd.md

 # Install on FreeBSD
 
-Create gitlab-runner user and group:
-
-```bash
-sudo pw group add -n gitlab-runner
-sudo pw user add -n gitlab-runner -g gitlab-runner -s /usr/local/bin/bash
-sudo mkdir /home/gitlab-runner
-sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner
-```
-
-Download the binary for your system:
-
-```bash
- sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-amd64
- sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-386
-```
-
-Give it permissions to execute:
-
-```bash
-sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
-```
-
-Create empty log file with correct permissions:
-
-```bash
-sudo touch /var/log/gitlab_runner.log && sudo chown gitlab-runner:gitlab-runner /var/log/gitlab_runner.log
-```
-
-Create rc.d directory in case it does not exist:
-
-```bash
-mkdir -p /usr/local/etc/rc.d
-```
-
-Create rc.d script:
-
-```bash
-sudo bash -c 'cat > /usr/local/etc/rc.d/gitlab_runner' << "EOF"
-#!/bin/sh
-# PROVIDE: gitlab_runner
-# REQUIRE: DAEMON NETWORKING
-# BEFORE:
-# KEYWORD:
-
-. /etc/rc.subr
-
-name="gitlab_runner"
-rcvar="gitlab_runner_enable"
-
-load_rc_config $name
-
-user="gitlab-runner"
-user_home="/home/gitlab-runner"
-command="/usr/local/bin/gitlab-ci-multi-runner run"
-pidfile="/var/run/${name}.pid"
-
-start_cmd="gitlab_runner_start"
-stop_cmd="gitlab_runner_stop"
-status_cmd="gitlab_runner_status"
-
-gitlab_runner_start()
-{
-    export USER=${user}
-    export HOME=${user_home}
-    if checkyesno ${rcvar}; then
-        cd ${user_home}
-        /usr/sbin/daemon -u ${user} -p ${pidfile} ${command} > /var/log/gitlab_runner.log 2>&1
-    fi
-}
-
-gitlab_runner_stop()
-{
-    if [ -f ${pidfile} ]; then
-        kill `cat ${pidfile}`
-    fi
-}
-
-gitlab_runner_status()
-{
-    if [ ! -f ${pidfile} ] || kill -0 `cat ${pidfile}`; then
-        echo "Service ${name} is not running."
-    else
-        echo "${name} appears to be running."
-    fi
-}
-
-run_rc_command $1
-EOF
-```
-
-Make it executable:
-
-```bash
-sudo chmod +x /usr/local/etc/rc.d/gitlab_runner
-```
-
-
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
-
-```bash
-sudo -u gitlab-runner -H /usr/local/bin/gitlab-ci-multi-runner register
-
-Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com):
-
-Please enter the gitlab-ci token for this runner:
-
-Please enter the gitlab-ci description for this runner:
-[name]:
-Please enter the gitlab-ci tags for this runner (comma separated):
-
-Registering runner... succeeded
-Please enter the executor: virtualbox, ssh, shell, parallels, docker, docker-ssh:
-shell
-Runner registered successfully. Feel free to start it, but if it\'s running already the config should be automatically reloaded!
-```
-
-Enable gitlab-runner service and start it:
-
-```bash
-sudo sysrc -f /etc/rc.conf "gitlab_runner_enable=YES"
-sudo service gitlab_runner start
-```
-
-If you don't want to enable gitlab-runner server to restart after reboot, you can start it:
-
-```bash
-sudo service gitlab_runner onestart
-```
-
-**The FreeBSD version is also available from [Bleeding edge](bleeding-edge.md)**
-
-Make sure that you read the [FAQ](../faq/README.md) section which describes
-some of the most common problems with GitLab Runner.
+>**Notes:**
+- The FreeBSD version is also available as a [bleeding edge](bleeding-edge.md)
+  release.
+- Make sure that you read the [FAQ](../faq/README.md) section which describes
+  some of the most common problems with GitLab Runner.
+
+Here are the steps to install and configure GitLab Runner under FreeBSD:
+
+1. Create the `gitlab-runner` user and group:
+
+    ```bash
+    sudo pw group add -n gitlab-runner
+    sudo pw user add -n gitlab-runner -g gitlab-runner -s /usr/local/bin/bash
+    sudo mkdir /home/gitlab-runner
+    sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner
+    ```
+
+1. Download the binary for your system:
+
+    ```bash
+    # For amd64
+    sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-amd64
+
+    # For i386
+    sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-386
+    ```
+
+1. Give it permissions to execute:
+
+    ```bash
+    sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
+    ```
+
+1. Create an empty log file with correct permissions:
+
+    ```bash
+    sudo touch /var/log/gitlab_runner.log && sudo chown gitlab-runner:gitlab-runner /var/log/gitlab_runner.log
+    ```
+
+1. Create the `rc.d` directory in case it doesn't exist:
+
+    ```bash
+    mkdir -p /usr/local/etc/rc.d
+    ```
+
+1. Create the `rc.d` script:
+
+    ```bash
+    sudo bash -c 'cat > /usr/local/etc/rc.d/gitlab_runner' << "EOF"
+    #!/bin/sh
+    # PROVIDE: gitlab_runner
+    # REQUIRE: DAEMON NETWORKING
+    # BEFORE:
+    # KEYWORD:
+
+    . /etc/rc.subr
+
+    name="gitlab_runner"
+    rcvar="gitlab_runner_enable"
+
+    load_rc_config $name
+
+    user="gitlab-runner"
+    user_home="/home/gitlab-runner"
+    command="/usr/local/bin/gitlab-ci-multi-runner run"
+    pidfile="/var/run/${name}.pid"
+
+    start_cmd="gitlab_runner_start"
+    stop_cmd="gitlab_runner_stop"
+    status_cmd="gitlab_runner_status"
+
+    gitlab_runner_start()
+    {
+        export USER=${user}
+        export HOME=${user_home}
+        if checkyesno ${rcvar}; then
+            cd ${user_home}
+            /usr/sbin/daemon -u ${user} -p ${pidfile} ${command} > /var/log/gitlab_runner.log 2>&1
+        fi
+    }
+
+    gitlab_runner_stop()
+    {
+        if [ -f ${pidfile} ]; then
+            kill `cat ${pidfile}`
+        fi
+    }
+
+    gitlab_runner_status()
+    {
+        if [ ! -f ${pidfile} ] || kill -0 `cat ${pidfile}`; then
+            echo "Service ${name} is not running."
+        else
+            echo "${name} appears to be running."
+        fi
+    }
+
+    run_rc_command $1
+    EOF
+    ```
+
+1. Make it executable:
+
+    ```bash
+    sudo chmod +x /usr/local/etc/rc.d/gitlab_runner
+    ```
+1. Register the Runner (look into [runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
+
+    ```bash
+    sudo -u gitlab-runner -H /usr/local/bin/gitlab-ci-multi-runner register
+
+    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com):
+    Please enter the gitlab-ci token for this runner:
+    Please enter the gitlab-ci description for this runner:
+    [name]:
+    Please enter the gitlab-ci tags for this runner (comma separated):
+    Registering runner... succeeded
+    Please enter the executor: virtualbox, ssh, shell, parallels, docker, docker-ssh:
+    shell
+    Runner registered successfully. Feel free to start it, but if it\'s running already the config should be automatically reloaded!
+    ```
+
+1. Enable the `gitlab-runner` service and start it:
+
+    ```bash
+    sudo sysrc -f /etc/rc.conf "gitlab_runner_enable=YES"
+    sudo service gitlab_runner start
+    ```
+
+    If you don't want to enable the `gitlab-runner` service to start after a
+    reboot, use:
+
+    ```bash
+    sudo service gitlab_runner onestart
+    ```

docs/install/index.md

@@ -5,11 +5,11 @@ There are three ways to install it. Using Docker, download the binary manually o
 use the repository for rpm/deb packages that GitLab offers. Below you can find
 information on the different installation methods:
 
-- [Install using GitLab's repository for Debian/Ubuntu/CentOS/RedHat (preferred)](linux-repository.md)
+- [Install using GitLab's repository for Debian/Ubuntu/CentOS/RedHat](linux-repository.md) (preferred)
 - [Install on GNU/Linux manually](linux-manually.md)
-- [Install on macOS (preferred)](osx.md)
-- [Install on Windows (preferred)](windows.md)
-- [Install as a Docker Service](docker.md)
+- [Install on macOS](osx.md)
+- [Install on Windows](windows.md)
+- [Install as a Docker service](docker.md)
 - [Install in Auto-scaling mode using Docker machine](autoscaling.md)
 - [Install on FreeBSD](freebsd.md)
 - [Install on Kubernetes](kubernetes.md)

docs/install/kubernetes.md

-## Run gitlab-runner on a Kubernetes cluster
+# Run GitLab Runner on a Kubernetes cluster
 
 To get started with the GitLab CI Runner on Kubernetes you need to define
-resources that you can then push to the cluster with kubectl.
+resources that you can then push to the cluster with `kubectl`.
 
 A recommended approach to this is to create a `ConfigMap` in Kubernetes such as
 the following:

docs/install/linux-manually.md

-## Manual installation and configuration
+# Manual installation and configuration on GNU/Linux
 
-### Install
+>**Note:**
+Make sure that you read the [FAQ](../faq/README.md) section which describes
+some of the most common problems with GitLab Runner.
+
+If you don't want to use a [deb/rpm repository](linux-repository.md) to install
+GitLab Runner, or your OS is not among the supported ones, you can install it
+manually.
+
+## Install
 
 Simply download one of the binaries for your system:
 
@@ -22,32 +30,33 @@ Optionally, if you want to use Docker, install Docker with:
 curl -sSL https://get.docker.com/ | sh
 ```
 
-Create a GitLab CI user (on Linux):
+Create a GitLab CI user:
 
 ```
 sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
 ```
 
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
+Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
 ```bash
 sudo gitlab-ci-multi-runner register
 ```
 
-Install and run as service (on Linux):
+Install and run as service:
+
 ```bash
 sudo gitlab-ci-multi-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
 sudo gitlab-ci-multi-runner start
 ```
 
-> **Notice**
+>**Note**
+If `gitlab-ci-multi-runner` is installed and run as service (what is described
+in this page), it will run as root, but will execute jobs as user specified by
+the `install` command. This means that some of the job functions like cache and
+artifacts will need to execute `/usr/local/bin/gitlab-ci-multi-runner` command,
+therefore the user under which jobs are run, needs to have access to the executable.
 
->Note that if gitlab-ci-multi-runner is installed and run as service (what is described in this page), 
-it will run as root, but will execute jobs as user specified by the `install` command. This means that some of the 
-job functions like cache and artifacts will need to execute `/usr/local/bin/gitlab-ci-multi-runner` command, therefore
-the user under which jobs are run, needs to have access to the executable.
-
-### Update
+## Update
 
 Stop the service (you need elevated command prompt as before):
 
@@ -55,7 +64,7 @@ Stop the service (you need elevated command prompt as before):
 sudo gitlab-ci-multi-runner stop
 ```
 
-Download the binary to replace runner's executable:
+Download the binary to replace Runner's executable:
 
 ```bash
 sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-linux-386
@@ -73,6 +82,3 @@ Start the service:
 ```bash
 sudo gitlab-ci-multi-runner start
 ```
-
-Make sure that you read the [FAQ](../faq/README.md) section which describes
-some of the most common problems with GitLab Runner.

docs/install/linux-repository.md

-### Install using official GitLab repositories
+# Install GitLab Runner using the official GitLab repositories
 
-Currently we support Debian, Ubuntu, RHEL and CentOS.
+Currently we support:
 
-If you want to use Docker runner, install it before using the multi runner:
+- Debian
+- Ubuntu
+- RHEL
+- CentOS.
+
+If you want to use the [Docker executor], install it before using the Runner:
 
 ```bash
 curl -sSL https://get.docker.com/ | sh
 ```
 
-Add GitLab's official repository via apt-get or yum:
+## Add the repository
+
+Add GitLab's official repository:
 
 ```bash
 # For Debian/Ubuntu
@@ -18,18 +25,18 @@ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-
 curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | sudo bash
 ```
 
----
-**APT pinning - Debian only**
-
+>**Note:**
+_Debian users should use APT pinning_
+>
 Since Debian Stretch, Debian maintainers added their native package
-with the same name as is used by our package. And by default the official
-repositories will have a priority.
-
+with the same name as is used by our package, and by default the official
+repositories will have a higher priority.
+>
 If you want to use our package you should manually set the source of
 the package. The best would be to add the pinning configuration file.
 Thanks to this every next update of the Runner's package - whether it will
 be done manually or automatically - will be done using the same source:
-
+>
 ```bash
 cat > /etc/apt/preferences.d/pin-gitlab-runner.pref <<EOF
 Explanation: Prefer GitLab provided packages over the Debian native ones
@@ -38,7 +45,6 @@ Pin: origin packages.gitlab.com
 Pin-Priority: 1001
 EOF
 ```
----
 
 Install `gitlab-ci-multi-runner`:
 
@@ -50,7 +56,7 @@ sudo apt-get install gitlab-ci-multi-runner
 sudo yum install gitlab-ci-multi-runner
 ```
 
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
+Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
 ```bash
 sudo gitlab-ci-multi-runner register
@@ -70,12 +76,12 @@ INFO[0037] Runner registered successfully. Feel free to start it, but if it's
 running already the config should be automatically reloaded!
 ```
 
-The runner should be started already and you are ready to build your projects!
+The Runner should be started already and you are ready to build your projects!
 
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
-### Update
+## Update
 
 Simply execute to install latest version:
 
@@ -89,5 +95,9 @@ sudo yum update
 sudo yum install gitlab-ci-multi-runner
 ```
 
-### Manually download packages
-You can manually download the packages from the following URL: https://packages.gitlab.com/runner/gitlab-ci-multi-runner
+## Manually download packages
+
\ No newline at end of file
+You can manually download the packages from the following URL:
+<https://packages.gitlab.com/runner/gitlab-ci-multi-runner>
+
+[docker executor]: ../executors/docker.md

docs/install/osx.md

-### Install on OSX
+# Install on macOS
 
-(In the future there will be a brew package).
+In the future there will be a brew package, but for now you have to manually
+download the macOS binary.
 
-Download the binary for your system:
+## Installation
 
-```bash
-sudo curl --output /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
-```
+1. Download the binary for your system:
 
-Give it permissions to execute:
+    ```bash
+    sudo curl --output /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
+    ```
 
-```bash
-sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
-```
+1. Give it permissions to execute:
 
-Get your gitlab-ci token from the *Specific Runners* section on your project 
-settings *Runners* page.
+    ```bash
+    sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
+    ```
 
+**The rest of commands execute as the user who will run the Runner.**
 
-**The rest of commands execute as the user who will run the runner.**
+1. Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
-```bash
-gitlab-ci-multi-runner register
-
-Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
-https://gitlab.com
-Please enter the gitlab-ci token for this runner
-xxx
-Please enter the gitlab-ci description for this runner
-my-runner
-INFO[0034] fcf5c619 Registering runner... succeeded
-Please enter the executor: shell, docker, docker-ssh, ssh?
-docker
-Please enter the Docker image (eg. ruby:2.1):
-ruby:2.1
-INFO[0037] Runner registered successfully. Feel free to start it, but if it's
-running already the config should be automatically reloaded!
-```
+    ```bash
+    gitlab-ci-multi-runner register
 
-Install runner as service and start it:
+    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
+    https://gitlab.com
+    Please enter the gitlab-ci token for this runner
+    xxx
+    Please enter the gitlab-ci description for this runner
+    my-runner
+    INFO[0034] fcf5c619 Registering runner... succeeded
+    Please enter the executor: shell, docker, docker-ssh, ssh?
+    docker
+    Please enter the Docker image (eg. ruby:2.1):
+    ruby:2.1
+    INFO[0037] Runner registered successfully. Feel free to start it, but if it's
+    running already the config should be automatically reloaded!
+    ```
 
-```bash
-cd ~
-gitlab-ci-multi-runner install
-gitlab-ci-multi-runner start
-```
+1. Install the Runner as service and start it:
 
-Voila! Runner is installed and will be run after system reboot.
+    ```bash
+    cd ~
+    gitlab-ci-multi-runner install
+    gitlab-ci-multi-runner start
+    ```
 
-### Update
+Voila! Runner is installed and will be run after a system reboot.
 
-Stop the service:
+## Update
 
-```bash
-gitlab-ci-multi-runner stop
-```
+1. Stop the service:
 
-Download binary to replace runner's executable:
+    ```bash
+    gitlab-ci-multi-runner stop
+    ```
 
-```bash
-curl -o /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
-```
+1. Download the binary to replace the Runner's executable:
 
-Give it permissions to execute:
+    ```bash
+    curl -o /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-darwin-amd64
+    ```
 
-```bash
-chmod +x /usr/local/bin/gitlab-ci-multi-runner
-```
+1. Give it permissions to execute:
 
-Start the service:
+    ```bash
+    chmod +x /usr/local/bin/gitlab-ci-multi-runner
+    ```
 
-```bash
-gitlab-ci-multi-runner start
-```
+1. Start the service:
+
+    ```bash
+    gitlab-ci-multi-runner start
+    ```
 
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
-### Limitations on OSX
+## Limitations on macOS
 
 >**Note:**
 The service needs to be installed from the Terminal by running its GUI
 interface as your current user. Only then will you be able to manage the service.
 
-Currently, the only proven to work mode for OSX is running service in user-mode.
+Currently, the only proven to work mode for macOS is running service in user-mode.
 
 Since the service will be running only when the user is logged in, you should
 enable auto-login on your OSX machine.
@@ -103,7 +103,7 @@ You can verify that the Runner created the service configuration file after
 executing the `install` command, by checking the
 `~/Library/LaunchAgents/gitlab-runner.plist` file.
 
-### Upgrade the service file
+## Upgrade the service file
 
 In order to upgrade the `LaunchAgent` configuration, you need to uninstall and
 install the service:

docs/install/windows.md

-### Install on Windows
-
-Create a folder somewhere in your system, ex.: `C:\Multi-Runner`.
-
-Download the binary for [x86][]  or [amd64][] and put it into the folder you
-created.
-
-Run an `Administrator` command prompt ([How to][prompt]). The simplest is to
-write `Command Prompt` in Windows search field, right click and select
-`Run as administrator`. You will be asked to confirm that you want to execute
-the elevated command prompt.
-
-Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
-
-```bash
-cd C:\Multi-Runner
-gitlab-ci-multi-runner register
-
-Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
-https://gitlab.com
-Please enter the gitlab-ci token for this runner
-xxx
-Please enter the gitlab-ci description for this runner
-my-runner
-INFO[0034] fcf5c619 Registering runner... succeeded
-Please enter the executor: shell, docker, docker-ssh, ssh?
-docker
-Please enter the Docker image (eg. ruby:2.1):
-ruby:2.1
-INFO[0037] Runner registered successfully. Feel free to start it, but if it's
-running already the config should be automatically reloaded!
-```
+# Install on Windows
 
-Install runner as a service and start it. You have to enter a valid password
-for the current user account, because it's required to start the service by Windows:
+To install GitLab Runner on Windows, your user must have a password set up.
 
-```bash
-gitlab-ci-multi-runner install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
-gitlab-ci-multi-runner start
-```
+## Installation
 
-> **Important:** If you encounter an error like '*The account name is invalid*' try to add `.\` before the username.
-> ```shell
-> gitlab-ci-multi-runner install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"
-> ```
+1. Create a folder somewhere in your system, ex.: `C:\Multi-Runner`.
 
-> **Important:** If you encounter a `The service did not start due to a logon failure` error
-> while starting the service, please [look into FAQ](../faq/README.md#13-the-service-did-not-start-due-to-a-logon-failure-error-when-starting-service-on-windows) to check how to resolve the problem.
+1. Download the binary for [x86][]  or [amd64][] and put it into the folder you
+   created.
 
-> **Notice:** If you don't have a Windows Password, Runner's service won't start. To
-> fix this please read [How to Configure the Service to Start Up with the Built-in System Account](https://support.microsoft.com/en-us/kb/327545#bookmark-6)
-> on Microsoft's support website.
+1. Run an `Administrator` command prompt ([How to][prompt]). The simplest is to
+   write `Command Prompt` in Windows search field, right click and select
+   `Run as administrator`. You will be asked to confirm that you want to execute
+   the elevated command prompt.
 
-Voila! Runner is installed and will be run after system reboot.
+1. Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
 
-Logs are stored in Windows Event Log.
+    ```bash
+    cd C:\Multi-Runner
+    gitlab-ci-multi-runner register
 
-#### Update
+    Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
+    https://gitlab.com
+    Please enter the gitlab-ci token for this runner
+    xxx
+    Please enter the gitlab-ci description for this runner
+    my-runner
+    INFO[0034] fcf5c619 Registering runner... succeeded
+    Please enter the executor: shell, docker, docker-ssh, ssh?
+    docker
+    Please enter the Docker image (eg. ruby:2.1):
+    ruby:2.1
+    INFO[0037] Runner registered successfully. Feel free to start it, but if it's
+    running already the config should be automatically reloaded!
+    ```
 
-Stop service (you need elevated command prompt as before):
+1. Install the Runner as a service and start it. You have to enter a valid password
+   for the current user account, because it's required to start the service by Windows:
 
-```bash
-cd C:\Multi-Runner
-gitlab-ci-multi-runner stop
-```
+    ```bash
+    gitlab-ci-multi-runner install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
+    gitlab-ci-multi-runner start
+    ```
 
-Download the binary for [x86][] or [amd64][] and replace runner's executable.
+    See the [troubleshooting section](#troubleshooting) if you encounter any
+    errors during the Runner installation.
 
-Start service:
+Voila! Runner is installed and will be run after system reboot.
+Logs are stored in Windows Event Log.
 
-```bash
-gitlab-ci-multi-runner start
-```
+## Update
+
+1. Stop the service (you need elevated command prompt as before):
+
+    ```bash
+    cd C:\Multi-Runner
+    gitlab-ci-multi-runner stop
+    ```
+
+1. Download the binary for [x86][] or [amd64][] and replace runner's executable.
+1. Start the service:
+
+    ```bash
+    gitlab-ci-multi-runner start
+    ```
 
 Make sure that you read the [FAQ](../faq/README.md) section which describes
 some of the most common problems with GitLab Runner.
 
+## Troubleshooting
+
+If you encounter an error like _The account name is invalid_ try to add `.\` before the username:
+
+```shell
+gitlab-ci-multi-runner install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"
+```
+
+If you encounter a _The service did not start due to a logon failure_ error
+while starting the service, please [look into FAQ](../faq/README.md#13-the-service-did-not-start-due-to-a-logon-failure-error-when-starting-service-on-windows) to check how to resolve the problem.
+
+If you don't have a Windows Password, Runner's service won't start. To
+fix this please read [How to Configure the Service to Start Up with the Built-in System Account](https://support.microsoft.com/en-us/kb/327545#bookmark-6)
+on Microsoft's support website.
+
 [x86]: https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-windows-386.exe
 [amd64]: https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-windows-amd64.exe
 [prompt]: http://pcsupport.about.com/od/windows-8/a/elevated-command-prompt-windows-8.htm

docs/monitoring/README.md

-# GitLab Runner Monitoring
+# GitLab Runner monitoring
+
+GitLab Runner can be monitored using [Prometheus].
 
 ## Embedded Prometheus metrics
 
 > The embedded HTTP Statistics Server with Prometheus metrics was
 introduced in GitLab Runner 1.8.0.
 
-The GitLab Runner is instrumented with native [Prometheus](https://prometheus.io/)
+The GitLab Runner is instrumented with native Prometheus
 metrics, which can be exposed via an embedded HTTP server on the `/metrics`
 path. The server - if enabled - can be scraped by the Prometheus monitoring
 system or accessed with any other HTTP client.
 
 The exposed information includes:
 
-- runner business logic metrics (e.g. the number of currently running builds)
+- Runner business logic metrics (e.g., the number of currently running builds)
 - Go-specific process metrics (garbage collection stats, goroutines, memstats, etc.)
-- general process metrics (memory usage, cpu usage, file descriptor usage, etc.)
+- general process metrics (memory usage, CPU usage, file descriptor usage, etc.)
 - build version information
 
-The following is an example of the metrics output in Prometheus's
+The following is an example of the metrics output in Prometheus'
 text-based metrics exposition format:
 
 ```
@@ -153,7 +155,7 @@ process_virtual_memory_bytes 3.39746816e+08
 ```
 
 Note that the lines starting with `# HELP` document the meaning of each exposed
-metric. This metrics format is documented in Prometheus's
+metric. This metrics format is documented in Prometheus'
 [Exposition formats](https://prometheus.io/docs/instrumenting/exposition_formats/)
 specification.
 
@@ -186,20 +188,22 @@ the `pprof` HTTP endpoints.
 `pprof` endpoints will be available via an embedded HTTP server on `/debug/pprof/`
 path.
 
-You can read more about using `pprof` in it's [documentation][go-pprof].
+You can read more about using `pprof` in its [documentation][go-pprof].
 
 ## Configuration of the metrics HTTP server
 
+> **Note:**
+The metrics server exports data about the internal state of the
+GitLab Runner process and should not be publicly available!
+
 The metrics HTTP server can be configured in two ways:
 
 - with a `metrics_server` global configuration option in `config.toml` file,
 - with a `--metrics-server` command line option for the `run` command.
 
-In both cases the option accepts a string with the format:
-
-`[host]:<port>`
-
+In both cases the option accepts a string with the format `[host]:<port>`,
 where:
+
 - `host` can be an IP address or a host name,
 - `port` is a valid TCP port or symbolic service name (like `http`).
 
@@ -218,7 +222,5 @@ to a public interface then you should consider to use your firewall to
 limit access to this server or add a HTTP proxy which will add the
 authorization and access control layer.
 
-> **Notice:** Metrics server exports data about internal state of the
-GitLab Runner process and should not be publicly available!
-
-[go-pprof]: https://golang.org/pkg/net/http/pprof/
+[go-pprof]: https://golang.org/pkg/net/http/pprof/
+[prometheus]: https://prometheus.io
\ No newline at end of file

docs/release_process/README.md

@@ -3,22 +3,6 @@
 To handle the growth of this project, in `v1.6` we've introduced a release process correlated
 with GitLab's CE/EE release process.
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-
-- [Release roadmap](#release-roadmap)
-  - [Stable release timeline](#stable-release-timeline)
-  - [Supported releases](#supported-releases)
-  - [Release planning](#release-planning)
-- [Workflow, merging and tagging strategy](#workflow-merging-and-tagging-strategy)
-  - [Stable release](#stable-release)
-  - [Patch releases](#patch-releases)
-  - [Branch naming](#branch-naming)
-- [Documentation](#documentation)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Release roadmap
 
 Starting with `v1.4`, GitLab Runner is released on the 22nd day of each month -

docs/shells/README.md

@@ -3,19 +3,6 @@
 GitLab Runner implements a few shell script generators that allow to execute
 builds on different systems.
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [Overview](#overview)
-- [Sh/Bash shells](#sh-bash-shells)
-- [Windows Batch](#windows-batch)
-- [PowerShell](#powershell)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 ## Overview
 
 The shell scripts contain commands to execute all steps of the build: