added in toggle table of contents links

Author: synapticloop

README.md

@@ -13,7 +13,7 @@ buildscript {
 	}
 
 	dependencies {
-		classpath 'synapticloop:documentr:2.2.0'
+		classpath 'synapticloop:documentr:2.3.0'
 	}
 }
 
@@ -36,7 +36,7 @@ group = 'synapticloop'
 archivesBaseName = 'documentr'
 description = """documentation (README) generator for projects in both markdown and asciidoc - this utilises the templar templating language - including generation of table of contents"""
 
-version = '2.2.0'
+version = '2.3.0'
 
 sourceCompatibility = 1.7
 targetCompatibility = 1.7

build-test.gradle

@@ -13,7 +13,7 @@ buildscript {
 	}
 
 	dependencies {
-		classpath 'synapticloop:documentr:2.2.0'
+		classpath 'synapticloop:documentr:2.3.0'
 	}
 }
 
@@ -36,7 +36,7 @@ group = 'synapticloop'
 archivesBaseName = 'documentr'
 description = """documentation (README) generator for projects in both markdown and asciidoc - this utilises the templar templating language - including generation of table of contents"""
 
-version = '2.2.0'
+version = '2.3.0'
 
 sourceCompatibility = 1.7
 targetCompatibility = 1.7

build.gradle

@@ -13,6 +13,9 @@
 		{ "type": "markup", "value": "\n\n# Table of Contents\n\n" },
 
 		{ "type": "toc", "value": "2" },
+		{ "type": "toclinks", "value": "true" },
+
+		{ "type": "file", "value":"src/docs/table-of-contents.md" },
 
 		{ "type":"inbuilt", "value":"project-name" },
 		{ "type":"inbuilt", "value":"project-description" },

documentr.json

@@ -0,0 +1,25 @@
+
+# Generating the table of contents
+
+`documentr` can automatically generate the table fo contents for your documentation, 
+simply by entering the following line into you `documentr.json` file:
+
+```
+{ "type": "markup", "value": "\n\n# Table of Contents\n\n" },
+
+{ "type": "toc", "value": "2" },
+{ "type": "toclinks", "value": "true" },
+```
+By default, no title is generated - you will need to include one as simple markup.
+
+This will generate both the table of contents and the links to all of the headers.
+
+The `{ "type": "toc", "value": "2" }` line will generate links up to `h2` elements, by 
+default this will generate up to header level 6.
+
+The `{ "type": "toclinks", "value": "true" },` line will generate links to he headers,
+and will only work if `"type": "toc"` is also included.
+
+> By default links are not generated.  Unfortunately the developer of the markdown  processor that is in use, does not distinguish block quote level elements correctly  such that anything that looks like a header included in a blockquote will also be  incorrectly identified as a header.  This is why the links are not automatically generated by default.
+
+

src/docs/table-of-contents.md

@@ -0,0 +1,33 @@
+package synapticloop.documentr.bean;
+
+/*
+ * Copyright (c) 2016 Synapticloop.
+ * 
+ * All rights reserved.
+ * 
+ * This code may contain contributions from other parties which, where 
+ * applicable, will be listed in the default build file for the project 
+ * ~and/or~ in a file named CONTRIBUTORS.txt in the root of the project.
+ * 
+ * This source code and any derived binaries are covered by the terms and 
+ * conditions of the Licence agreement ("the Licence").  You may not use this 
+ * source code or any derived binaries except in compliance with the Licence.  
+ * A copy of the Licence is available in the file named LICENSE.txt shipped with 
+ * this source code or binaries.
+ */
+
+public class StartEndBean {
+
+	private int start;
+	private int end;
+
+	public StartEndBean(int start, int end) {
+		this.start = start;
+		this.end = end;
+	}
+
+	public int getStart() { return this.start; }
+
+	public int getEnd() { return this.end; }
+
+}

src/main/java/synapticloop/documentr/bean/StartEndBean.java

@@ -64,7 +64,10 @@ public class Generator {
 	private static final int TYPE_TEMPLAR = 2;
 	private static final int TYPE_TEMPLATE = 3;
 	private static final int TYPE_MARKUP = 4;
-	private static final int TYPE_TOC = 5;
+	private static final int TYPE_MARKDOWN = 5;
+	private static final int TYPE_TOC = 6;
+	private static final int TYPE_TOCBACKTOTOP = 7;
+	private static final int TYPE_TOCLINKS= 8;
 
 	private static final String CONTEXT_CONFIGURATION_BEANS = "configurationBeans";
 	private static final String CONTEXT_CONFIGURATIONS = "configurations";
@@ -78,7 +81,10 @@ public class Generator {
 		TYPE_LOOKUP.put("templar", TYPE_TEMPLAR);
 		TYPE_LOOKUP.put("template", TYPE_TEMPLATE);
 		TYPE_LOOKUP.put("markup", TYPE_MARKUP);
+		TYPE_LOOKUP.put("markdown", TYPE_MARKDOWN);
 		TYPE_LOOKUP.put("toc", TYPE_TOC);
+		TYPE_LOOKUP.put("toclinks", TYPE_TOCLINKS);
+		TYPE_LOOKUP.put("tocbacktop", TYPE_TOCBACKTOTOP);
 
 		SPACING_LOOKUP.put(1, " - ");
 		SPACING_LOOKUP.put(2, "   - ");
@@ -94,8 +100,10 @@ public class Generator {
 	private boolean verbose = false;
 
 	// table of content variables
-	private boolean hasToc = false;
 	private int tocLevel = 6;
+	private boolean hasToc = false;
+	private boolean hasTocBackToTop = false;
+	private boolean hasTocLinks = false;
 
 	private final TemplarContext templarContext = new TemplarContext();
 	private List<ConfigurationBean> configurationBeans = new ArrayList<ConfigurationBean>();
@@ -177,7 +185,7 @@ public void generate() throws DocumentrException {
 						throw new DocumentrException(String.format("Unknown type of '%s'", type));
 					}
 
-					String value = templateObject.getString(KEY_VALUE);
+					String value = templateObject.optString(KEY_VALUE, "");
 					String pathname = documentrJsonFile.getParent() + "/" + value;
 					switch(TYPE_LOOKUP.get(type)) {
 					case TYPE_FILE:
@@ -186,6 +194,7 @@ public void generate() throws DocumentrException {
 						stringBuilder.append("\npre}\n");
 						break;
 					case TYPE_MARKUP:
+					case TYPE_MARKDOWN:
 						stringBuilder.append("\n");
 						stringBuilder.append(value.replaceAll("\\{", "\\{\\{").replaceAll("\\n", "\\{\\\\n\\}").replaceAll("\\t", "\\{\\\\t\\}"));
 						stringBuilder.append("\n");
@@ -221,6 +230,18 @@ public void generate() throws DocumentrException {
 							// ignore - will stay at 6
 						}
 						break;
+					case TYPE_TOCBACKTOTOP:
+						if(value.equalsIgnoreCase("true")) {
+							hasTocBackToTop = true;
+							stringBuilder.insert(0, "<a name=\"top\"></a>");
+						}
+						break;
+					case TYPE_TOCLINKS:
+						if(value.equalsIgnoreCase("true")) {
+							hasTocLinks = true;
+						}
+						break;
+
 					default:
 						throw new DocumentrException(String.format("Could not determine type %s", type));
 					}
@@ -258,17 +279,20 @@ public void generate() throws DocumentrException {
 					}
 
 					// now we need to go through and generate the links to the headers 
-					
-					Iterator<Integer> iterator = HEADER_LOOKUP.keySet().iterator();
-					int start = 0;
-					StringBuilder renderedStringBuilder = new StringBuilder();
-
-					while (iterator.hasNext()) {
-						Integer headerStart = (Integer) iterator.next();
-						Integer headerNum = HEADER_LOOKUP.get(headerStart);
-						renderedStringBuilder.append(Arrays.copyOfRange(charArray, start, headerStart));
-						renderedStringBuilder.append("\n\n<a name=\"heading_" + headerNum + "\"></a>\n\n");
-						start = headerStart;
+					if(hasTocLinks) {
+						Iterator<Integer> iterator = HEADER_LOOKUP.keySet().iterator();
+						int start = 0;
+						StringBuilder renderedStringBuilder = new StringBuilder();
+	
+						while (iterator.hasNext()) {
+							Integer headerStart = (Integer) iterator.next();
+							Integer headerNum = HEADER_LOOKUP.get(headerStart);
+							renderedStringBuilder.append(Arrays.copyOfRange(charArray, start, headerStart));
+							renderedStringBuilder.append("\n\n<a name=\"heading_" + headerNum + "\"></a>\n\n");
+							start = headerStart;
+						}
+
+						rendered = renderedStringBuilder.toString();
 					}
 
 					String markdownToHtml = pegDownProcessor.markdownToHtml(rendered);
@@ -278,14 +302,18 @@ public void generate() throws DocumentrException {
 					Elements headings = document.select("h1, h2, h3, h4, h5, h6");
 					for (Element heading : headings) {
 						int valueOf = Integer.parseInt(heading.nodeName().substring(1));
-						if(valueOf <= tocLevel)
-							headerStringBuilder.append( SPACING_LOOKUP.get(valueOf) + "[" + heading.text() + "](#heading_" + numHeader + ")\n");
+						if(valueOf <= tocLevel) {
+							if(hasTocLinks) {
+								headerStringBuilder.append(SPACING_LOOKUP.get(valueOf) + "[" + heading.text() + "](#heading_" + numHeader + ")\n");
+							} else {
+								headerStringBuilder.append(SPACING_LOOKUP.get(valueOf) + heading.text() + "\n");
+							}
+						}
 						numHeader++;
 					}
 
 					headerStringBuilder.append("\n\n");
 
-					rendered = renderedStringBuilder.toString();
 					rendered = rendered.replace("§§TABLE_OF_CONTENTS§§", headerStringBuilder.toString());
 				}
 

src/main/java/synapticloop/documentr/generator/Generator.java

@@ -30,10 +30,17 @@ be one of the following:
   - file - the file will be included as is with no parsing done on it
   - markup - any valid markdown, with '\n' being replaced with a new line 
         character.  No templar parsing is done on this.
+  - markdown - an alias for markup
   - inbuilt - one of the in-built templates (see below for a list of the 
         inbuilt templates).
   - toc - build up a table of contents, the value set the level of headers that
         will be out put. e.g.: value="1" only h1, value="2" only h1 and h2.
+  - toclinks - whether to display the table of contents as links, and insert
+        links into the headers (default false)
+  - backtotop - this will generate a back to top link for each of the 
+        headers (e.g. h1, h2, h3 etc), the value is the text link (default 
+        'top')
+
 
 The list of inbuilt templates:
 

src/main/resources/HELP.txt

@@ -1 +1,4 @@
+#
+# Implementation class for the plugin
+#
 implementation-class=synapticloop.documentr.plugin.DocumentrPlugin