diff --git a/Rakefile b/Rakefile
index 2bbf4969a..e8fa627b5 100644
--- a/Rakefile
+++ b/Rakefile
@@ -6,6 +6,7 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rubocop/rake_task'
 require_relative 'tasks/maintainers'
+require_relative 'tasks/docs'
 
 # Rubocop
 desc 'Run Rubocop lint checks'
@@ -165,56 +166,3 @@ task :release_docker do
   puts "--> #{cmd}"
   sh('sh', '-c', cmd)
 end
-
-namespace :docs do
-  desc 'Create cli docs'
-  task :cli do
-    res = "=====================================================\n"\
-          "InSpec CLI\n"\
-          "=====================================================\n\n"\
-          "Use the InSpec CLI to run tests and audits against targets "\
-          "using local, SSH, WinRM, or Docker connections.\n\n"
-
-    require 'inspec/cli'
-    cmds = Inspec::InspecCLI.all_commands
-    cmds.keys.sort.each do |key|
-      cmd = cmds[key]
-
-      res << "#{cmd.usage.split.first}\n"\
-             "=====================================================\n\n"
-
-      res << cmd.description.capitalize
-      res << "\n\n"
-
-      res << "Syntax\n"\
-             "-----------------------------------------------------\n\n"
-
-      res << "This subcommand has the following syntax:\n\n"\
-             ".. code-block:: bash\n\n"\
-             "   $ inspec #{cmd.usage}\n\n"
-
-      opts = cmd.options.select { |_, o| !o.hide }
-      unless opts.empty?
-        res << "Options\n"\
-               "-----------------------------------------------------\n\n"\
-               "This subcommand has additional options:\n\n"
-
-        opts.keys.sort.each do |option|
-          opt = cmd.options[option]
-          # TODO: remove when UX of help is reworked 1.0
-          usage = opt.usage.split(', ')
-                     .map { |x| x.tr('[]', '') }
-                     .map { |x| x.start_with?('-') ? x : '-'+x }
-                     .map { |x| '``' + x + '``' }
-          res << "#{usage.join(', ')}\n   #{opt.description}\n\n"
-        end
-
-      end
-      res << "\n\n"
-    end
-
-    dst = 'docs/cli.rst'
-    File.write(dst, res)
-    puts "Documentation generated in #{dst.inspect}"
-  end
-end
diff --git a/tasks/docs.rb b/tasks/docs.rb
new file mode 100644
index 000000000..35ed9cbfe
--- /dev/null
+++ b/tasks/docs.rb
@@ -0,0 +1,152 @@
+# encoding: utf-8
+# Copyright:: Copyright (c) 2015 Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+class Markdown
+  class << self
+    def h1(msg)
+      "# #{msg}\n\n"
+    end
+
+    def h2(msg)
+      "## #{msg}\n\n"
+    end
+
+    def h3(msg)
+      "### #{msg}\n\n"
+    end
+
+    def code(msg, syntax = nil)
+      "```#{syntax}\n"\
+      "#{msg}\n"\
+      "```\n\n"
+    end
+
+    def li(msg)
+      "* #{msg.gsub("\n", "\n    ")}\n"
+    end
+
+    def ul(msg)
+      msg + "\n"
+    end
+
+    def p(msg)
+      "#{msg}\n\n"
+    end
+
+    def suffix
+      '.md'
+    end
+
+    def meta(opts)
+      o = opts.map { |k, v| "#{k}: #{v}" }.join("\n")
+      "---\n#{o}\n---\n\n"
+    end
+  end
+end
+
+class RST
+  class << self
+    def h1(msg)
+      "=====================================================\n"\
+      "#{msg}\n"\
+      "=====================================================\n\n"\
+    end
+
+    def h2(msg)
+      "#{msg}\n"\
+      "=====================================================\n\n"\
+    end
+
+    def h3(msg)
+      "#{msg}\n"\
+      "-----------------------------------------------------\n\n"\
+    end
+
+    def code(msg, syntax = nil)
+      ".. code-block:: #{syntax}\n\n"\
+      "   #{msg.gsub("\n", "\n   ")}\n\n"
+    end
+
+    def li(msg)
+      "#{msg.gsub("\n", "\n   ")}\n\n"
+    end
+
+    def ul(msg)
+      msg
+    end
+
+    def p(msg)
+      "#{msg}\n\n"
+    end
+
+    def suffix
+      '.rst'
+    end
+
+    def meta(_o)
+      '' # ignore for now
+    end
+  end
+end
+
+namespace :docs do
+  desc 'Create cli docs'
+  task :cli do
+    f = RST
+    res = f.meta(title: 'About the InSpec CLI')
+    res << f.h1('InSpec CLI')
+    res << f.p('Use the InSpec CLI to run tests and audits against targets '\
+               'using local, SSH, WinRM, or Docker connections.')
+
+    require 'inspec/cli'
+    cmds = Inspec::InspecCLI.all_commands
+    cmds.keys.sort.each do |key|
+      cmd = cmds[key]
+
+      res << f.h2(cmd.usage.split.first)
+      res << f.p(cmd.description.capitalize)
+
+      res << f.h3('Syntax')
+      res << f.p('This subcommand has the following syntax:')
+      res << f.code("$ inspec #{cmd.usage}", 'bash')
+
+      opts = cmd.options.select { |_, o| !o.hide }
+      unless opts.empty?
+        res << f.h3('Options') + f.p('This subcommand has additional options:')
+
+        list = ''
+        opts.keys.sort.each do |option|
+          opt = cmd.options[option]
+          # TODO: remove when UX of help is reworked 1.0
+          usage = opt.usage.split(', ')
+                     .map { |x| x.tr('[]', '') }
+                     .map { |x| x.start_with?('-') ? x : '-'+x }
+                     .map { |x| '``' + x + '``' }
+          list << f.li("#{usage.join(', ')}\n#{opt.description}")
+        end.join
+        res << f.ul(list)
+      end
+
+      # FIXME: for some reason we have extra lines in our RST; needs investigation
+      res << "\n\n" if f == RST
+    end
+
+    dst = 'docs/cli' + f.suffix
+    File.write(dst, res)
+    puts "Documentation generated in #{dst.inspect}"
+  end
+end