Generate the release notes' toc

.travis/render_release_notes.rb

@@ -13,6 +13,7 @@ require "safe_yaml"
 
 # include some custom liquid extensions
 require_relative "../docs/_plugins/rule_tag"
+require_relative "../docs/_plugins/tocmaker_block"
 require_relative "../docs/_plugins/custom_filters"
 
 # explicitly setting safe mode to get rid of the warning

docs/_plugins/tocmaker_block.rb

@@ -0,0 +1,51 @@
+# Generates a table of contents based on markdown headers in the body
+#
+# The block's arg may be an int describing the maximum depth at which
+# headers are added to the toc
+
+class TocMakerBlock < Liquid::Block
+  # include Enumerable
+
+  def initialize(tag_name, arg, tokens)
+    super
+    @max_depth = arg.to_s.empty? ? 100 : arg.to_i
+    @body = tokens
+  end
+
+  def to_internal_link(header)
+    url = header.downcase.gsub(/\s+/, "-")
+
+    "[#{header}](##{url})"
+  end
+
+  def render(context)
+
+    contents = @body.render(context)
+
+
+    headers = contents.lines.map {|l|
+      if /^(#+)\s+(\S.*)$/ =~ l
+        [$1.length, $2]
+      end
+    }.compact
+
+    min_indent = headers.min_by {|t| t[0]}[0]
+
+    headers = headers.map {|t|
+      actual_depth = t[0] - min_indent
+      if actual_depth < @max_depth then
+
+        indent = "    " * actual_depth
+
+        "#{indent}* #{to_internal_link(t[1])}"
+      end
+    }.compact
+
+    headers.unshift("### Table Of Contents\n")
+
+    headers.join("\n") + contents
+  end
+end
+
+
+Liquid::Template.register_tag('tocmaker', TocMakerBlock)

docs/pages/release_notes.md

@@ -10,13 +10,7 @@ The PMD team is pleased to announce PMD {{ site.pmd.version }}.
 
 This is a {{ site.pmd.release_type }} release.
 
-### Table Of Contents
+{% tocmaker %}
-
-* [New and noteworthy](#new-and-noteworthy)
-    *   [New Rules](#new-rules)
-* [Fixed Issues](#fixed-issues)
-* [API Changes](#api-changes)
-* [External Contributions](#external-contributions)
 
 ### New and noteworthy
 
@@ -77,3 +71,5 @@ This is a {{ site.pmd.release_type }} release.
 *   [#1289](https://github.com/pmd/pmd/pull/1289): \[java] UselessParentheses: Fix false positive with assignments - [cobratbq](https://github.com/cobratbq)
 *   [#1290](https://github.com/pmd/pmd/pull/1290): \[docs] \[GSoC] Create the documentation about pmdtester - [BBG](https://github.com/djydewang)
 *   [#1256](https://github.com/pmd/pmd/pull/1256): \[java] #940 Avoid JUnit 4 false positives for JUnit 5 tests - [Alex Shesterov](https://github.com/vovkss)
+
+{% endtocmaker %}