diff --git a/lib/puppet/parser/functions/versioncmp.rb b/lib/puppet/parser/functions/versioncmp.rb
index 94ba3886f..3dbfb5dc4 100644
--- a/lib/puppet/parser/functions/versioncmp.rb
+++ b/lib/puppet/parser/functions/versioncmp.rb
@@ -1,34 +1,34 @@
 require 'puppet/util/package'
 
 
       Puppet::Parser::Functions::newfunction(
         :versioncmp, :type => :rvalue,
 
   :doc => "Compares two versions
 
 Prototype:
 
     \$result = versioncmp(a, b)
 
 Where a and b are arbitrary version strings
 
 This functions returns a number:
 
-* > 0 if version a is greater than version b
-* == 0 if both version are equals
-* < 0 if version a is less than version b
+* Greate than 0 if version a is greater than version b
+* Equal to 0 if both version are equals
+* Less than 0 if version a is less than version b
 
 Example:
 
     if versioncmp('2.6-1', '2.4.5') > 0 {
         notice('2.6-1 is > than 2.4.5')
     }
 
 ") do |args|
 
   unless args.length == 2
     raise Puppet::ParseError, "versioncmp should have 2 arguments"
   end
 
   return Puppet::Util::Package.versioncmp(args[0], args[1])
 end
diff --git a/lib/puppet/reference/configuration.rb b/lib/puppet/reference/configuration.rb
index fadd1a423..e6a8dc20f 100644
--- a/lib/puppet/reference/configuration.rb
+++ b/lib/puppet/reference/configuration.rb
@@ -1,149 +1,144 @@
 config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc => "A reference for all configuration parameters") do
   docs = {}
   Puppet.settings.each do |name, object|
     docs[name] = object
   end
 
   str = ""
   docs.sort { |a, b|
     a[0].to_s <=> b[0].to_s
   }.each do |name, object|
     # Make each name an anchor
     header = name.to_s
     str += h(header, 3)
 
     # Print the doc string itself
     begin
       str += object.desc.gsub(/\n/, " ")
     rescue => detail
       puts detail.backtrace
       puts detail
     end
     str += "\n\n"
 
     # Now print the data about the item.
     str += ""
     val = object.default
     if name.to_s == "vardir"
       val = "/var/lib/puppet"
     elsif name.to_s == "confdir"
       val = "/etc/puppet"
     end
 
     # Leave out the section information; it was apparently confusing people.
     #str += "- **Section**: #{object.section}\n"
     unless val == ""
       str += "- *Default*: #{val}\n"
     end
     str += "\n"
   end
 
   return str
 end
 
 config.header = "
-Specifying Configuration Parameters
------------------------------------
+## Specifying Configuration Parameters
+
+### On The Command-Line
 
-On The Command-Line
-+++++++++++++++++++
 Every Puppet executable (with the exception of `puppetdoc`) accepts all of
 the parameters below, but not all of the arguments make sense for every executable.
 
 I have tried to be as thorough as possible in the descriptions of the
 arguments, so it should be obvious whether an argument is appropriate or not.
 
 These parameters can be supplied to the executables either as command-line
 options or in the configuration file.  For instance, the command-line
 invocation below would set the configuration directory to `/private/puppet`:
 
     $ puppet agent --confdir=/private/puppet
 
 Note that boolean options are turned on and off with a slightly different
 syntax on the command line:
 
     $ puppet agent --storeconfigs
 
     $ puppet agent --no-storeconfigs
 
 The invocations above will enable and disable, respectively, the storage of
 the client configuration.
 
-Configuration Files
-+++++++++++++++++++
+### Configuration Files
 
 As mentioned above, the configuration parameters can also be stored in a
 configuration file, located in the configuration directory.  As root, the
 default configuration directory is `/etc/puppet`, and as a regular user, the
 default configuration directory is `~user/.puppet`.  As of 0.23.0, all
 executables look for `puppet.conf` in their configuration directory
 (although they previously looked for separate files).  For example,
 `puppet.conf` is located at `/etc/puppet/puppet.conf` as `root` and
 `~user/.puppet/puppet.conf` as a regular user by default.
 
 All executables will set any parameters set within the `[main]` section,
 and each executable will also use one of the `[master]`, `[agent]`.
 
-File Format
-'''''''''''
+#### File Format
 
 The file follows INI-style formatting.  Here is an example of a very simple
 `puppet.conf` file:
 
     [main]
       confdir = /private/puppet
       storeconfigs = true
 
 Note that boolean parameters must be explicitly specified as `true` or
 `false` as seen above.
 
 If you need to change file parameters (e.g., reset the mode or owner), do
 so within curly braces on the same line:
 
     [main]
       myfile = /tmp/whatever {owner = root, mode = 644}
 
 If you're starting out with a fresh configuration, you may wish to let
 the executable generate a template configuration file for you by invoking
 the executable in question with the `--genconfig` command.  The executable
 will print a template configuration to standard output, which can be
 redirected to a file like so:
 
     $ puppet agent --genconfig > /etc/puppet/puppet.conf
 
 Note that this invocation will replace the contents of any pre-existing
 `puppet.conf` file, so make a backup of your present config if it contains
 valuable information.
 
 Like the `--genconfig` argument, the executables also accept a `--genmanifest`
 argument, which will generate a manifest that can be used to manage all of
 Puppet's directories and files and prints it to standard output.  This can
 likewise be redirected to a file:
 
     $ puppet agent --genmanifest > /etc/puppet/manifests/site.pp
 
 Puppet can also create user and group accounts for itself (one `puppet` group
 and one `puppet` user) if it is invoked as `root` with the `--mkusers` argument:
 
     $ puppet agent --mkusers
 
-Signals
--------
+## Signals
 
 The `puppet agent` and `puppet master` executables catch some signals for special
 handling.  Both daemons catch (`SIGHUP`), which forces the server to restart
 tself.  Predictably, interrupt and terminate (`SIGINT` and `SIGTERM`) will shut
 down the server, whether it be an instance of `puppet agent` or `puppet master`.
 
 Sending the `SIGUSR1` signal to an instance of `puppet agent` will cause it to
 immediately begin a new configuration transaction with the server.  This
 signal has no effect on `puppet master`.
 
-Configuration Parameter Reference
----------------------------------
+## Configuration Parameter Reference
 
 Below is a list of all documented parameters.  Not all of them are valid with all
 Puppet executables, but the executables will ignore any inappropriate values.
 
 "
 
diff --git a/lib/puppet/reference/indirection.rb b/lib/puppet/reference/indirection.rb
index 0cdbb2510..e5b076508 100644
--- a/lib/puppet/reference/indirection.rb
+++ b/lib/puppet/reference/indirection.rb
@@ -1,33 +1,33 @@
 require 'puppet/indirector/indirection'
 require 'puppet/util/checksums'
 require 'puppet/file_serving/content'
 require 'puppet/file_serving/metadata'
 
 reference = Puppet::Util::Reference.newreference :indirection, :doc => "Indirection types and their terminus classes" do
   text = ""
   Puppet::Indirector::Indirection.instances.sort { |a,b| a.to_s <=> b.to_s }.each do |indirection|
     ind = Puppet::Indirector::Indirection.instance(indirection)
     name = indirection.to_s.capitalize
-    text += indirection.to_s + "\n" + ("-" * name.length) + "\n\n"
+    text += "## " + indirection.to_s + "\n\n"
 
     text += ind.doc + "\n\n"
 
     Puppet::Indirector::Terminus.terminus_classes(ind.name).sort { |a,b| a.to_s <=> b.to_s }.each do |terminus|
-      text += terminus.to_s + "\n" + ("+" * terminus.to_s.length) + "\n\n"
+      text += "### " + terminus.to_s + "\n\n"
 
       term_class = Puppet::Indirector::Terminus.terminus_class(ind.name, terminus)
 
       text += Puppet::Util::Docs.scrub(term_class.doc) + "\n\n"
     end
   end
 
   text
 end
 
 reference.header = "This is the list of all indirections, their associated terminus classes, and how you select between them.
 
 In general, the appropriate terminus class is selected by the application for you (e.g., `puppet agent` would always use the `rest`
 terminus for most of its indirected classes), but some classes are tunable via normal settings.  These will have `terminus setting` documentation listed with them.
 
 
 "
diff --git a/lib/puppet/reference/metaparameter.rb b/lib/puppet/reference/metaparameter.rb
index 39c4b7f5f..c16a1d33a 100644
--- a/lib/puppet/reference/metaparameter.rb
+++ b/lib/puppet/reference/metaparameter.rb
@@ -1,40 +1,41 @@
 metaparameter = Puppet::Util::Reference.newreference :metaparameter, :doc => "All Puppet metaparameters and all their details" do
   types = {}
   Puppet::Type.loadall
 
   Puppet::Type.eachtype { |type|
     next if type.name == :puppet
     next if type.name == :component
     types[type.name] = type
   }
 
   str = %{
-    Metaparameters
-    --------------
-    Metaparameters are parameters that work with any resource type; they are part of the
-    Puppet framework itself rather than being part of the implementation of any
-    given instance.  Thus, any defined metaparameter can be used with any instance
-    in your manifest, including defined components.
 
-    Available Metaparameters
-    ++++++++++++++++++++++++
-    }
+# Metaparameters
+    
+Metaparameters are parameters that work with any resource type; they are part of the 
+Puppet framework itself rather than being part of the implementation of any
+given instance.  Thus, any defined metaparameter can be used with any instance
+in your manifest, including defined components.
+
+## Available Metaparameters
+
+}
   begin
     params = []
     Puppet::Type.eachmetaparam { |param|
       params << param
     }
 
     params.sort { |a,b|
       a.to_s <=> b.to_s
     }.each { |param|
       str += paramwrap(param.to_s, scrub(Puppet::Type.metaparamdoc(param)), :level => 4)
     }
   rescue => detail
     puts detail.backtrace
     puts "incorrect metaparams: #{detail}"
     exit(1)
   end
 
   str
 end
diff --git a/lib/puppet/reference/type.rb b/lib/puppet/reference/type.rb
index 2378bb83a..847bbc223 100644
--- a/lib/puppet/reference/type.rb
+++ b/lib/puppet/reference/type.rb
@@ -1,113 +1,112 @@
 type = Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource types and all their details" do
   types = {}
   Puppet::Type.loadall
 
   Puppet::Type.eachtype { |type|
     next if type.name == :puppet
     next if type.name == :component
     types[type.name] = type
   }
 
   str = %{
 
-    Resource Types
-    --------------
+## Resource Types
 
-    - The *namevar* is the parameter used to uniquely identify a type instance.
+- The *namevar* is the parameter used to uniquely identify a type instance.
   This is the parameter that gets assigned when a string is provided before
   the colon in a type declaration.  In general, only developers will need to
   worry about which parameter is the `namevar`.
 
   In the following code:
 
       file { "/etc/passwd":
         owner => root,
         group => root,
         mode => 644
       }
 
   `/etc/passwd` is considered the title of the file object (used for things like
   dependency handling), and because `path` is the namevar for `file`, that
   string is assigned to the `path` parameter.
 
-  - *Parameters* determine the specific configuration of the instance.  They either
+- *Parameters* determine the specific configuration of the instance.  They either
   directly modify the system (internally, these are called properties) or they affect
   how the instance behaves (e.g., adding a search path for `exec` instances or determining recursion on `file` instances).
 
-  - *Providers* provide low-level functionality for a given resource type.  This is
+- *Providers* provide low-level functionality for a given resource type.  This is
   usually in the form of calling out to external commands.
 
   When required binaries are specified for providers, fully qualifed paths
   indicate that the binary must exist at that specific path and unqualified
   binaries indicate that Puppet will search for the binary using the shell
   path.
 
-  - *Features* are abilities that some providers might not support.  You can use the list
+- *Features* are abilities that some providers might not support.  You can use the list
   of supported features to determine how a given provider can be used.
 
   Resource types define features they can use, and providers can be tested to see
   which features they provide.
 
     }
 
     types.sort { |a,b|
       a.to_s <=> b.to_s
     }.each { |name,type|
 
       str += "
 
 ----------------
 
 "
 
   str += h(name, 3)
   str += scrub(type.doc) + "\n\n"
 
   # Handle the feature docs.
   if featuredocs = type.featuredocs
     str += h("Features", 4)
     str += featuredocs
     end
 
     docs = {}
     type.validproperties.sort { |a,b|
       a.to_s <=> b.to_s
     }.reject { |sname|
       property = type.propertybyname(sname)
       property.nodoc
     }.each { |sname|
       property = type.propertybyname(sname)
 
       raise "Could not retrieve property #{sname} on type #{type.name}" unless property
 
       doc = nil
       unless doc = property.doc
         $stderr.puts "No docs for #{type}[#{sname}]"
         next
       end
       doc = doc.dup
       tmp = doc
       tmp = scrub(tmp)
 
       docs[sname]  = tmp
     }
 
     str += h("Parameters", 4) + "\n"
     type.parameters.sort { |a,b|
       a.to_s <=> b.to_s
     }.each { |name,param|
       #docs[name] = indent(scrub(type.paramdoc(name)), $tab)
       docs[name] = scrub(type.paramdoc(name))
     }
 
     additional_key_attributes = type.key_attributes - [:name]
     docs.sort { |a, b|
       a[0].to_s <=> b[0].to_s
     }.each { |name, doc|
       str += paramwrap(name, doc, :namevar => additional_key_attributes.include?(name))
     }
     str += "\n"
   }
 
   str
 end
diff --git a/lib/puppet/util/reference.rb b/lib/puppet/util/reference.rb
index 4f2058e69..5fedb5f48 100644
--- a/lib/puppet/util/reference.rb
+++ b/lib/puppet/util/reference.rb
@@ -1,158 +1,158 @@
 require 'puppet/util/instance_loader'
 require 'fileutils'
 
 # Manage Reference Documentation.
 class Puppet::Util::Reference
   include Puppet::Util
   include Puppet::Util::Docs
 
   extend Puppet::Util::InstanceLoader
 
   instance_load(:reference, 'puppet/reference')
 
   def self.footer
     "\n\n----------------\n\n*This page autogenerated on #{Time.now}*\n"
   end
 
   def self.modes
     %w{pdf text}
   end
 
   def self.newreference(name, options = {}, &block)
     ref = self.new(name, options, &block)
     instance_hash(:reference)[symbolize(name)] = ref
 
     ref
   end
 
   def self.page(*sections)
     depth = 4
     # Use the minimum depth
     sections.each do |name|
       section = reference(name) or raise "Could not find section #{name}"
       depth = section.depth if section.depth < depth
     end
     text = "{:toc}\n\n"
   end
 
   def self.pdf(text)
     puts "creating pdf"
     Puppet::Util.secure_open("/tmp/puppetdoc.txt", "w") do |f|
       f.puts text
     end
     rst2latex = %x{which rst2latex}
     if $CHILD_STATUS != 0 or rst2latex =~ /no /
       rst2latex = %x{which rst2latex.py}
     end
     if $CHILD_STATUS != 0 or rst2latex =~ /no /
       raise "Could not find rst2latex"
     end
     rst2latex.chomp!
     cmd = %{#{rst2latex} /tmp/puppetdoc.txt > /tmp/puppetdoc.tex}
     Puppet::Util.secure_open("/tmp/puppetdoc.tex","w") do |f|
       # If we get here without an error, /tmp/puppetdoc.tex isn't a tricky cracker's symlink
     end
     output = %x{#{cmd}}
     unless $CHILD_STATUS == 0
       $stderr.puts "rst2latex failed"
       $stderr.puts output
       exit(1)
     end
     $stderr.puts output
 
     # Now convert to pdf
     Dir.chdir("/tmp") do
       %x{texi2pdf puppetdoc.tex >/dev/null 2>/dev/null}
     end
 
   end
 
   def self.references
     instance_loader(:reference).loadall
     loaded_instances(:reference).sort { |a,b| a.to_s <=> b.to_s }
   end
 
-  HEADER_LEVELS = [nil, "=", "-", "+", "'", "~"]
+  HEADER_LEVELS = [nil, "#", "##", "###", "####", "#####"]
 
   attr_accessor :page, :depth, :header, :title, :dynamic
   attr_writer :doc
 
   def doc
     if defined?(@doc)
       return "#{@name} - #{@doc}"
     else
       return @title
     end
   end
 
   def dynamic?
     self.dynamic
   end
 
   def h(name, level)
-    "#{name}\n#{HEADER_LEVELS[level] * name.to_s.length}\n\n"
+    "#{HEADER_LEVELS[level]} #{name}\n\n"
   end
 
   def initialize(name, options = {}, &block)
     @name = name
     options.each do |option, value|
       send(option.to_s + "=", value)
     end
 
     meta_def(:generate, &block)
 
     # Now handle the defaults
     @title ||= "#{@name.to_s.capitalize} Reference"
     @page ||= @title.gsub(/\s+/, '')
     @depth ||= 2
     @header ||= ""
   end
 
   # Indent every line in the chunk except those which begin with '..'.
   def indent(text, tab)
     text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..")
   end
 
   def option(name, value)
     ":#{name.to_s.capitalize}: #{value}\n"
   end
 
   def paramwrap(name, text, options = {})
     options[:level] ||= 5
     #str = "#{name} : "
     str = h(name, options[:level])
     str += "- **namevar**\n\n" if options[:namevar]
     str += text
     #str += text.gsub(/\n/, "\n    ")
 
     str += "\n\n"
   end
 
   # Remove all trac links.
   def strip_trac(text)
     text.gsub(/`\w+\s+([^`]+)`:trac:/) { |m| $1 }
   end
 
   def text
     puts output
   end
 
   def to_rest(withcontents = true)
     # First the header
     text = h(@title, 1)
     text += "\n\n**This page is autogenerated; any changes will get overwritten** *(last generated on #{Time.now.to_s})*\n\n"
     text +=  "{:toc}\n\n" if withcontents
 
     text += @header
 
     text += generate
 
     text += self.class.footer if withcontents
 
     text
   end
 
   def to_text(withcontents = true)
     strip_trac(to_rest(withcontents))
   end
 end