diff --git a/lib/puppet-strings/yard/templates/default/layout/html/setup.rb b/lib/puppet-strings/yard/templates/default/layout/html/setup.rb
index d228a36..7b237a8 100644
--- a/lib/puppet-strings/yard/templates/default/layout/html/setup.rb
+++ b/lib/puppet-strings/yard/templates/default/layout/html/setup.rb
@@ -54,7 +54,13 @@ def layout
     @path = object.path
   end
 
-  erb(:layout)
+  final_layout = erb(:layout)
+
+  if @file && @file.name == 'README'
+    PuppetStrings::Yard::Util.github_to_yard_links(final_layout)
+  end
+
+  final_layout
 end
 
 # Creates the dynamic menu lists.
diff --git a/lib/puppet-strings/yard/util.rb b/lib/puppet-strings/yard/util.rb
index 809bd55..29a701c 100644
--- a/lib/puppet-strings/yard/util.rb
+++ b/lib/puppet-strings/yard/util.rb
@@ -14,4 +14,18 @@ module PuppetStrings::Yard::Util
 
     Puppet::Util::Docs.scrub(str)
   end
+
+  # hacksville, usa
+  # YARD creates ids in the html with with the style of "label-Module+description", where the markdown
+  # we use in the README involves the GitHub-style, which is #module-description. This takes our GitHub-style
+  # links and converts them to reference the YARD-style ids.
+  # @see https://github.com/octokit/octokit.rb/blob/0f13944e8dbb0210d1e266addd3335c6dc9fe36a/yard/default/layout/html/setup.rb#L5-L14
+  # @param [String] data HTML document to convert
+  # @return [String] HTML document with links converted
+  def self.github_to_yard_links(data)
+    data.scan(/href\=\"\#(.+)\"/).each do |bad_link|
+      data.gsub!(bad_link.first, "label-#{bad_link.first.capitalize.gsub('-', '+')}")
+    end
+    data
+  end
 end
diff --git a/spec/unit/puppet-strings/yard/util_spec.rb b/spec/unit/puppet-strings/yard/util_spec.rb
index 65da303..3814c2e 100644
--- a/spec/unit/puppet-strings/yard/util_spec.rb
+++ b/spec/unit/puppet-strings/yard/util_spec.rb
@@ -28,4 +28,16 @@ STR
       expect(subject.scrub_string(str)).to eq('this is a test string')
     end
   end
+
+  describe 'github_to_yard_links' do
+    it 'converts a link correctly' do
+      str = '<a href="#module-description">'
+      expect(subject.github_to_yard_links(str)).to eq('<a href="#label-Module+description">')
+    end
+
+    it 'leaves other links with hashes alone' do
+      str = '<a href="www.github.com/blah/document.html#module-description">'
+      expect(subject.github_to_yard_links(str)).to eq(str)
+    end
+  end
 end