Permalink
Browse files

Even more updates to TOH

  • Loading branch information...
1 parent 1ac1ea1 commit 9e62681da9240d200ca556381f8dd0b14ecc32e0 @gjtorikian committed Aug 2, 2012
Showing with 115 additions and 7 deletions.
  1. +68 −6 README.md
  2. +1 −0 lib/generator.js
  3. +45 −0 lib/toh.js
  4. +1 −1 package.json
View
@@ -94,12 +94,16 @@ You have to specify at least one Jade file as a template for your pages. Within
* `metadata` is an object containing your document-based metadata values
* `manifest` is an object containing the Manifest.json properties
* `toh` is an object containing the headings for each file (`h1`, `h2`, _e.t.c._). See below for more information on this object.
+* `headingTable` is a function you can use to generate a list of your page's table of contents. See below for more information on using this
* `options` is an object containing your passed in properties
* `fileName` is the name of the resulting file (without the extension)
* `title` is the title of the documentation
* `pageTitle` is the title of the current page
* `mtime` indicates the last modified time of your source Markdown file
+
+#### Working with a Table of Contents for a Page
+
The `toh` object has the following structure:
```json
@@ -113,16 +117,21 @@ The `toh` object has the following structure:
rank: 2,
name: "Subtitle",
link: "#subtitle",
- line: 1
+ line: 4
}, {
rank: 4,
- name: "Next Header",
- link: "#next-header",
+ name: "Minor Header",
+ link: "#minor-header",
line: 25
- }]
+ },{
+ rank: 2,
+ name: "Another Subtitle!",
+ link: "#another-subtitle",
+ line: 58
+}]
```
-Each non-`h1` header is also automatically an anchor. The HTML for an H2 called "Testing Your Highlighter" looks like this:
+Each non-`h1` header is also automatically an anchor. The resulting HTML for an H2 called "Testing Your Highlighter" looks like this:
```html
<h2>
@@ -132,4 +141,57 @@ Each non-`h1` header is also automatically an anchor. The HTML for an H2 called
</h2>
```
-You can add an icon for `headerLinkIcon` to make it more discoverable, _i.e._ by using something from [Font Awesome](http://fortawesome.github.com/Font-Awesome/).
+You can add an icon for `headerLinkIcon` to make it more discoverable, _i.e._ by using something from [Font Awesome](http://fortawesome.github.com/Font-Awesome/).
+
+Finally, you also have access to a function, called `headingTable`, that automatically generates a table of contents for each page's heading. The resulting HTML produced by this function might look like this:
+
+```html
+<ol class="tocContainer level_1">
+ <li class="tocItem level_2">
+ <a href="#defining-a-mode">Defining a Mode</a>
+ </li>
+ <li class="tocItem level_2">
+ <a href="#defining-syntax-highlighting-rules">Defining Syntax Highlighting Rules</a>
+ <ol class="tocContainer level_2">
+ <li class="tocItem level_3">
+ <a href="#defining-tokens">Defining Tokens</a>
+ </li>
+ <li class="tocItem level_3">
+ <a href="#defining-regular-expressions">Defining Regular Expressions</a>
+ <ol class="tocContainer level_3">
+ <li class="tocItem level_4">
+ <a href="#groupings">Groupings</a>
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </li>
+ <li class="tocItem level_2">
+ <a href="#defining-states">Defining States</a>
+ </li>
+ <li class="tocItem level_2">
+ <a href="#code-folding">Code Folding</a>
+ </li>
+</ol>
+```
+
+Basically, every sub-heading is nested underneath a parent heading of larger size. In the example above, we have a page with an `<h2>` tag called "Defining a Mode", followed by another `<h2>`, "Defining Syntax Highlighting Rules", which itself is followed by two `<h3>` tags, "Defining Tokens" and "Defining Regular Expressions." The last `<h3>` has an `<h4>` called "Groupings." We then go back to some regular old `<h2>` tags.
+
+This generated table always ignores the `<h1>` tag. You can customize it by by embedding the following signature into your Jade template:
+
+```javascript
+headingTable(toh, maxLevel, classes)
+```
+
+where
+
+* `toh` is your page's `toh` object
+* `maxLevel` is optional, and refers to the maximum heading number you want to display; this defaults to 4. Basically, any `h` tag greater than this number is ignored
+* `classes` is optional, and it's an array of two strings. The first is a class that applies to all the `<ol>` tags; the second applies to the `<li>` tags. Every `<ol>` and `<li>` automatically gets a `level_<POSITION>` class that is set to the current item's position
+
+
+Thus, to generate the above, your Jade template might go:
+
+```jade
+!= headingTable(toh, 5, ['tocContainer', 'tocItem'])
+```
View
1 lib/generator.js 100755 → 100644
@@ -60,6 +60,7 @@ Generator.render = function(manifest, jadeCompileFn, filepath, file, srcContent,
manifest: manifest,
content: content,
toh: toh,
+ headingTable: tohGenerator.headingTable,
metadata: metadata,
fileName: file,
whoAmI: filepath,
View
45 lib/toh.js 100755 → 100644
@@ -64,5 +64,50 @@ module.exports = {
var link = linkify(text);
return "<h" + type + "><a name='"+link.substr(1)+"' class='heading_anchor' href='"+link+"'></a><i class='headerLinkIcon'></i>"+text+"</h" + type + ">";
});
+ },
+
+ headingTable: function (toh, maxLevel, classes) {
+ if (toh.length > 1) {
+ var tocHTML = "";
+ var assignedLevel = 0;
+ if (maxLevel instanceof Array) {
+ classes = maxLevel;
+ maxLevel = null;
+ }
+ if (!maxLevel) maxLevel = 4;
+
+ var firstOL = 0; // a pathetic hack
+
+ for (var h = 1; h < toh.length; h++) {
+ var heading = toh[h];
+ var currentLevel = heading.rank;
+
+ if (currentLevel > maxLevel) continue;
+
+ if (assignedLevel !== currentLevel - 1) {
+ tocHTML += "</li>"
+ }
+
+ while (assignedLevel < currentLevel) {
+ if (firstOL == 0) firstOL = 1;
+ else tocHTML += "<ol" + (classes.length ? " class='" + classes[0] + " level_" + assignedLevel + "'>" : ">")
+ assignedLevel++
+ }
+
+ while (assignedLevel > currentLevel) {
+ tocHTML += "</ol></li>"
+ assignedLevel--;
+ }
+
+ tocHTML += "<li" + (classes.length ? " class='" + classes[1] + " level_" + assignedLevel + "'>" : ">") + "<a href='" + heading.link + "'>" + heading.name + "</a>";
+ }
+
+ while (assignedLevel > 0) {
+ tocHTML += "</li></ol>";
+ assignedLevel--;
+ }
+ }
+
+ return tocHTML;
}
};
View
2 package.json 100755 → 100644
@@ -1,6 +1,6 @@
{
"name": "panda-docs",
- "version": "0.3.8",
+ "version": "0.3.9",
"author": "Garen Torikian",
"keywords": ["documentation", "docs", "markdown"],
"description": "A complete documentation generation tool for Markdown files",

0 comments on commit 9e62681

Please sign in to comment.