Adds the @outline tag

Author: matthewp

bit-docs.js

@@ -1,11 +1,14 @@
 var path = require("path");
+var tags = require("./tags");
 
 module.exports = function(bitDocs){
-    var pkg = require("./package.json");
-    var dependencies = {};
-    dependencies[pkg.name] = pkg.version;
+	var pkg = require("./package.json");
+	var dependencies = {};
+	dependencies[pkg.name] = pkg.version;
 
-    bitDocs.register("html", {
-        dependencies: dependencies
-    });
+	bitDocs.register("html", {
+		dependencies: dependencies
+	});
+
+	bitDocs.register("tags", tags);
 }

tags.js

@@ -0,0 +1,36 @@
+/**
+ * @constructor documentjs.tags.outline @outline
+ * @parent documentjs.tags
+ * 
+ * @description 
+ * 
+ * Controls the outline behavior.
+ * 
+ * @signature `@outline DEPTH TAG`
+ * 
+ * Controls the outline's depth and type.
+ * 
+ * @param {Number} [DEPTH=1] The number of headers below and including h2. For example,
+ * `2` will include `h2` and `h3` elements.
+ * 
+ * @param {String} [TAG="ul"] Make the list an ordered list. 
+ * 
+ * @body
+ * 
+ */
+exports.outline = {
+		add: function (line, curData, scope, docMap) {
+			var m = line.match(/@outline\s+(\d+)(?:\s+(ol|ul))?/);
+			if(m) {
+				if(!this.outline) {
+					this.outline = {};
+				}
+				if(m[1]) {
+					this.outline.depth = +m[1];
+				}
+				if(m[2]) {
+					this.outline.tag = m[2];
+				}
+			}
+		}
+	};

toc.js

@@ -6,8 +6,6 @@ var template = stache("{{#each titles}}" +
 	"<li><a ($click)='scrollTo(., %event)' href='#{{id}}'>{{text}}</a></li>" +
 	"{{/each}}");
 
-var toc = document.getElementsByClassName("on-this-page")[0];
-
 function throttle(fn, ms){
 	var wait = false;
 	return function(){
@@ -22,19 +20,30 @@ function throttle(fn, ms){
 	};
 }
 
+function outerHeight(el) {
+  var height = el.offsetHeight;
+  var style = getComputedStyle(el);
+
+  height += parseInt(style.marginTop) + parseInt(style.marginBottom);
+  return height;
+}
+
 var TableOfContents = Control.extend({
 	init: function(el, options){
 		this.scroller = document.body;
-		this.titleSelector = options.titleSelector || ".signature-title";
+		this.container = this.element.parentNode;
 
-		this.navHeight = this.getNavHeight();
+		this.depth = window.docObject.outline && window.docObject.outline.depth || 1;
 
+		this.navHeight = this.getNavHeight();
 		this.titles = this.collectTitles();
 
 		// If there are no titles, bail
 		if(!this.titles.length) {
 			el.parentNode.removeChild(el);
 			return;
+		} else {
+			el.parentNode.style.display = 'block';
 		}
 		this.titleIndex = 0;
 		this.calculateActive();
@@ -46,7 +55,8 @@ var TableOfContents = Control.extend({
 			scrollTo: function(item, ev){
 				ev.preventDefault();
 				toc.disabled(true);
-				window.scrollTo(0, item.pos + 1);
+				var pos = item.pos + toc.TOCHeight;
+				window.scrollTo(0, pos + 1);
 				toc.calculateActive();
 
 				requestAnimationFrame(function(){
@@ -55,6 +65,8 @@ var TableOfContents = Control.extend({
 			}
 		}));
 		this.setActive(this.titleIndex);
+		this.TOCHeight = this.getTOCHeight();
+		this.container.style.height = this.TOCHeight + 'px';
 
 		// Wait until we've appended the TOC so it can be part of the calculation
 		this.fixed(!this.isFirstTitleVisible());
@@ -67,14 +79,22 @@ var TableOfContents = Control.extend({
 		return nav.clientHeight;
 	},
 
+	getTOCHeight: function(){
+		return outerHeight(this.element);
+	},
+
 	isFirstTitleVisible: function(){
 		var firstPosition = this.titles[0].pos + this.element.clientHeight +
 			this.navHeight;
 		return firstPosition > this.scroller.scrollTop;
 	},
 
 	collectTitles: function(){
-		var titles = document.querySelectorAll("article " + this.titleSelector);
+		var selector = this.getHeadings().map(function(h){
+			return "article " + h;
+		}).join(",");
+
+		var titles = document.querySelectorAll(selector);
 		var curScroll = this.scroller.scrollTop;
 		var navHeight = this.navHeight;
 		return [].map.call(titles, function(title, idx){
@@ -89,6 +109,14 @@ var TableOfContents = Control.extend({
 		});
 	},
 
+	getHeadings: function(){
+		var headings = [];
+		for(var i = 0; i < this.depth; i++) {
+			headings.push("h" + (i + 2));
+		}
+		return headings;
+	},
+
 	fixed: function(fixed){
 		if(fixed === this._fixed) {
 			return;
@@ -131,35 +159,48 @@ var TableOfContents = Control.extend({
 
 	calculateActive: function(){
 		var scrollTop = this.scroller.scrollTop;
+		var TOCHeight = this.TOCHeight;
 
 		// Determine which h2 should be showing
 		var prev = this.getTitle(this.titleIndex);
 		var next = this.getTitle(this.titleIndex + 1);
 
 		// See if we need to jump to the next when scrolling down
-		var cur;
-		while(scrollTop > next.pos) {
+		var cur, nextPos = next.pos + TOCHeight;
+		while(scrollTop > nextPos) {
 			cur = next;
 			next = this.getTitle(cur.index + 1);
+			nextPos = next.pos + TOCHeight;
 		}
 
 		// See if we need to move to the previous when scrolling up
 		if(!cur) {
+			var curPos;
 			do {
 				cur = prev;
+				curPos = cur.pos + TOCHeight;
 				prev = this.getTitle(prev.index - 1);
-			} while(scrollTop < cur.pos);
+			} while(scrollTop < curPos);
 		}
 
 		if(typeof cur.pos !== "undefined") {
 			this.setActive(cur.index);
 		}
-	},
+	}
+});
 
+var TOCContainer = Control.extend({
+	init: function(el){
+		el.style.display = 'none';
 
+		var toc = document.createElement("ul");
+		toc.className = "on-this-page";
+		el.appendChild(toc);
 
+		new TableOfContents(toc);
+	}
 });
 
-if(toc) {
-	new TableOfContents(toc);
-}
+new TOCContainer(
+	document.getElementsByClassName("on-this-page-container")[0]
+);