Update docs to markdown style guide.

CONTRIBUTING.md

@@ -24,16 +24,11 @@ Issues and merge requests should be in English and contain appropriate language
 To get support for your particular problem please use the channels as detailed in the [getting help section of the readme](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/README.md#getting-help). Professional [support subscriptions](http://www.gitlab.com/subscription/) and [consulting services](http://www.gitlab.com/consultancy/) are available from [GitLab.com](http://www.gitlab.com/).
-The [issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues) is only for obvious errors in the latest [stable or development release of GitLab](MAINTENANCE.md).
-If something is wrong but it is not a regression compared to older versions of GitLab please do not open an issue but a feature request.
-When submitting an issue please conform to the issue submission guidelines listed below.
-Not all issues will be addressed and your issue is more likely to be addressed if you submit a merge request which partially or fully addresses the issue.
+The [issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues) is only for obvious errors in the latest [stable or development release of GitLab](MAINTENANCE.md). If something is wrong but it is not a regression compared to older versions of GitLab please do not open an issue but a feature request. When submitting an issue please conform to the issue submission guidelines listed below. Not all issues will be addressed and your issue is more likely to be addressed if you submit a merge request which partially or fully addresses the issue.
 Issues can be filed either at [gitlab.com](https://gitlab.com/gitlab-org/gitlab-ce/issues) or [github.com](https://github.com/gitlabhq/gitlabhq/issues).
-Do not use the issue tracker for feature requests.
-We have a specific [feature request forum](http://feedback.gitlab.com) for this purpose.
-Please keep feature requests as small and simple as possible, complex ones might be edited to make them small and simple.
+Do not use the issue tracker for feature requests. We have a specific [feature request forum](http://feedback.gitlab.com) for this purpose. Please keep feature requests as small and simple as possible, complex ones might be edited to make them small and simple.
 Please send a merge request with a tested solution or a merge request with a failing test instead of opening an issue if you can. If you're unsure where to post, post to the [mailing list](https://groups.google.com/forum/#!forum/gitlabhq) or [Stack Overflow](http://stackoverflow.com/questions/tagged/gitlab) first. There are a lot of helpful GitLab users there who may be able to help you quickly. If your particular issue turns out to be a bug, it will find its way from there.
@@ -42,16 +37,16 @@ Please send a merge request with a tested solution or a merge request with a fai
 **[Search the issues](https://gitlab.com/gitlab-org/gitlab-ce/issues)** for similar entries before submitting your own, there's a good chance somebody else had the same issue. Show your support with `:+1:` and/or join the discussion. Please submit issues in the following format (as the first post):
 1. **Summary:** Summarize your issue in one sentence (what goes wrong, what did you expect to happen)
-2. **Steps to reproduce:** How can we reproduce the issue, preferably on the [GitLab development virtual machine with vagrant](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/doc/development.md) (start your issue with: `vagrant destroy && vagrant up && vagrant ssh`)
-3. **Expected behavior:** Describe your issue in detail
-4. **Observed behavior**
-5. **Relevant logs and/or screenshots:** Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.
-6. **Output of checks**
+1. **Steps to reproduce:** How can we reproduce the issue, preferably on the [GitLab development virtual machine with vagrant](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/doc/development.md) (start your issue with: `vagrant destroy && vagrant up && vagrant ssh`)
+1. **Expected behavior:** Describe your issue in detail
+1. **Observed behavior**
+1. **Relevant logs and/or screenshots:** Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.
+1. **Output of checks**
     * Results of GitLab [Application Check](doc/install/installation.md#check-application-status) (`sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production`); we will only investigate if the tests are passing
     * Version of GitLab you are running; we will only investigate issues in the latest stable and development releases as per the [maintenance policy](MAINTENANCE.md)
     * Add the last commit sha1 of the GitLab version you used to replicate the issue (obtainable from the help page)
     * Describe your setup (use relevant parts from `sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production`)
-7. **Possible fixes**: If you can, link to the line of code that might be responsible for the problem
+1. **Possible fixes**: If you can, link to the line of code that might be responsible for the problem
 ## Merge requests
@@ -87,10 +82,10 @@ For examples of feedback on merge requests please look at already [closed merge
 **Please format your merge request description as follows:**
 1. What does this MR do?
-2. Are there points in the code the reviewer needs to double check?
-3. Why was this MR needed?
-4. What are the relevant issue numbers / [Feature requests](http://feedback.gitlab.com/)?
-5. Screenshots (If appropiate)
+1. Are there points in the code the reviewer needs to double check?
+1. Why was this MR needed?
+1. What are the relevant issue numbers / [Feature requests](http://feedback.gitlab.com/)?
+1. Screenshots (If appropiate)
 ## Contribution acceptance criteria
@@ -106,6 +101,7 @@ For examples of feedback on merge requests please look at already [closed merge
 1. It conforms to the following style guides
 ## Style guides
+
 1. [Ruby](https://github.com/bbatsov/ruby-style-guide)
 1. [Rails](https://github.com/bbatsov/rails-style-guide)
 1. [Formatting](https://github.com/thoughtbot/guides/tree/master/style#formatting)

MAINTENANCE.md

 # GitLab Maintenance Policy
-GitLab is a fast moving and evolving project. We currently don't have the
-resources to support many releases concurrently. We support exactly one stable
-release at any given time.
-GitLab follows the [Semantic Versioning](http://semver.org/) for its releases:
-`(Major).(Minor).(Patch)`.
-* **Major version**: Whenever there is something significant or any backwards
-  incompatible changes are introduced to the public API.
-* **Minor version**: When new, backwards compatible functionality is introduced
-  to the public API or a minor feature is introduced, or when a set of smaller
-  features is rolled out.
-* **Patch number**: When backwards compatible bug fixes are introduced that fix
-  incorrect behavior.
-The current stable release will receive security patches and bug fixes
-(eg. `5.0` -> `5.0.1`).  Feature releases will mark the next supported stable
-release where the minor version is increased numerically by increments of one
-(eg. `5.0 -> 5.1`).
+GitLab is a fast moving and evolving project. We currently don't have the resources to support many releases concurrently. We support exactly one stable release at any given time.
+GitLab follows the [Semantic Versioning](http://semver.org/) for its releases: `(Major).(Minor).(Patch)`.
+- **Major version**: Whenever there is something significant or any backwards incompatible changes are introduced to the public API.
+- **Minor version**: When new, backwards compatible functionality is introduced to the public API or a minor feature is introduced, or when a set of smaller features is rolled out.
+- **Patch number**: When backwards compatible bug fixes are introduced that fix incorrect behavior.
+The current stable release will receive security patches and bug fixes (eg. `5.0` -> `5.0.1`).  Feature releases will mark the next supported stable release where the minor version is increased numerically by increments of one (eg. `5.0 -> 5.1`).
 We encourage everyone to run the latest stable release to ensure that you can easily upgrade to the most secure and feature rich GitLab experience. In order to make sure you can easily run the most recent stable release, we are working hard to keep the update process simple and reliable.

PROCESS.md

@@ -24,9 +24,9 @@ Below we describe the contributing process to GitLab for two reasons. So that co
 ## Priorities of the issue team
 1. Mentioning people (critical)
-2. Workflow labels (normal)
-3. Functional labels (minor)
-4. Assigning issues (avoid if possible)
+1. Workflow labels (normal)
+1. Functional labels (minor)
+1. Assigning issues (avoid if possible)
 ## Mentioning people
@@ -36,11 +36,11 @@ The most important thing is making sure valid issues receive feedback from the d
 Workflow labels are purposely not very detailed since that would be hard to keep updated as you would need to reevaluate them after every comment. We optionally use functional labels on demand when want to group related issues to get an overview (for example all issues related to RVM, to tackle them in one go) and to add details to the issue. 
-- _Awaiting feedback_: Feedback pending from the reporter
-- _Awaiting confirmation of fix_: The issue should already be solved in **master** (generally you can avoid this workflow item and just close the issue right away)
-- _Attached MR_: There is a MR attached and the discussion should happen there
-  - We need to let issues stay in sync with the MR's. We can do this with a "Closing #XXXX" or "Fixes #XXXX" comment in the MR. We can't close the issue when there is a merge request because sometimes a MR is not good and we just close the MR, then the issue must stay.
-- _Awaiting developer action/feedback_: Issue needs to be fixed or clarified by a developer
+-   *Awaiting feedback*: Feedback pending from the reporter
+-   *Awaiting confirmation of fix*: The issue should already be solved in **master** (generally you can avoid this workflow item and just close the issue right away)
+-   *Attached MR*: There is a MR attached and the discussion should happen there
+    - We need to let issues stay in sync with the MR's. We can do this with a "Closing #XXXX" or "Fixes #XXXX" comment in the MR. We can't close the issue when there is a merge request because sometimes a MR is not good and we just close the MR, then the issue must stay.
+-   *Awaiting developer action/feedback*: Issue needs to be fixed or clarified by a developer
 ## Functional labels
@@ -51,12 +51,13 @@ These labels describe what development specialities are involved such as: Postgr
 If an issue is complex and needs the attention of a specific person, assignment is a good option but assigning issues might discourage other people from contributing to that issue. We need all the contributions we can get so this should never be discouraged. Also, an assigned person might not have time for a few weeks, so others should feel free to takeover.
 ## Label colors
-- Light orange `#fef2c0`: workflow labels for issue team members (awaiting feedback, awaiting confirmation of fix)
-- Bright orange `#eb6420`: workflow labels for core team members (attached MR, awaiting developer action/feedback)
-- Light blue `#82C5FF`: functional labels
-- Green labels `#009800`: issues that can generally be ignored. For example, issues given the following labels normally can be closed immediately:
-  - Feature request (see copy & paste response: [Feature requests](#feature-requests))
-  - Support (see copy & paste response: [Support requests and configuration questions](#support-requests-and-configuration-questions)
+
+-   Light orange `#fef2c0`: workflow labels for issue team members (awaiting feedback, awaiting confirmation of fix)
+-   Bright orange `#eb6420`: workflow labels for core team members (attached MR, awaiting developer action/feedback)
+-   Light blue `#82C5FF`: functional labels
+-   Green labels `#009800`: issues that can generally be ignored. For example, issues given the following labels normally can be closed immediately:
+    - Feature request (see copy & paste response: [Feature requests](#feature-requests))
+    - Support (see copy & paste response: [Support requests and configuration questions](#support-requests-and-configuration-questions)
 ## Be kind
@@ -102,8 +103,4 @@ This merge request has been closed because a request for more information has no
 ### Accepting merge requests
-Is there a request on [the feature request forum](http://feedback.gitlab.com/forums/176466-general) that is similar to this?
-If so, can you make a comment with a link to it?
-Please be aware that new functionality that is not marked [accepting merge/pull requests](http://feedback.gitlab.com/forums/176466-general/status/796455) on the forum might not make it into GitLab.
-You might be asked to make changes and even after implementing them your feature might still be declined.
-If you want to reduce the chance of this happening please have a discussion in the forum first.
+Is there a request on [the feature request forum](http://feedback.gitlab.com/forums/176466-general) that is similar to this? If so, can you make a comment with a link to it? Please be aware that new functionality that is not marked [accepting merge/pull requests](http://feedback.gitlab.com/forums/176466-general/status/796455) on the forum might not make it into GitLab. You might be asked to make changes and even after implementing them your feature might still be declined. If you want to reduce the chance of this happening please have a discussion in the forum first.

README.md

-## GitLab: self hosted Git management software
+# GitLab
+
+## Self hosted Git management software
 ![logo](https://gitlab.com/gitlab-org/gitlab-ce/raw/master/public/gitlab_logo.png)
 ![animated-screenshots](https://gist.github.com/fnkr/2f9badd56bfe0ed04ee7/raw/4f48806fbae97f556c2f78d8c2d299c04500cb0d/compiled.gif)
-### Gitlab is open source software to collaborate on code
-* Manage git repositories with fine grained access controls that keep your code secure
-* Perform code reviews and enhance collaboration with merge requests
-* Each project can also have an issue tracker and a wiki
-* Used by more than 100,000 organizations, GitLab is the most popular solution to manage git repositories on-premises
-* Completely free and open source (MIT Expat license)
-* Powered by Ruby on Rails
-### Canonical source
-* The source of GitLab Community Edition is [hosted on GitLab.com](https://gitlab.com/gitlab-org/gitlab-ce/) and there are mirrors to make [contributing](CONTRIBUTING.md) as easy as possible.
-### Code status
-* [![build status](https://ci.gitlab.org/projects/1/status.png?ref=master)](https://ci.gitlab.org/projects/1?ref=master) on ci.gitlab.org (master branch)
-* [![Code Climate](https://codeclimate.com/github/gitlabhq/gitlabhq.png)](https://codeclimate.com/github/gitlabhq/gitlabhq)
-* [![Coverage Status](https://coveralls.io/repos/gitlabhq/gitlabhq/badge.png?branch=master)](https://coveralls.io/r/gitlabhq/gitlabhq)
-* [![PullReview stats](https://www.pullreview.com/gitlab/gitlab-org/gitlab-ce/badges/master.svg?)](https://www.pullreview.com/gitlab.gitlab.com/gitlab-org/gitlab-ce/reviews/master)
+## Open source software to collaborate on code
+- Manage Git repositories with fine grained access controls that keep your code secure
+- Perform code reviews and enhance collaboration with merge requests
+- Each project can also have an issue tracker and a wiki
+- Used by more than 100,000 organizations, GitLab is the most popular solution to manage Git repositories on-premises
+- Completely free and open source (MIT Expat license)
+- Powered by Ruby on Rails
+## Canonical source
+- The source of GitLab Community Edition is [hosted on GitLab.com](https://gitlab.com/gitlab-org/gitlab-ce/) and there are mirrors to make [contributing](CONTRIBUTING.md) as easy as possible.
+## Code status
+- [![build status](https://ci.gitlab.org/projects/1/status.png?ref=master)](https://ci.gitlab.org/projects/1?ref=master) on ci.gitlab.org (master branch)
+- [![Code Climate](https://codeclimate.com/github/gitlabhq/gitlabhq.png)](https://codeclimate.com/github/gitlabhq/gitlabhq)
+- [![Coverage Status](https://coveralls.io/repos/gitlabhq/gitlabhq/badge.png?branch=master)](https://coveralls.io/r/gitlabhq/gitlabhq)
+- [![PullReview stats](https://www.pullreview.com/gitlab/gitlab-org/gitlab-ce/badges/master.svg?)](https://www.pullreview.com/gitlab.gitlab.com/gitlab-org/gitlab-ce/reviews/master)
 ### Resources
-* [www.gitlab.com](https://www.gitlab.com/) includes information about [subscriptions](https://www.gitlab.com/subscription/), [consultancy](https://www.gitlab.com/consultancy/), the [community](https://www.gitlab.com/community/) and the [hosted GitLab.com](https://www.gitlab.com/gitlab-com/).
-* [GitLab Enterprise Edition](https://www.gitlab.com/gitlab-ee/) offers additional features aimed at larger organizations.
-* [GitLab CI](https://www.gitlab.com/gitlab-ci/) is a continuous integration (CI) server that is easy to integrate with GitLab.
-* Unofficial third-party [iPhone app](http://gitlabcontrol.com/), [Android app](https://play.google.com/store/apps/details?id=com.bd.gitlab&hl=en), [command line client](https://github.com/drewblessing/gitlab-cli), [Ruby API wrapper](https://github.com/NARKOZ/gitlab) and [Chrome app](https://chrome.google.com/webstore/detail/chrome-gitlab-notifier/eageapgbnjicdjjihgclpclilenjbobi) for GitLab.
-### Requirements
-* Ubuntu/Debian/CentOS/RHEL**
-* ruby 2.0+
-* git 1.7.10+
-* redis 2.0+
-* MySQL or PostgreSQL
-** More details are in the [requirements doc](doc/install/requirements.md)
-### Installation
+- [www.gitlab.com](https://www.gitlab.com/) includes information about [subscriptions](https://www.gitlab.com/subscription/), [consultancy](https://www.gitlab.com/consultancy/), the [community](https://www.gitlab.com/community/) and the [hosted GitLab.com](https://www.gitlab.com/gitlab-com/).
+- [GitLab Enterprise Edition](https://www.gitlab.com/gitlab-ee/) offers additional features aimed at larger organizations.
+- [GitLab CI](https://www.gitlab.com/gitlab-ci/) is a continuous integration (CI) server that is easy to integrate with GitLab.
+- Unofficial third-party [iPhone app](http://gitlabcontrol.com/), [Android app](https://play.google.com/store/apps/details?id=com.bd.gitlab&hl=en), [command line client](https://github.com/drewblessing/gitlab-cli), [Ruby API wrapper](https://github.com/NARKOZ/gitlab) and [Chrome app](https://chrome.google.com/webstore/detail/chrome-gitlab-notifier/eageapgbnjicdjjihgclpclilenjbobi) for GitLab.
+## Requirements
+- Ubuntu/Debian/CentOS/RHEL**
+- ruby 2.0+
+- git 1.7.10+
+- redis 2.0+
+- MySQL or PostgreSQL
+** More details are in the [requirements doc](doc/install/requirements.md).
+## Installation
 Please see [the installation page on the GitLab website](https://www.gitlab.com/installation/).
@@ -59,22 +61,21 @@ Since 2011 a minor or major version of GitLab is released on the 22nd of every m
 For updating the the Omnibus installation please see the [update documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/update.md). For manual installations there is an [upgrader script](doc/update/upgrader.md) and there are [upgrade guides](doc/update).
-### Run in production mode
+## Run in production mode
 The Installation guide contains instructions on how to download an init script and run it automatically on boot. You can also start the init script manually:
     sudo service gitlab start
-or by directly calling the script
+or by directly calling the script:
      sudo /etc/init.d/gitlab start
-Please login with root / 5iveL!fe
+Please login with `root` / `5iveL!fe`.
 ### Install a development environment
-We recommend setting up your development environment with [the cookbook](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/README.md#installation).
-If you do not use the cookbook you might need to copy the example development unicorn configuration file
+We recommend setting up your development environment with [the cookbook](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/README.md#installation). If you do not use the cookbook you might need to copy the example development unicorn configuration file
     cp config/unicorn.rb.example.development config/unicorn.rb
@@ -84,36 +85,35 @@ Start it with [Foreman](https://github.com/ddollar/foreman)
     bundle exec foreman start -p 3000
-or start each component separately
+or start each component separately:
     bundle exec rails s
     bin/background_jobs start
-And surf to [localhost:3000](http://localhost:3000/) and login with root / 5iveL!fe
-### Run the tests
-* Run all tests
+And surf to [localhost:3000](http://localhost:3000/) and login with `root` / `5iveL!fe`.
+## Run the tests
+-   Run all tests:
         bundle exec rake test
-* [RSpec](http://rspec.info/) unit and functional tests
-
-        All RSpec tests: bundle exec rake spec
-        Single RSpec file: bundle exec rspec spec/controllers/commit_controller_spec.rb
-* [Spinach](https://github.com/codegram/spinach) integration tests
-        All Spinach tests: bundle exec rake spinach
-        Single Spinach test: bundle exec spinach features/project/issues/milestones.feature
-### Documentation
+-   [RSpec](http://rspec.info/) unit and functional tests.
+    All RSpec tests: `bundle exec rake spec`
+    Single RSpec file: `bundle exec rspec spec/controllers/commit_controller_spec.rb`
+-   [Spinach](https://github.com/codegram/spinach) integration tests.
+    All Spinach tests: `bundle exec rake spinach`
+    Single Spinach test: `bundle exec spinach features/project/issues/milestones.feature`
+## Documentation
 All documentation can be found on [doc.gitlab.com/ce/](http://doc.gitlab.com/ce/).
-### Getting help
+## Getting help
 Please see [Getting help for GitLab](https://www.gitlab.com/getting-help/) on our website for the many options to get help.

doc/README.md

-**User documentation**
-+ [API](api/README.md) Explore how you can access GitLab via a simple and powerful API.
-+ [Markdown](markdown/markdown.md) Learn what you can do with GitLab's advanced formatting system.
-+ [Permissions](permissions/permissions.md) Learn what each role in a project (guest/reporter/developer/master/owner) can do.
-+ [Public access](public_access/public_access.md) Learn how you can allow public and internal access to a project.
-+ [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects.
-+ [Web hooks](web_hooks/web_hooks.md) Let GitLab notify you when new code has been pushed to your project.
-+ [Workflow](workflow/README.md) Learn how to use Git and GitLab together.
-**Administrator documentation**
-+ [Install](install/README.md) Requirements, directory structures and manual installation.
-+ [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, LDAP and Twitter.
-+ [Raketasks](raketasks/README.md) Explore what GitLab has in store for you to make administration easier.
-+ [System hooks](system_hooks/system_hooks.md) Let GitLab notify you when certain management tasks need to be carried out.
-+ [Security](security/README.md) Learn what you can do to further secure your GitLab instance.
-+ [Update](update/README.md) Update guides to upgrade your installation.
-**Contributor documentation**
-+ [Development](development/README.md) Explains the architecture and the guidelines for shell commands.
-+ [Legal](legal/README.md) Contributor license agreements.
-+ [Release](release/README.md) How to make the monthly and security releases.
+# Documentation
+## User documentation
+- [API](api/README.md) Explore how you can access GitLab via a simple and powerful API.
+- [Markdown](markdown/markdown.md) Learn what you can do with GitLab's advanced formatting system.
+- [Permissions](permissions/permissions.md) Learn what each role in a project (guest/reporter/developer/master/owner) can do.
+- [Public access](public_access/public_access.md) Learn how you can allow public and internal access to a project.
+- [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects.
+- [Web hooks](web_hooks/web_hooks.md) Let GitLab notify you when new code has been pushed to your project.
+- [Workflow](workflow/README.md) Learn how to use Git and GitLab together.
+## Administrator documentation
+- [Install](install/README.md) Requirements, directory structures and manual installation.
+- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, LDAP and Twitter.
+- [Raketasks](raketasks/README.md) Explore what GitLab has in store for you to make administration easier.
+- [System hooks](system_hooks/system_hooks.md) Let GitLab notify you when certain management tasks need to be carried out.
+- [Security](security/README.md) Learn what you can do to further secure your GitLab instance.
+- [Update](update/README.md) Update guides to upgrade your installation.
+## Contributor documentation
+
+- [Development](development/README.md) Explains the architecture and the guidelines for shell commands.
+- [Legal](legal/README.md) Contributor license agreements.
+- [Release](release/README.md) How to make the monthly and security releases.

doc/api/README.md

@@ -2,31 +2,31 @@
 ## Resources
-+ [Users](users.md)
-+ [Session](session.md)
-+ [Projects](projects.md)
-+ [Project Snippets](project_snippets.md)
-+ [Repositories](repositories.md)
-+ [Repository Files](repository_files.md)
-+ [Commits](commits.md)
-+ [Branches](branches.md)
-+ [Merge Requests](merge_requests.md)
-+ [Issues](issues.md)
-+ [Milestones](milestones.md)
-+ [Notes](notes.md) (comments)
-+ [Deploy Keys](deploy_keys.md)
-+ [System Hooks](system_hooks.md)
-+ [Groups](groups.md)
+- [Users](users.md)
+- [Session](session.md)
+- [Projects](projects.md)
+- [Project Snippets](project_snippets.md)
+- [Repositories](repositories.md)
+- [Repository Files](repository_files.md)
+- [Commits](commits.md)
+- [Branches](branches.md)
+- [Merge Requests](merge_requests.md)
+- [Issues](issues.md)
+- [Milestones](milestones.md)
+- [Notes](notes.md) (comments)
+- [Deploy Keys](deploy_keys.md)
+- [System Hooks](system_hooks.md)
+- [Groups](groups.md)
 ## Clients
-+ [php-gitlab-api](https://github.com/m4tthumphrey/php-gitlab-api) - PHP
-+ [Laravel API Wrapper for GitLab CE](https://github.com/adamgoose/gitlab) - PHP / [Laravel](http://laravel.com)
-+ [Ruby Wrapper](https://github.com/NARKOZ/gitlab) - Ruby
-+ [python-gitlab](https://github.com/Itxaka/python-gitlab) - Python
-+ [java-gitlab-api](https://github.com/timols/java-gitlab-api) - Java
-+ [node-gitlab](https://github.com/moul/node-gitlab) - Node.js
-+ [NGitLab](https://github.com/Scooletz/NGitLab) - .NET
+- [php-gitlab-api](https://github.com/m4tthumphrey/php-gitlab-api) - PHP
+- [Laravel API Wrapper for GitLab CE](https://github.com/adamgoose/gitlab) - PHP / [Laravel](http://laravel.com)
+- [Ruby Wrapper](https://github.com/NARKOZ/gitlab) - Ruby
+- [python-gitlab](https://github.com/Itxaka/python-gitlab) - Python
+- [java-gitlab-api](https://github.com/timols/java-gitlab-api) - Java
+- [node-gitlab](https://github.com/moul/node-gitlab) - Node.js
+- [NGitLab](https://github.com/Scooletz/NGitLab) - .NET
 ## Introduction
@@ -54,41 +54,35 @@ Example for a valid API request using curl and authentication via header:
 curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects"
 ```
-
 The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
-
-
 ## Status codes
-The API is designed to return different status codes according to context and action. In this way
-if a request results in an error the caller is able to get insight into what went wrong, e.g.
-status code `400 Bad Request` is returned if a required attribute is missing from the request.
-The following list gives an overview of how the API functions generally behave.
+The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave.
 API request types:
-* `GET` requests access one or more resources and return the result as JSON
-* `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
-* `GET`, `PUT` and `DELETE` return `200 Ok` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
-* `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 Ok` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
-
+- `GET` requests access one or more resources and return the result as JSON
+- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
+- `GET`, `PUT` and `DELETE` return `200 Ok` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
+- `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 Ok` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
 The following list shows the possible return codes for API requests.
 Return values:
-* `200 Ok` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
-* `201 Created` - The `POST` request was successful and the resource is returned as JSON
-* `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
-* `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
-* `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
-* `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
-* `405 Method Not Allowed` - The request is not supported
-* `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists
-* `500 Server Error` - While handling the request something went wrong on the server side
+- `200 Ok` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
+- `201 Created` - The `POST` request was successful and the resource is returned as JSON
+- `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
+- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
+- `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
+- `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
+- `405 Method Not Allowed` - The request is not supported
+- `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists
+- `500 Server Error` - While handling the request something went wrong on the server side
 ## Sudo
+
 All API requests support performing an api call as if you were another user, if your private token is for an administration account. You need to pass  `sudo` parameter by url or header with an id or username of the user you want to perform the operation as. If passed as header, the header name must be "SUDO" (capitals).
 If a non administrative `private_token` is provided then an error message will be returned with status code 403:
@@ -112,16 +106,17 @@ Example of a valid API with sudo request:
 ```
 GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=username
 ```
+
 ```
 GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=23
 ```
-
 Example for a valid API request with sudo using curl and authentication via header:
 ```
 curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "http://example.com/api/v3/projects"
 ```
+
 ```
 curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects"
 ```
@@ -130,24 +125,21 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://
 When listing resources you can pass the following parameters:
-+ `page` (default: `1`) - page number
-+ `per_page` (default: `20`, max: `100`) - number of items to list per page
-[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response.
-These have `rel` prev/next/first/last and contain the relevant url.
-Please use these instead of generating your own urls.
+- `page` (default: `1`) - page number
+- `per_page` (default: `20`, max: `100`) - number of items to list per page
+[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own urls.
 ## id vs iid
-When you work with API you may notice two similar fields in api entites: id and iid. 
-The main difference between them is scope. Example: 
-Issue 
-  id: 46
-  iid: 5
-* id - is uniq across all Issues table. It used for any api calls. 
-* iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid. 
-So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`
-But when you want to create a link to web page - use  `http:://host/project/issues/:iid.json`
+When you work with API you may notice two similar fields in api entites: id and iid. The main difference between them is scope. Example: 
+
+Issue:
+    id: 46
+    iid: 5
+- id - is uniq across all Issues table. It used for any api calls. 
+- iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid. 
+So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`. But when you want to create a link to web page - use  `http:://host/project/issues/:iid.json`

doc/api/branches.md

@@ -10,7 +10,7 @@ GET /projects/:id/repository/branches
 Parameters:
-+ `id` (required) - The ID of a project
+- `id` (required) - The ID of a project
 ```json
 [
@@ -52,8 +52,8 @@ GET /projects/:id/repository/branches/:branch
 Parameters:
-+ `id` (required) - The ID of a project
-+ `branch` (required) - The name of the branch
+- `id` (required) - The ID of a project
+- `branch` (required) - The name of the branch
 ```json
 {
@@ -82,7 +82,6 @@ Parameters:
 }
 ```
-
 ## Protect repository branch
 Protects a single project repository branch. This is an idempotent function, protecting an already
@@ -94,8 +93,8 @@ PUT /projects/:id/repository/branches/:branch/protect
 Parameters:
-+ `id` (required) - The ID of a project
-+ `branch` (required) - The name of the branch
+- `id` (required) - The ID of a project
+- `branch` (required) - The name of the branch
 ```json
 {
@@ -124,7 +123,6 @@ Parameters:
 }
 ```
-
 ## Unprotect repository branch
 Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
@@ -136,8 +134,8 @@ PUT /projects/:id/repository/branches/:branch/unprotect
 Parameters:
-+ `id` (required) - The ID of a project
-+ `branch` (required) - The name of the branch
+- `id` (required) - The ID of a project
+- `branch` (required) - The name of the branch
 ```json
 {
@@ -168,16 +166,15 @@ Parameters:
 ## Create repository branch
-
 ```
 POST /projects/:id/repository/branches
 ```
 Parameters:
-+ `id` (required) - The ID of a project
-+  `branch_name` (required) - The name of the branch
-+  `ref` (required) - Create branch from commit sha or existing branch
+- `id` (required) - The ID of a project
+- `branch_name` (required) - The name of the branch
+- `ref` (required) - Create branch from commit sha or existing branch
 ```json
 {

doc/api/commits.md

@@ -10,8 +10,8 @@ GET /projects/:id/repository/commits
 Parameters:
-+ `id` (required) - The ID of a project
-+ `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
+- `id` (required) - The ID of a project
+- `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
 ```json
 [
@@ -44,8 +44,8 @@ GET /projects/:id/repository/commits/:sha
 Parameters:
-+ `id` (required) - The ID of a project
-+ `sha` (required) - The commit hash or name of a repository branch or tag
+- `id` (required) - The ID of a project
+- `sha` (required) - The commit hash or name of a repository branch or tag
 ```json
 {
@@ -63,7 +63,6 @@ Parameters:
 }
 ```
-
 ## Get the diff of a commit
 Get the diff of a commit in a project.
@@ -74,8 +73,8 @@ GET /projects/:id/repository/commits/:sha/diff
 Parameters:
-+ `id` (required) - The ID of a project
-+ `sha` (required) - The name of a repository branch or tag or if not given the default branch
+- `id` (required) - The ID of a project
+- `sha` (required) - The name of a repository branch or tag or if not given the default branch
 ```json
 [
@@ -91,5 +90,3 @@ Parameters:
   }
 ]
 ```
-
-

doc/api/deploy_keys.md

 # Deploy Keys
-### List deploy keys
+## List deploy keys
 Get a list of a project's deploy keys.
@@ -10,7 +10,7 @@ GET /projects/:id/keys
 Parameters:
-+ `id` (required) - The ID of the project
+- `id` (required) - The ID of the project
 ```json
 [
@@ -29,8 +29,7 @@ Parameters:
 ]
 ```
-
-### Single deploy key
+## Single deploy key
 Get a single key.
@@ -40,8 +39,8 @@ GET /projects/:id/keys/:key_id
 Parameters:
-+ `id` (required) - The ID of the project
-+ `key_id` (required) - The ID of the deploy key
+- `id` (required) - The ID of the project
+- `key_id` (required) - The ID of the deploy key
 ```json
 {
@@ -52,8 +51,7 @@ Parameters:
 }
 ```
-
-### Add deploy key
+## Add deploy key
 Creates a new deploy key for a project.
 If deploy key already exists in another project - it will be joined to project but only if original one was is accessible by same user
@@ -64,12 +62,11 @@ POST /projects/:id/keys
 Parameters:
-+ `id` (required) - The ID of the project
-+ `title` (required) - New deploy key's title
-+ `key` (required) - New deploy key
-
-### Delete deploy key
+- `id` (required) - The ID of the project
+- `title` (required) - New deploy key's title
+- `key` (required) - New deploy key
+## Delete deploy key
 Delete a deploy key from a project
@@ -79,6 +76,5 @@ DELETE /projects/:id/keys/:key_id
 Parameters:
-+ `id` (required) - The ID of the project
-+ `key_id` (required) - The ID of the deploy key
-
+- `id` (required) - The ID of the project
+- `key_id` (required) - The ID of the deploy key

doc/api/issues.md

@@ -73,7 +73,6 @@ GET /issues
 ]
 ```
-
 ## List project issues
 Get a list of project issues. This function accepts pagination parameters `page` and `per_page`
@@ -85,8 +84,7 @@ GET /projects/:id/issues
 Parameters:
-+ `id` (required) - The ID of a project
-
+- `id` (required) - The ID of a project
 ## Single issue
@@ -98,8 +96,8 @@ GET /projects/:id/issues/:issue_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of a project issue
+- `id` (required) - The ID of a project
+- `issue_id` (required) - The ID of a project issue
 ```json
 {
@@ -142,7 +140,6 @@ Parameters:
 }
 ```
-
 ## New issue
 Creates a new project issue.
@@ -153,13 +150,12 @@ POST /projects/:id/issues
 Parameters:
-+ `id` (required) - The ID of a project
-+ `title` (required) - The title of an issue
-+ `description` (optional) - The description of an issue
-+ `assignee_id` (optional) - The ID of a user to assign issue
-+ `milestone_id` (optional) - The ID of a milestone to assign issue
-+ `labels` (optional) - Comma-separated label names for an issue
-
+- `id` (required) - The ID of a project
+- `title` (required) - The title of an issue
+- `description` (optional) - The description of an issue
+- `assignee_id` (optional) - The ID of a user to assign issue
+- `milestone_id` (optional) - The ID of a milestone to assign issue
+- `labels` (optional) - Comma-separated label names for an issue
 ## Edit issue
@@ -171,21 +167,18 @@ PUT /projects/:id/issues/:issue_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of a project's issue
-+ `title` (optional) - The title of an issue
-+ `description` (optional) - The description of an issue
-+ `assignee_id` (optional) - The ID of a user to assign issue
-+ `milestone_id` (optional) - The ID of a milestone to assign issue
-+ `labels` (optional) - Comma-separated label names for an issue
-+ `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it)
-
+- `id` (required) - The ID of a project
+- `issue_id` (required) - The ID of a project's issue
+- `title` (optional) - The title of an issue
+- `description` (optional) - The description of an issue
+- `assignee_id` (optional) - The ID of a user to assign issue
+- `milestone_id` (optional) - The ID of a milestone to assign issue
+- `labels` (optional) - Comma-separated label names for an issue
+- `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it)
 ## Delete existing issue (**Deprecated**)
-The function is deprecated and returns a `405 Method Not Allowed`
-error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with
-parameter `closed` set to 1.
+The function is deprecated and returns a `405 Method Not Allowed` error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with parameter `closed` set to 1.
 ```
 DELETE /projects/:id/issues/:issue_id
@@ -193,8 +186,8 @@ DELETE /projects/:id/issues/:issue_id
 Parameters:
-+ `id` (required) - The project ID
-+ `issue_id` (required) - The ID of the issue
+- `id` (required) - The project ID
+- `issue_id` (required) - The ID of the issue
 ## Comments on issues

doc/api/merge_requests.md

@@ -2,11 +2,7 @@
 ## List merge requests
-Get all merge requests for this project.
-The `state` parameter can be used to get only merge requests with a
-given state (`opened`, `closed`, or `merged`) or all of them (`all`).
-The pagination parameters `page` and `per_page` can be used to restrict the
-list of merge requests.
+Get all merge requests for this project. The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests.
 ```
 GET /projects/:id/merge_requests
@@ -16,8 +12,8 @@ GET /projects/:id/merge_requests?state=all
 Parameters:
-+ `id` (required) - The ID of a project
-+ `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed`
+- `id` (required) - The ID of a project
+- `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed`
 ```json
 [
@@ -51,7 +47,6 @@ Parameters:
 ]
 ```
-
 ## Get single MR
 Shows information about a single merge request.
@@ -62,8 +57,8 @@ GET /projects/:id/merge_request/:merge_request_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `merge_request_id` (required) - The ID of MR
+- `id` (required) - The ID of a project
+- `merge_request_id` (required) - The ID of MR
 ```json
 {
@@ -95,7 +90,6 @@ Parameters:
 }
 ```
-
 ## Create MR
 Creates a new merge request.
@@ -106,12 +100,12 @@ POST /projects/:id/merge_requests
 Parameters:
-+ `id` (required) - The ID of a project
-+ `source_branch` (required)     - The source branch
-+ `target_branch` (required)     - The target branch
-+ `assignee_id` (optional)       - Assignee user ID
-+ `title` (required)             - Title of MR
-+ `target_project_id` (optional) - The target project (numeric id)
+- `id` (required)                - The ID of a project
+- `source_branch` (required)     - The source branch
+- `target_branch` (required)     - The target branch
+- `assignee_id` (optional)       - Assignee user ID
+- `title` (required)             - Title of MR
+- `target_project_id` (optional) - The target project (numeric id)
 ```json
 {
@@ -142,7 +136,6 @@ Parameters:
 }
 ```
-
 ## Update MR
 Updates an existing merge request. You can change branches, title, or even close the MR.
@@ -153,13 +146,13 @@ PUT /projects/:id/merge_request/:merge_request_id
 Parameters:
-+ `id` (required)               - The ID of a project
-+ `merge_request_id` (required) - ID of MR
-+ `source_branch`               - The source branch
-+ `target_branch`               - The target branch
-+ `assignee_id`                 - Assignee user ID
-+ `title`                       - Title of MR
-+ `state_event`                 - New state (close|reopen|merge)
+- `id` (required)               - The ID of a project
+- `merge_request_id` (required) - ID of MR
+- `source_branch`               - The source branch
+- `target_branch`               - The target branch
+- `assignee_id`                 - Assignee user ID
+- `title`                       - Title of MR
+- `state_event`                 - New state (close|reopen|merge)
 ```json
 {
@@ -190,13 +183,16 @@ Parameters:
 }
 ```
-
 ## Accept MR
 Merge changes submitted with MR usign this API.
+
 If merge success you get 200 OK.
+
 If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged'
+
 If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed' 
+
 If you dont have permissions to accept this merge request - you get 401
 ```
@@ -205,9 +201,9 @@ PUT /projects/:id/merge_request/:merge_request_id/merge
 Parameters:
-+ `id` (required)               - The ID of a project
-+ `merge_request_id` (required) - ID of MR
-+ `merge_commit_message` (optional) - Custom merge commit message
+- `id` (required)                   - The ID of a project
+- `merge_request_id` (required)     - ID of MR
+- `merge_commit_message` (optional) - Custom merge commit message
 ```json
 {
@@ -238,7 +234,6 @@ Parameters:
 }
 ```
-
 ## Post comment to MR
 Adds a comment to a merge request.
@@ -249,10 +244,9 @@ POST /projects/:id/merge_request/:merge_request_id/comments
 Parameters:
-+ `id` (required) - The ID of a project
-+ `merge_request_id` (required) - ID of merge request
-+ `note` (required) - Text of comment
-
+- `id` (required)               - The ID of a project
+- `merge_request_id` (required) - ID of merge request
+- `note` (required)             - Text of comment
 ```json
 {
@@ -268,7 +262,6 @@ Parameters:
 }
 ```
-
 ## Get the comments on a MR
 Gets all the comments associated with a merge request.
@@ -279,8 +272,8 @@ GET /projects/:id/merge_request/:merge_request_id/comments
 Parameters:
-+ `id` (required) - The ID of a project
-+ `merge_request_id` (required) - ID of merge request
+- `id` (required)               - The ID of a project
+- `merge_request_id` (required) - ID of merge request
 ```json
 [

doc/api/milestones.md

@@ -26,8 +26,7 @@ GET /projects/:id/milestones
 Parameters:
-+ `id` (required) - The ID of a project
-
+- `id` (required) - The ID of a project
 ## Get single milestone
@@ -39,9 +38,8 @@ GET /projects/:id/milestones/:milestone_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `milestone_id` (required) - The ID of a project milestone
-
+- `id` (required) - The ID of a project
+- `milestone_id` (required) - The ID of a project milestone
 ## Create new milestone
@@ -53,11 +51,10 @@ POST /projects/:id/milestones
 Parameters:
-+ `id` (required) - The ID of a project
-+ `title` (required) - The title of an milestone
-+ `description` (optional) - The description of the milestone
-+ `due_date` (optional) - The due date of the milestone
-
+- `id` (required) - The ID of a project
+- `title` (required) - The title of an milestone
+- `description` (optional) - The description of the milestone
+- `due_date` (optional) - The due date of the milestone
 ## Edit milestone
@@ -69,10 +66,9 @@ PUT /projects/:id/milestones/:milestone_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `milestone_id` (required) - The ID of a project milestone
-+ `title` (optional) - The title of a milestone
-+ `description` (optional) - The description of a milestone
-+ `due_date` (optional) - The due date of the milestone
-+ `state_event` (optional) - The state event of the milestone (close|activate)
-
+- `id` (required) - The ID of a project
+- `milestone_id` (required) - The ID of a project milestone
+- `title` (optional) - The title of a milestone
+- `description` (optional) - The description of a milestone
+- `due_date` (optional) - The due date of the milestone
+- `state_event` (optional) - The state event of the milestone (close|activate)

doc/api/project_snippets.md

@@ -10,8 +10,7 @@ GET /projects/:id/snippets
 Parameters:
-+ `id` (required) - The ID of a project
-
+- `id` (required) - The ID of a project
 ## Single snippet
@@ -23,8 +22,8 @@ GET /projects/:id/snippets/:snippet_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a project's snippet
+- `id` (required) - The ID of a project
+- `snippet_id` (required) - The ID of a project's snippet
 ```json
 {
@@ -45,7 +44,6 @@ Parameters:
 }
 ```
-
 ## Create new snippet
 Creates a new project snippet. The user must have permission to create new snippets.
@@ -56,11 +54,10 @@ POST /projects/:id/snippets
 Parameters:
-+ `id` (required) - The ID of a project
-+ `title` (required) - The title of a snippet
-+ `file_name` (required) - The name of a snippet file
-+ `code` (required) - The content of a snippet
-
+- `id` (required) - The ID of a project
+- `title` (required) - The title of a snippet
+- `file_name` (required) - The name of a snippet file
+- `code` (required) - The content of a snippet
 ## Update snippet
@@ -72,12 +69,11 @@ PUT /projects/:id/snippets/:snippet_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a project's snippet
-+ `title` (optional) - The title of a snippet
-+ `file_name` (optional) - The name of a snippet file
-+ `code` (optional) - The content of a snippet
-
+- `id` (required) - The ID of a project
+- `snippet_id` (required) - The ID of a project's snippet
+- `title` (optional) - The title of a snippet
+- `file_name` (optional) - The name of a snippet file
+- `code` (optional) - The content of a snippet
 ## Delete snippet
@@ -90,9 +86,8 @@ DELETE /projects/:id/snippets/:snippet_id
 Parameters:
-+ `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a project's snippet
-
+- `id` (required) - The ID of a project
+- `snippet_id` (required) - The ID of a project's snippet
 ## Snippet content
@@ -104,5 +99,5 @@ GET /projects/:id/snippets/:snippet_id/raw
 Parameters:
-+ `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a project's snippet
+- `id` (required) - The ID of a project
+- `snippet_id` (required) - The ID of a project's snippet

doc/api/repository_files.md

@@ -4,12 +4,11 @@
 ## Create, read, update and delete repository files using this API
-- - -
+---
 ## Get file from repository
-Allows you to receive information about file in repository like name, size, content.
-Note that file content is Base64 encoded.
+Allows you to receive information about file in repository like name, size, content. Note that file content is Base64 encoded.
 ```
 GET /projects/:id/repository/files
@@ -32,8 +31,8 @@ Example response:
 Parameters:
-+ `file_path` (required) - Full path to new file. Ex. lib/class.rb
-+ `ref` (required) - The name of branch, tag or commit
+- `file_path` (required) - Full path to new file. Ex. lib/class.rb
+- `ref` (required) - The name of branch, tag or commit
 ## Create new file in repository
@@ -52,11 +51,11 @@ Example response:
 Parameters:
-+ `file_path` (required) - Full path to new file. Ex. lib/class.rb
-+ `branch_name` (required) - The name of branch
-+ `encoding` (optional) - 'text' or 'base64'. Text is default.
-+ `content` (required) - File content
-+ `commit_message` (required) - Commit message
+- `file_path` (required) - Full path to new file. Ex. lib/class.rb
+- `branch_name` (required) - The name of branch
+- `encoding` (optional) - 'text' or 'base64'. Text is default.
+- `content` (required) - File content
+- `commit_message` (required) - Commit message
 ## Update existing file in repository
@@ -75,11 +74,11 @@ Example response:
 Parameters:
-+ `file_path` (required) - Full path to file. Ex. lib/class.rb
-+ `branch_name` (required) - The name of branch
-+ `encoding` (optional) - 'text' or 'base64'. Text is default.
-+ `content` (required) - New file content
-+ `commit_message` (required) - Commit message
+- `file_path` (required) - Full path to file. Ex. lib/class.rb
+- `branch_name` (required) - The name of branch
+- `encoding` (optional) - 'text' or 'base64'. Text is default.
+- `content` (required) - New file content
+- `commit_message` (required) - Commit message
 ## Delete existing file in repository
@@ -98,7 +97,6 @@ Example response:
 Parameters:
-+ `file_path` (required) - Full path to file. Ex. lib/class.rb
-+ `branch_name` (required) - The name of branch
-+ `commit_message` (required) - Commit message
-
+- `file_path` (required) - Full path to file. Ex. lib/class.rb
+- `branch_name` (required) - The name of branch
+- `commit_message` (required) - Commit message

doc/api/system_hooks.md

@@ -2,7 +2,7 @@
 All methods require admin authorization.
-The url endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks).
+The URL endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks).
 ## List system hooks
@@ -14,7 +14,7 @@ GET /hooks
 Parameters:
-+ **none**
+- **none**
 ```json
 [
@@ -34,8 +34,7 @@ POST /hooks
 Parameters:
-+ `url` (required) - The hook URL
-
+- `url` (required) - The hook URL
 ## Test system hook
@@ -45,7 +44,7 @@ GET /hooks/:id
 Parameters:
-+ `id` (required) - The ID of hook
+- `id` (required) - The ID of hook
 ```json
 {
@@ -60,8 +59,7 @@ Parameters:
 ## Delete system hook
-Deletes a system hook. This is an idempotent API function and returns `200 Ok` even if the hook
-is not available. If the hook is deleted it is also returned as JSON.
+Deletes a system hook. This is an idempotent API function and returns `200 Ok` even if the hook is not available. If the hook is deleted it is also returned as JSON.
 ```
 DELETE /hooks/:id
@@ -69,4 +67,4 @@ DELETE /hooks/:id
 Parameters:
-+ `id` (required) - The ID of hook
+- `id` (required) - The ID of hook

doc/api/users.md

@@ -3,6 +3,7 @@
 ## List users
 Get a list of users.
+
 This function takes pagination parameters `page` and `per_page` to restrict the list of users.
 ```
@@ -53,8 +54,7 @@ GET /users
 ]
 ```
-You can search for a users by email or username with:
-`/users?search=John`
+You can search for a users by email or username with: `/users?search=John`
 Also see `def search query` in `app/models/user.rb`.
@@ -68,7 +68,7 @@ GET /users/:id
 Parameters:
-+ `id` (required) - The ID of a user
+- `id` (required) - The ID of a user
 ```json
 {
@@ -93,7 +93,6 @@ Parameters:
 }
 ```
-
 ## User creation
 Creates a new user. Note only administrators can create new users.
@@ -104,21 +103,20 @@ POST /users
 Parameters:
-+ `email` (required)            - Email
-+ `password` (required)         - Password
-+ `username` (required)         - Username
-+ `name` (required)             - Name
-+ `skype` (optional)            - Skype ID
-+ `linkedin` (optional)         - Linkedin
-+ `twitter` (optional)          - Twitter account
-+ `website_url` (optional)      - Website url
-+ `projects_limit` (optional)   - Number of projects user can create
-+ `extern_uid` (optional)       - External UID
-+ `provider` (optional)         - External provider name
-+ `bio` (optional)              - User's bio
-+ `admin` (optional)            - User is admin - true or false (default)
-+ `can_create_group` (optional) - User can create groups - true or false
-
+- `email` (required)            - Email
+- `password` (required)         - Password
+- `username` (required)         - Username
+- `name` (required)             - Name
+- `skype` (optional)            - Skype ID
+- `linkedin` (optional)         - Linkedin
+- `twitter` (optional)          - Twitter account
+- `website_url` (optional)      - Website url
+- `projects_limit` (optional)   - Number of projects user can create
+- `extern_uid` (optional)       - External UID
+- `provider` (optional)         - External provider name
+- `bio` (optional)              - User's bio
+- `admin` (optional)            - User is admin - true or false (default)
+- `can_create_group` (optional) - User can create groups - true or false
 ## User modification
@@ -130,30 +128,26 @@ PUT /users/:id
 Parameters:
-+ `email`                             - Email
-+ `username`                          - Username
-+ `name`                              - Name
-+ `password`                          - Password
-+ `skype`                             - Skype ID
-+ `linkedin`                          - Linkedin
-+ `twitter`                           - Twitter account
-+ `website_url`                       - Website url
-+ `projects_limit`                    - Limit projects each user can create
-+ `extern_uid`                        - External UID
-+ `provider`                          - External provider name
-+ `bio`                               - User's bio
-+ `admin` (optional)                  - User is admin - true or false (default)
-+ `can_create_group` (optional)       - User can create groups - true or false
-
-Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would
-be more appropriate, e.g. when renaming the email address to some existing one.
-
+- `email`                             - Email
+- `username`                          - Username
+- `name`                              - Name
+- `password`                          - Password
+- `skype`                             - Skype ID
+- `linkedin`                          - Linkedin
+- `twitter`                           - Twitter account
+- `website_url`                       - Website url
+- `projects_limit`                    - Limit projects each user can create
+- `extern_uid`                        - External UID
+- `provider`                          - External provider name
+- `bio`                               - User's bio
+- `admin` (optional)                  - User is admin - true or false (default)
+- `can_create_group` (optional)       - User can create groups - true or false
+
+Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one.
 ## User deletion
-Deletes a user. Available only for administrators. This is an idempotent function, calling this function
-for a non-existent user id still returns a status code `200 Ok`. The JSON response differs if the user
-was actually deleted or not. In the former the user is returned and in the latter not.
+Deletes a user. Available only for administrators. This is an idempotent function, calling this function for a non-existent user id still returns a status code `200 Ok`. The JSON response differs if the user was actually deleted or not. In the former the user is returned and in the latter not.
 ```
 DELETE /users/:id
@@ -161,8 +155,7 @@ DELETE /users/:id
 Parameters:
-+ `id` (required) - The ID of the user
-
+- `id` (required) - The ID of the user
 ## Current user
@@ -194,7 +187,6 @@ GET /user
 }
 ```
-
 ## List SSH keys
 Get a list of currently authenticated user's SSH keys.
@@ -220,7 +212,7 @@ GET /user/keys
 Parameters:
-+ **none**
+- **none**
 ## List SSH keys for user
@@ -232,8 +224,7 @@ GET /users/:uid/keys
 Parameters:
-+ `uid` (required) - id of specified user
-
+- `uid` (required) - id of specified user
 ## Single SSH key
@@ -245,7 +236,7 @@ GET /user/keys/:id
 Parameters:
-+ `id` (required) - The ID of an SSH key
+- `id` (required) - The ID of an SSH key
 ```json
 {
@@ -255,7 +246,6 @@ Parameters:
 }
 ```
-
 ## Add SSH key
 Creates a new key owned by the currently authenticated user.
@@ -266,9 +256,8 @@ POST /user/keys
 Parameters:
-+ `title` (required) - new SSH Key's title
-+ `key` (required) - new SSH key
-
+- `title` (required) - new SSH Key's title
+- `key` (required) - new SSH key
 ## Add SSH key for user
@@ -280,17 +269,15 @@ POST /users/:id/keys
 Parameters:
-+ `id` (required) - id of specified user
-+ `title` (required) - new SSH Key's title
-+ `key` (required) - new SSH key
-Will return created key with status `201 Created` on success, or `404 Not
-found` on fail.
-## Delete SSH key
-Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already
-deleted or not available results in `200 Ok`.
+- `id` (required) - id of specified user
+- `title` (required) - new SSH Key's title
+- `key` (required) - new SSH key
+Will return created key with status `201 Created` on success, or `404 Not found` on fail.
+## Delete SSH key for current user
+Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already deleted or not available results in `200 Ok`.
 ```
 DELETE /user/keys/:id
@@ -298,9 +285,9 @@ DELETE /user/keys/:id
 Parameters:
-+ `id` (required) - SSH key ID
-## Delete SSH key
+- `id` (required) - SSH key ID
+## Delete SSH key for given user
 Deletes key owned by a specified user. Available only for admin.
@@ -310,8 +297,7 @@ DELETE /users/:uid/keys/:id
 Parameters:
-+ `uid` (required) - id of specified user
-+ `id` (required) - SSH key ID
+- `uid` (required) - id of specified user
+- `id` (required) - SSH key ID
 Will return `200 Ok` on success, or `404 Not found` if either user or key cannot be found.
-

doc/development/README.md

-## Development 
-+ [Architecture](architecture.md) of GitLab
-+ [Shell commands](shell_commands.md) in the GitLab codebase
-+ [Rake tasks](rake_tasks.md) for development
+# Development 
+- [Architecture](architecture.md) of GitLab
+- [Shell commands](shell_commands.md) in the GitLab codebase
+- [Rake tasks](rake_tasks.md) for development

doc/development/architecture.md

 # GitLab Architecture Overview
----
-# Software delivery
-There are two editions of GitLab: [Enterprise Edition](https://www.gitlab.com/gitlab-ee/) (EE) and [Community Edition](https://www.gitlab.com/gitlab-ce/) (CE).
-GitLab CE is delivered via git from the [gitlabhq repository](https://gitlab.com/gitlab-org/gitlab-ce/tree/master).
-New versions of GitLab are released in stable branches and the master branch is for bleeding edge development.
-EE releases are available not long after CE releases.
-To obtain the GitLab EE there is a [repository at gitlab.com](https://gitlab.com/subscribers/gitlab-ee).
-For more information about the release process see the section 'New versions and upgrading' in the readme.
-Both EE and CE require an add-on component called gitlab-shell.
-It is obtained from the [gitlab-shell repository](https://gitlab.com/gitlab-org/gitlab-shell/tree/master).
-New versions are usually tags but staying on the master branch will give you the latest stable version.
-New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical.
-# System Layout
+## Software delivery
+There are two editions of GitLab: [Enterprise Edition](https://www.gitlab.com/gitlab-ee/) (EE) and [Community Edition](https://www.gitlab.com/gitlab-ce/) (CE). GitLab CE is delivered via git from the [gitlabhq repository](https://gitlab.com/gitlab-org/gitlab-ce/tree/master). New versions of GitLab are released in stable branches and the master branch is for bleeding edge development.
+EE releases are available not long after CE releases. To obtain the GitLab EE there is a [repository at gitlab.com](https://gitlab.com/subscribers/gitlab-ee). For more information about the release process see the section 'New versions and upgrading' in the readme.
+Both EE and CE require an add-on component called gitlab-shell. It is obtained from the [gitlab-shell repository](https://gitlab.com/gitlab-org/gitlab-shell/tree/master). New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical.
+## System Layout
 When referring to ~git in the pictures it means the home directory of the git user which is typically /home/git.
-GitLab is primarily installed within the `/home/git` user home directory as `git` user.
-Within the home directory is where the gitlabhq server software resides as well as the repositories (though the repository location is configurable).
-The bare repositories are located in `/home/git/repositories`.
-GitLab is a ruby on rails application so the particulars of the inner workings can be learned by studying how a ruby on rails application works.
+GitLab is primarily installed within the `/home/git` user home directory as `git` user. Within the home directory is where the gitlabhq server software resides as well as the repositories (though the repository location is configurable).
+
+The bare repositories are located in `/home/git/repositories`. GitLab is a ruby on rails application so the particulars of the inner workings can be learned by studying how a ruby on rails application works.
+
 To serve repositories over SSH there's an add-on application called gitlab-shell which is installed in `/home/git/gitlab-shell`.
-## Components
+### Components
 ![GitLab Diagram Overview](gitlab_diagram_overview.png)
-A typical install of GitLab will be on Ubuntu Linux or RHEL/CentOS.
-It uses Nginx or Apache as a web front end to proxypass the Unicorn web server.
-By default, communication between Unicorn and the front end is via a Unix domain socket but forwarding requests via TCP is also supported.
-The web front end accesses `/home/git/gitlab/public` bypassing the Unicorn server to serve static pages, uploads (e.g. avatar images or attachments), and precompiled assets.
-GitLab serves web pages and a [GitLab API](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/api) using the Unicorn web server.
-It uses Sidekiq as a job queue which, in turn, uses redis as a non-persistent database backend for job information, meta data, and incomming jobs.
-The GitLab web app uses MySQL or PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data).
-GitLab stores the bare git repositories it serves in `/home/git/repositories` by default.
-It also keeps default branch and hook information with the bare repository.
-`/home/git/gitlab-satellites` keeps checked out repositories when performing actions such as a merge request, editing files in the web interface, etc.
-The satellite repository is used by the web interface for editing repositories and the wiki which is also a git repository.
-When serving repositories over HTTP/HTTPS GitLab utilizes the GitLab API to resolve authorization and access as well as serving git objects.
-
-The add-on component gitlab-shell serves repositories over SSH.
-It manages the SSH keys within `/home/git/.ssh/authorized_keys` which should not be manually edited.
-gitlab-shell accesses the bare repositories directly to serve git objects and communicates with redis to submit jobs to Sidekiq for GitLab to process.
- gitlab-shell queries the GitLab API to determine authorization and access.
-
-## Installation Folder Summary
-To summarize here's the [directory structure of the `git` user home directory](../install/structure.md).
-## Processes
+A typical install of GitLab will be on Ubuntu Linux or RHEL/CentOS. It uses Nginx or Apache as a web front end to proxypass the Unicorn web server. By default, communication between Unicorn and the front end is via a Unix domain socket but forwarding requests via TCP is also supported. The web front end accesses `/home/git/gitlab/public` bypassing the Unicorn server to serve static pages, uploads (e.g. avatar images or attachments), and precompiled assets. GitLab serves web pages and a [GitLab API](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/api) using the Unicorn web server. It uses Sidekiq as a job queue which, in turn, uses redis as a non-persistent database backend for job information, meta data, and incomming jobs.
+The GitLab web app uses MySQL or PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data). GitLab stores the bare git repositories it serves in `/home/git/repositories` by default. It also keeps default branch and hook information with the bare repository. `/home/git/gitlab-satellites` keeps checked out repositories when performing actions such as a merge request, editing files in the web interface, etc.
+
+The satellite repository is used by the web interface for editing repositories and the wiki which is also a git repository. When serving repositories over HTTP/HTTPS GitLab utilizes the GitLab API to resolve authorization and access as well as serving git objects.
+The add-on component gitlab-shell serves repositories over SSH. It manages the SSH keys within `/home/git/.ssh/authorized_keys` which should not be manually edited. gitlab-shell accesses the bare repositories directly to serve git objects and communicates with redis to submit jobs to Sidekiq for GitLab to process. gitlab-shell queries the GitLab API to determine authorization and access.
+
+### Installation Folder Summary
+
+To summarize here's the [directory structure of the `git` user home directory](../install/structure.md).
+### Processes
     ps aux | grep '^git'
-GitLab has several components to operate.
-As a system user (i.e. any user that is not the `git` user) it requires a persistent database (MySQL/PostreSQL) and redis database.
-It also uses Apache httpd or nginx to proxypass Unicorn.
-As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server running on port `8080` by default).
-Under the gitlab user there are normally 4 processes: `unicorn_rails master` (1 process), `unicorn_rails worker` (2 processes), `sidekiq` (1 process).
-## Repository access
-Repositories get accessed via HTTP or SSH.
-HTTP cloning/push/pull utilizes the GitLab API and SSH cloning is handled by gitlab-shell (previously explained).
-# Troubleshooting
+GitLab has several components to operate. As a system user (i.e. any user that is not the `git` user) it requires a persistent database (MySQL/PostreSQL) and redis database. It also uses Apache httpd or nginx to proxypass Unicorn. As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server running on port `8080` by default). Under the gitlab user there are normally 4 processes: `unicorn_rails master` (1 process), `unicorn_rails worker` (2 processes), `sidekiq` (1 process).
+### Repository access
+Repositories get accessed via HTTP or SSH. HTTP cloning/push/pull utilizes the GitLab API and SSH cloning is handled by gitlab-shell (previously explained).
+## Troubleshooting
 See the README for more information.
-## Init scripts of the services
+### Init scripts of the services
 The GitLab init script starts and stops Unicorn and Sidekiq.
@@ -115,61 +91,59 @@ $ /etc/init.d/postgresql
 Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [version ..]
 ```
-## Log locations of the services
+### Log locations of the services
 Note: `/home/git/` is shorthand for `/home/git`.
 gitlabhq (includes Unicorn and Sidekiq logs)
-* `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `githost.log`, `satellites.log`, and `unicorn.stderr.log` normally.
+- `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `githost.log`, `satellites.log`, and `unicorn.stderr.log` normally.
 gitlab-shell
-* `/home/git/gitlab-shell/gitlab-shell.log`
+- `/home/git/gitlab-shell/gitlab-shell.log`
 ssh
-* `/var/log/auth.log` auth log (on Ubuntu).
-* `/var/log/secure` auth log (on RHEL).
+- `/var/log/auth.log` auth log (on Ubuntu).
+- `/var/log/secure` auth log (on RHEL).
 nginx
-* `/var/log/nginx/` contains error and access logs.
+- `/var/log/nginx/` contains error and access logs.
 Apache httpd
-* [Explanation of apache logs](http://httpd.apache.org/docs/2.2/logs.html).
-* `/var/log/apache2/` contains error and output logs (on Ubuntu).
-* `/var/log/httpd/` contains error and output logs (on RHEL).
+- [Explanation of apache logs](http://httpd.apache.org/docs/2.2/logs.html).
+- `/var/log/apache2/` contains error and output logs (on Ubuntu).
+- `/var/log/httpd/` contains error and output logs (on RHEL).
 redis
-* `/var/log/redis/redis.log` there are also logrotated logs there.
+- `/var/log/redis/redis.log` there are also logrotated logs there.
 PostgreSQL
-* `/var/log/postgresql/*`
+- `/var/log/postgresql/*`
 MySQL
-* `/var/log/mysql/*`
-* `/var/log/mysql.*`
-## GitLab specific config files
-GitLab has configuration files located in `/home/git/gitlab/config/*`.
-Commonly referenced config files include:
-* `gitlab.yml` - GitLab configuration.
-* `unicorn.rb` - Unicorn web server settings.
-* `database.yml` - Database connection settings.
+- `/var/log/mysql/*`
+- `/var/log/mysql.*`
+### GitLab specific config files
+GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced config files include:
+- `gitlab.yml` - GitLab configuration.
+- `unicorn.rb` - Unicorn web server settings.
+- `database.yml` - Database connection settings.
 gitlab-shell has a configuration file at `/home/git/gitlab-shell/config.yml`.
-## Maintenance Tasks
-[GitLab](https://gitlab.com/gitlab-org/gitlab-ce/tree/master) provides rake tasks with which you see version information and run a quick check on your configuration to ensure it is configured properly within the application.
-See [maintenance rake tasks](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/raketasks/maintenance.md).
+### Maintenance Tasks
+[GitLab](https://gitlab.com/gitlab-org/gitlab-ce/tree/master) provides rake tasks with which you see version information and run a quick check on your configuration to ensure it is configured properly within the application. See [maintenance rake tasks](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/raketasks/maintenance.md).
 In a nutshell, do the following:
 ```
@@ -179,5 +153,4 @@ bundle exec rake gitlab:env:info RAILS_ENV=production
 bundle exec rake gitlab:check RAILS_ENV=production
 ```
-Note: It is recommended to log into the `git` user using `sudo -i -u git` or `sudo su - git`.
-While the sudo commands provided by gitlabhq work in Ubuntu they do not always work in RHEL.
\ No newline at end of file
+Note: It is recommended to log into the `git` user using `sudo -i -u git` or `sudo su - git`. While the sudo commands provided by gitlabhq work in Ubuntu they do not always work in RHEL.

doc/development/shell_commands.md

@@ -8,9 +8,7 @@
 ## Use File and FileUtils instead of shell commands
-Sometimes we invoke basic Unix commands via the shell when there is also a Ruby API for doing it.
-Use the Ruby API if it exists.
-http://www.ruby-doc.org/stdlib-2.0.0/libdoc/fileutils/rdoc/FileUtils.html#module-FileUtils-label-Module+Functions
+Sometimes we invoke basic Unix commands via the shell when there is also a Ruby API for doing it. Use the Ruby API if it exists. <http://www.ruby-doc.org/stdlib-2.0.0/libdoc/fileutils/rdoc/FileUtils.html#module-FileUtils-label-Module+Functions>
 ```ruby
 # Wrong
@@ -30,12 +28,7 @@ This coding style could have prevented CVE-2013-4490.
 ## Bypass the shell by splitting commands into separate tokens
-When we pass shell commands as a single string to Ruby, Ruby will let `/bin/sh` evaluate the entire string.
-Essentially, we are asking the shell to evaluate a one-line script.
-This creates a risk for shell injection attacks.
-It is better to split the shell command into tokens ourselves.
-Sometimes we use the scripting capabilities of the shell to change the working directory or set environment variables.
-All of this can also be achieved securely straight from Ruby
+When we pass shell commands as a single string to Ruby, Ruby will let `/bin/sh` evaluate the entire string. Essentially, we are asking the shell to evaluate a one-line script. This creates a risk for shell injection attacks. It is better to split the shell command into tokens ourselves. Sometimes we use the scripting capabilities of the shell to change the working directory or set environment variables. All of this can also be achieved securely straight from Ruby
 ```ruby
 # Wrong
@@ -55,8 +48,7 @@ This coding style could have prevented CVE-2013-4546.
 ## Separate options from arguments with --
-Make the difference between options and arguments clear to the argument parsers of system commands with `--`.
-This is supported by many but not all Unix commands.
+Make the difference between options and arguments clear to the argument parsers of system commands with `--`. This is supported by many but not all Unix commands.
 To understand what `--` does, consider the problem below.
@@ -68,9 +60,7 @@ cat: illegal option -- l
 usage: cat [-benstuv] [file ...]
 ```
-In the example above, the argument parser of `cat` assumes that `-l` is an option.
-The solution in the example above is to make it clear to `cat` that `-l` is really an argument, not an option.
-Many Unix command line tools follow the convention of separating options from arguments with `--`.
+In the example above, the argument parser of `cat` assumes that `-l` is an option. The solution in the example above is to make it clear to `cat` that `-l` is really an argument, not an option. Many Unix command line tools follow the convention of separating options from arguments with `--`.
 ```
 # Example (continued)
@@ -91,9 +81,7 @@ This coding style could have prevented CVE-2013-4582.
 ## Do not use the backticks
-Capturing the output of shell commands with backticks reads nicely, but you are forced to pass the command as one string to the shell.
-We explained above that this is unsafe.
-In the main GitLab codebase, the solution is to use `Gitlab::Popen.popen` instead.
+Capturing the output of shell commands with backticks reads nicely, but you are forced to pass the command as one string to the shell. We explained above that this is unsafe. In the main GitLab codebase, the solution is to use `Gitlab::Popen.popen` instead.
 ```ruby
 # Wrong

doc/install/README.md

-+ [Installation](installation.md)
-+ [Requirements](requirements.md)
-+ [Structure](structure.md)
-+ [Database MySQL](database_mysql.md)
+# Installation
+
+- [Installation](installation.md)
+- [Requirements](requirements.md)
+- [Structure](structure.md)
+- [Database MySQL](database_mysql.md)