Enabled metadata via paths

Added option to parse metadata from folder/file names.

Author: tunurgitr

index.js

@@ -18,7 +18,7 @@ function gulpMarkdownDocs(fileOpt, opt) {
 	var DEFAULTS = {
 		yamlMeta: true,
 		stylesheetUrl: '',
-		categorySort: 'alphabetical', // 'alphabetical' || 'rank' 
+		categorySort: 'alphabetical', // 'alphabetical' || 'rank'
 		documentSort: 'alphabetical', // 'alphabetical' || 'rank'
 		layoutStylesheetUrl: __dirname + '/resources/layout.css',
 		templatePath: __dirname + '/resources/index.html',
@@ -36,16 +36,16 @@ function gulpMarkdownDocs(fileOpt, opt) {
 		  smartLists: true,
 		  smartypants: false
 		}
-	}
+	};
 	var _ORPHAN_SLUG = 'orphans';
-	
-	// merge defaults and passed options 
+
+	// merge defaults and passed options
 	var options = _.extend({}, DEFAULTS, opt);
 	var markdownOptions = options.markdown = _.extend({}, DEFAULTS.markdown, opt.markdown);
 
 	// apply options for markdown parsing
 	marked.setOptions(markdownOptions);
-	
+
 	// gather needed resources
 	var indexHtml = fs.readFileSync(options.templatePath);
 	var highlightCss = fs.readFileSync(require.resolve('highlight.js/styles/'+options.highlightTheme+'.css'));
@@ -57,8 +57,8 @@ function gulpMarkdownDocs(fileOpt, opt) {
 	$head.append('<style>'+highlightCss+'</style>');
 	if (layoutCss) { $head.append('<style>'+layoutCss+'</style>'); }
 	// add the custom style sheet last for sensible overrides
-	if (options.stylesheetUrl) { 
-		$head.append('<link rel="stylesheet" type="text/css" href="'+options.stylesheetUrl+'">'); 
+	if (options.stylesheetUrl) {
+		$head.append('<link rel="stylesheet" type="text/css" href="'+options.stylesheetUrl+'">');
 	}
 
 	if (typeof fileOpt !== 'string') {
@@ -80,9 +80,9 @@ function gulpMarkdownDocs(fileOpt, opt) {
 		categories.forEach(function (category) {
 			var $section = $('<section class="doc-section"></section>');
       var $navGroup = $('<ul class="doc-nav-group"></ul>');
-			if (category.categoryLabel && category.categorySlug !== _ORPHAN_SLUG) { 
+			if (category.categoryLabel && category.categorySlug !== _ORPHAN_SLUG) {
 				$navGroup.append('<li class="doc-nav-group-header"><a href="#'+category.categorySlug+'">'+category.categoryLabel+'</a></li>');
-				$section.append('<h1 class="doc-section-header"><a class="doc-nav-anchor" name="'+category.categorySlug+'"></a>'+category.categoryLabel+'</h1>'); 
+				$section.append('<h1 class="doc-section-header"><a class="doc-nav-anchor" name="'+category.categorySlug+'"></a>'+category.categoryLabel+'</h1>');
 			}
 			category.children.forEach(function (doc) {
 				var anchor = '';
@@ -119,15 +119,15 @@ function gulpMarkdownDocs(fileOpt, opt) {
 				categories[slug].categoryRank = (!!doc.meta.categoryRank) ? doc.meta.categoryRank : categories[slug].categoryRank;
 			} else {
 				categories[_ORPHAN_SLUG] = categories[_ORPHAN_SLUG] || { children: [] };
-				categories[_ORPHAN_SLUG].children.push(doc); 
+				categories[_ORPHAN_SLUG].children.push(doc);
 				// orphans go to the back
 				categories[_ORPHAN_SLUG].categoryRank = 1000000;
 				categories[_ORPHAN_SLUG].categoryLabel = 'zzzzzzz';
 			}
 		});
 		// map categories into an array
 		categories = _.map(categories, function (category, key) {
-			return { categoryLabel: category.categoryLabel, children: category.children, categoryRank: category.categoryRank, categorySlug: key }
+			return { categoryLabel: category.categoryLabel, children: category.children, categoryRank: category.categoryRank, categorySlug: key };
 		});
 		// sort categories
 		categories = _.sortBy(categories, (options.categorySort === 'rank' ? 'categoryRank' : 'categoryLabel'));
@@ -143,7 +143,7 @@ function gulpMarkdownDocs(fileOpt, opt) {
 	var firstFile = null;
 	function bufferContents(file) {
 		if (file.isNull()) return; // ignore
-    if (file.isStream()) return this.emit('error', new PluginError('gulp-markdown-docs',  'Streaming not supported'));
+    	if (file.isStream()) return this.emit('error', new PluginError('gulp-markdown-docs',  'Streaming not supported'));
 
 		var markdown, meta, html;
 		if (!firstFile) firstFile = file;
@@ -153,7 +153,28 @@ function gulpMarkdownDocs(fileOpt, opt) {
 			delete parsedFile['__content'];
 			var metadata = parsedFile;
 
-			if (options.yamlMeta) {
+            if (options.yamlMeta === 'use-paths') {
+                var relativePath = file.path.substring(file.base.length);
+                var relativePathMinusExtension = relativePath.substring(0, relativePath.lastIndexOf('.'));
+
+				var pathSegments = relativePathMinusExtension.split('\\');
+
+				if (pathSegments.length > 1) {
+					var fileParts = pathSegments[pathSegments.length - 1].split(' ');
+					var name = fileParts[fileParts.length-1].substring(0, fileParts[fileParts.length-1].lastIndexOf('.'));
+					var categoryParts = pathSegments[pathSegments.length - 2].split(' ');
+					meta = {};
+					meta.documentRank = fileParts.length > 1 ? parseInt(fileParts.shift()) : 0;
+					meta.label = fileParts.join(' ');
+					meta.categoryRank = categoryParts.length > 1 ? parseInt(categoryParts.shift()) : 0;
+					meta.categorySlug = meta.categoryLabel = categoryParts.join(' ');
+					meta.id = categoryParts.join('-').toLowerCase() + '_' + fileParts.join('-').toLowerCase();
+				}
+				collectedDocs.push({
+					html: parseMarkdown(markdown),
+                    meta: meta
+				});
+			} else if (options.yamlMeta) {
 				collectedDocs.push({
 					meta: metadata,
 					html: parseMarkdown(markdown)
@@ -172,12 +193,12 @@ function gulpMarkdownDocs(fileOpt, opt) {
 		if (firstFile) {
 			var joinedFile = firstFile;
 			var sortedDocs = sortDocs(collectedDocs);
-			
+
 			appendToIndex(sortedDocs);
-			
+
 			if (typeof fileOpt === 'string') {
 				joinedFile = firstFile.clone({contents: false});
-				joinedFile.path = path.join(firstFile.base, fileOpt)
+				joinedFile.path = path.join(firstFile.base, fileOpt);
 			}
 			joinedFile.contents = new Buffer($.html());
 	  	this.emit('data', joinedFile);
@@ -186,7 +207,6 @@ function gulpMarkdownDocs(fileOpt, opt) {
 	}
 
   return through(bufferContents, endStream);
-};
+}
 
 module.exports = gulpMarkdownDocs;
-

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gulp-markdown-docs",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "",
   "license": "MIT",
   "repository": "sojournerc/gulp-markdown-docs",

readme.md

@@ -28,32 +28,47 @@ gulp.task('default', function () {
 
 #### Meta Information
 
-    yamlMeta: true
+    yamlMeta: true // true || false || 'use-paths'
 
-*Required* in order to construct the navigation menu. When set to true, each document given to gulp-markdown-docs should have a Front Matter YAML header providing needed information about the document.
+*Must be either truthy or 'use paths'* in order to construct the navigation menu.
+
+When set to true, each document given to gulp-markdown-docs should have a Front Matter YAML header providing needed information about the document.
 
 ```md
 ---
 label: Nav Label
 id: unique_slug
 categorySlug:
-categoryLabel: 
-categoryRank: 
-documentRank: 
+categoryLabel:
+categoryRank:
+documentRank:
 ---
 
 # Your Content
 ...
 ```
 
+When set to 'use paths', the folder structure will be used to determine the metadata. The first part of the markdown filename should start with a number to indicate the `documentRank`, followed by a space, and the rest of the filename will be used for the `label` (without the extension).
+
+Each markdown file should be in a folder with a similar naming strategy: the first part of the folder name should be a number indicating the `categoryRank`, the rest of the folder name will be used as the `categorySlug` and `categoryLabel`. The `id` is created by appending the `categoryLabel` and `label` properties.
+
+```
+docs\10 Intro\10 Definitions.md
+docs\10 Intro\20 Theory.md
+docs\20 Getting Started\01 Step 1.md
+...
+```
+
+This has the advantage of keeping your file structure sorted in the same way as the output HTML.
+
 #### Sorting (`yamlMeta` must be true)
 If you wanted a document or category to always be at the end you could set this to 10000, or beginning -10000.
 
 All sorting is done on a last-in basis, so the last rank seen is the value used for the category
 
 **NOTE**  slugs/ids need to be unique between categories and documents TODO: !!
 
-    categorySort: 'alphabetical', // 'alphabetical' || 'rank' 
+    categorySort: 'alphabetical', // 'alphabetical' || 'rank'
     documentSort: 'alphabetical', // 'alphabetical' || 'rank'
 
 #### External Stylesheet
@@ -72,15 +87,15 @@ gulp-markdown-docs includes a simple layout by default. `false` will prevent it
 
     templatePath: __dirname + '/resources/index.html'
 
-gulp-markdown-docs includes a simple HTML document by default. Passing a path to a different HTML file allows you to customize the resulting documentation page. 
-**NOTE** This module looks for `<head>...</head>` to add stylesheets to, and `.doc-nav` and `.doc-content` to append the navigation items and documentation respectively. 
+gulp-markdown-docs includes a simple HTML document by default. Passing a path to a different HTML file allows you to customize the resulting documentation page.
+**NOTE** This module looks for `<head>...</head>` to add stylesheets to, and `.doc-nav` and `.doc-content` to append the navigation items and documentation respectively.
+
+#### Highlight theme
 
-#### Highlight theme 
-    
     highlightTheme: 'solarized_dark'
 
 see [highlight.js](https://highlightjs.org/) for available themes
-    
+
 
 #### Markdown
 
@@ -98,7 +113,7 @@ see [highlight.js](https://highlightjs.org/) for available themes
       smartypants: false
     }
 
-Defaults shown. See documentation for [marked](https://www.npmjs.org/package/marked) for additional details. 
+Defaults shown. See documentation for [marked](https://www.npmjs.org/package/marked) for additional details.
 
 
 ## License