diff --git a/source/guides/git.html.haml b/source/guides/git.html.haml
deleted file mode 100644
index 33bf0d5ebd..0000000000
--- a/source/guides/git.html.haml
+++ /dev/null
@@ -1,197 +0,0 @@
----
-title: How to install gems from git repositories
----
-.container.guide
-  %h2 How to install gems from git repositories
-
-  .contents
-    .bullet
-      .description
-        %p
-          This document is written for Bundler 2.1 or higher.
-          Use `bundle config X Y` instead of `bundle config set X Y`
-          if you are still using Bundler 2.0 or earlier, which were already deprecated.
-        %p
-          Bundler has the ability to install gems directly from git repositories. Installing
-          a gem using git is as easy as adding a gem to your Gemfile.
-        %p
-          Note that because RubyGems lacks the ability to handle gems from git, any gems
-          installed from a git repository will not show up in <code>gem list</code>.
-          They will, however, be available after running <code>Bundler.setup</code>.
-
-    .bullet
-      .description
-        Specify that a gem should come from a git
-        repository with a .gemspec at its root
-      :code
-        # lang: ruby
-        gem 'rack', git: 'https://github.com/rack/rack'
-    .bullet
-      .description
-        If there is no .gemspec at the root of
-        a git repository, you must specify a version
-        that bundler should use when resolving
-        dependencies
-      :code
-        # lang: ruby
-        gem 'nokogiri', '1.7.0.1', git: 'https://github.com/sparklemotion/nokogiri'
-    .bullet
-      .description
-        If the gem is located within a subdirectory of
-        a git repository, you can use the <code>:glob</code> option
-        to specify the location of its .gemspec
-      :code
-        # lang: ruby
-        gem 'cf-copilot', git: 'https://github.com/cloudfoundry/copilot', glob: 'sdk/ruby/*.gemspec'
-    .bullet
-      .description
-        Specify that a git repository containing
-        multiple .gemspec files should be treated
-        as a gem source
-      :code
-        # lang: ruby
-        git 'https://github.com/rails/rails.git' do
-          gem 'railties'
-          gem 'actionpack'
-          gem 'activemodel'
-        end
-    .bullet
-      .description
-        From the previous example, you may specify a particular ref, branch or tag
-      :code
-        # lang: ruby
-        git 'https://github.com/rails/rails.git', ref: '4aded' do
-        git 'https://github.com/rails/rails.git', branch: '5-0-stable' do
-        git 'https://github.com/rails/rails.git', tag: 'v5.0.0' do
-    .bullet
-      .description
-        Specifying a ref, branch, or tag for a
-        git repository specified inline works
-        exactly the same way
-      :code
-        # lang: ruby
-        gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', ref: '0bd839d'
-        gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', tag: '2.0.1'
-        gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', branch: 'rack-1.5'
-    .bullet
-      .description
-        Bundler can use HTTP(S), SSH, or git
-      :code
-        # lang: ruby
-        gem 'rack', git: 'https://github.com/rack/rack.git'
-        gem 'rack', git: 'git@github.com:rack/rack.git'
-        gem 'rack', git: 'git://github.com/rack/rack.git'
-    .bullet
-      .description
-        Specify that the submodules from a git repository
-        also should be expanded by bundler
-      :code
-        # lang: ruby
-        gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true
-    .bullet
-      .description
-        If you are getting your gems from a public GitHub repository,
-        you can use the shorthand
-      :code
-        # lang: ruby
-        gem 'rack', github: 'rack/rack'
-      .description
-        If the repository name is the same as the GitHub account hosting it,
-        you can omit it
-      :code
-        # lang: ruby
-        gem 'rails', github: 'rails'
-      .description
-        <b>NB:</b> This shorthand can only be used for public repos in Bundler version 1.x. Use HTTPS for read and write:
-      :code
-        # lang: ruby
-        gem 'rails', git: 'https://github.com/rails/rails'
-      .description
-        All of the usual <code>:git</code> options apply, like <code>:branch</code> and <code>:ref</code>.
-      :code
-        # lang: ruby
-        gem 'rails', github: 'rails', ref: 'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56'
-      .description
-        There are analogous shortcuts for Bitbucket (<code>:bitbucket</code>) and GitHub Gists (<code>:gist</code>).
-      :code
-        # lang: ruby
-        gem 'keystone', bitbucket: 'musicone/keystone'
-        gem 'my_gist', gist: '4815162342'
-  %h2 Custom git sources
-  .contents
-    .bullet
-      .description
-        The <code>:github</code> shortcut used above is one of Bundler's built in git sources. Bundler comes
-        with shortcuts for <code>:github</code>, <code>:gist</code>, and <code>:bitbucket</code>, but you can
-        also add your own.
-
-      .description
-        If you're using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts
-        by calling <code>git_source</code> before you use your custom option. Here's an example for Stash:
-
-      :code
-        # lang: ruby
-        git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/\#{repo_name}.git" }
-        gem 'rails', stash: 'forks/rails'
-  %h2 Security
-  .contents
-    .bullet
-      .description
-        <code>http://</code> and <code>git://</code> URLs are insecure. A
-        man-in-the-middle attacker could tamper with the code as you check it out,
-        and potentially supply you with malicious code instead of the code you meant to
-        check out. Because the <code>:github</code> shortcut uses a <code>git://</code>
-        URL in Bundler 1.x versions, we recommend using HTTPS URLs or overriding
-        the <code>:github</code> shortcut with your own HTTPS git source.
-
-  %h2#local Local Git Repos
-  .contents
-    .bullet
-      .description
-        Bundler also allows you to work against a git repository locally
-        instead of using the remote version. This can be achieved by setting
-        up a local override:
-      :code
-        $ bundle config set local.GEM_NAME /path/to/local/git/repository
-    .bullet
-      .description
-        For example, in order to use a local Rack repository, a developer could call:
-      :code
-        $ bundle config set local.rack ~/Work/git/rack
-      .description
-        and setup the git repo pointing to a branch:
-      :code
-        # lang: ruby
-        gem 'rack', github: 'rack/rack', branch: 'master'
-    .bullet
-      .description
-        %p
-          Now instead of checking out the remote git repository, the local
-          override will be used. Similar to a path source, every time the local
-          git repository change, changes will be automatically picked up by
-          Bundler. This means a commit in the local git repo will update the
-          revision in the <code>Gemfile.lock</code> to the local git repo revision. This
-          requires the same attention as git submodules. Before pushing to
-          the remote, you need to ensure the local override was pushed, otherwise
-          you may point to a commit that only exists in your local machine.
-
-        %p
-          <strong>Please note!</strong>
-          Bundler does many checks to ensure a developer won't work with
-          invalid references. Particularly, <strong>we force a developer to specify
-          a branch in the <code>Gemfile</code> in order to use this feature</strong>. If the branch
-          specified in the <code>Gemfile</code> and the current branch in the local git
-          repository do not match, Bundler will abort. This ensures that
-          a developer is always working against the correct branches, and prevents
-          accidental locking to a different branch.
-
-        %p
-          Finally, Bundler also ensures that the current revision in the
-          <code>Gemfile.lock</code> exists in the local git repository. By doing this, Bundler
-          forces you to fetch the latest changes in the remotes.
-
-    .bullet
-      .description
-        %p If you do not want bundler to make these branch checks, you can override it by setting this option:
-      :code
-        $ bundle config set disable_local_branch_check true
diff --git a/source/guides/git.html.md b/source/guides/git.html.md
new file mode 100644
index 0000000000..50eeecf40b
--- /dev/null
+++ b/source/guides/git.html.md
@@ -0,0 +1,191 @@
+---
+title: How to install gems from git repositories
+---
+## How to install gems from git repositories
+
+This document is written for Bundler 2.1 or higher.
+Use `bundle config X Y` instead of `bundle config set X Y`
+if you are still using Bundler 2.0 or earlier, which were already deprecated.
+
+Bundler has the ability to install gems directly from git repositories. Installing
+a gem using git is as easy as adding a gem to your Gemfile.
+
+Note that because RubyGems lacks the ability to handle gems from git, any gems
+installed from a git repository will not show up in `gem list`.
+They will, however, be available after running `Bundler.setup`.
+
+Specify that a gem should come from a git
+repository with a .gemspec at its root
+
+~~~ruby
+gem 'rack', git: 'https://github.com/rack/rack'
+~~~
+
+If there is no .gemspec at the root of
+a git repository, you must specify a version
+that bundler should use when resolving
+dependencies
+
+~~~ruby
+gem 'nokogiri', '1.7.0.1', git: 'https://github.com/sparklemotion/nokogiri'
+~~~
+
+If the gem is located within a subdirectory of
+a git repository, you can use the `:glob` option
+to specify the location of its .gemspec
+
+~~~ruby
+gem 'cf-copilot', git: 'https://github.com/cloudfoundry/copilot', glob: 'sdk/ruby/*.gemspec'
+~~~
+
+Specify that a git repository containing
+multiple .gemspec files should be treated
+as a gem source
+
+~~~ruby
+git 'https://github.com/rails/rails.git' do
+  gem 'railties'
+  gem 'actionpack'
+  gem 'activemodel'
+end
+~~~
+
+From the previous example, you may specify a particular ref, branch or tag
+
+~~~ruby
+git 'https://github.com/rails/rails.git', ref: '4aded' do
+git 'https://github.com/rails/rails.git', branch: '5-0-stable' do
+git 'https://github.com/rails/rails.git', tag: 'v5.0.0' do
+~~~
+
+Specifying a ref, branch, or tag for a
+git repository specified inline works
+exactly the same way
+
+~~~ruby
+gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', ref: '0bd839d'
+gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', tag: '2.0.1'
+gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', branch: 'rack-1.5'
+~~~
+
+Bundler can use HTTP(S), SSH, or git
+
+~~~ruby
+gem 'rack', git: 'https://github.com/rack/rack.git'
+gem 'rack', git: 'git@github.com:rack/rack.git'
+gem 'rack', git: 'git://github.com/rack/rack.git'
+~~~
+
+Specify that the submodules from a git repository
+also should be expanded by bundler
+
+~~~ruby
+gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true
+~~~
+
+If you are getting your gems from a public GitHub repository,
+you can use the shorthand
+
+~~~ruby
+gem 'rack', github: 'rack/rack'
+~~~
+
+If the repository name is the same as the GitHub account hosting it,
+you can omit it
+
+~~~ruby
+gem 'rails', github: 'rails'
+~~~
+
+*NB:* This shorthand can only be used for public repos in Bundler version 1.x. Use HTTPS for read and write:
+
+~~~ruby
+gem 'rails', git: 'https://github.com/rails/rails'
+~~~
+
+All of the usual `:git` options apply, like `:branch` and `:ref`.
+
+~~~ruby
+gem 'rails', github: 'rails', ref: 'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56'
+~~~
+
+There are analogous shortcuts for Bitbucket (`:bitbucket`) and GitHub Gists (`:gist`).
+
+~~~ruby
+gem 'keystone', bitbucket: 'musicone/keystone'
+gem 'my_gist', gist: '4815162342'
+~~~
+
+## Custom git sources
+
+The `:github` shortcut used above is one of Bundler's built in git sources. Bundler comes
+with shortcuts for `:github`, `:gist`, and `:bitbucket`, but you can
+also add your own.
+
+If you're using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts
+by calling `git_source` before you use your custom option. Here's an example for Stash:
+
+~~~ruby
+git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
+gem 'rails', stash: 'forks/rails'
+~~~
+
+## Security
+
+`http://` and `git://` URLs are insecure. A
+man-in-the-middle attacker could tamper with the code as you check it out,
+and potentially supply you with malicious code instead of the code you meant to
+check out. Because the `:github` shortcut uses a `git://`
+URL in Bundler 1.x versions, we recommend using HTTPS URLs or overriding
+the `:github` shortcut with your own HTTPS git source.
+
+## Local Git Repos
+<a name="local"></a>
+
+Bundler also allows you to work against a git repository locally
+instead of using the remote version. This can be achieved by setting
+up a local override:
+
+~~~
+$ bundle config set local.GEM_NAME /path/to/local/git/repository
+~~~
+
+For example, in order to use a local Rack repository, a developer could call:
+
+~~~
+$ bundle config set local.rack ~/Work/git/rack
+~~~
+
+and setup the git repo pointing to a branch:
+
+~~~ruby
+gem 'rack', github: 'rack/rack', branch: 'master'
+~~~
+
+Now instead of checking out the remote git repository, the local
+override will be used. Similar to a path source, every time the local
+git repository change, changes will be automatically picked up by
+Bundler. This means a commit in the local git repo will update the
+revision in the `Gemfile.lock` to the local git repo revision. This
+requires the same attention as git submodules. Before pushing to
+the remote, you need to ensure the local override was pushed, otherwise
+you may point to a commit that only exists in your local machine.
+
+**Please note!**
+Bundler does many checks to ensure a developer won't work with
+invalid references. Particularly, **we force a developer to specify
+a branch in the `Gemfile` in order to use this feature**. If the branch
+specified in the `Gemfile` and the current branch in the local git
+repository do not match, Bundler will abort. This ensures that
+a developer is always working against the correct branches, and prevents
+accidental locking to a different branch.
+
+Finally, Bundler also ensures that the current revision in the
+`Gemfile.lock` exists in the local git repository. By doing this, Bundler
+forces you to fetch the latest changes in the remotes.
+
+If you do not want bundler to make these branch checks, you can override it by setting this option:
+
+~~~
+$ bundle config set disable_local_branch_check true
+~~~