1.4.0

Author: jonathantneal

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.4.0 (2015-01-26)
+
+- Added: Automatically detects sibling markdown documentation
+- Added: Forward plugin options when theme-specific options are unspecified
+- Updated: Detects documentation relative to the original partial
+- Updated: Documentation
+
 ## 1.3.0 (2015-11-17)
 
 - Updated: Package dependencies

README.md

@@ -6,26 +6,24 @@
 
 [mdcss] lets you easily create and maintain style guides with CSS comments using Markdown.
 
-```css
-/*---
-title:   Buttons
-section: Base CSS
----
-
-Button styles can be applied to any element. Typically you'll want to use
-either a `<button>` or an `<a>` element:
-
-​```example:html
-<button class="btn">Click</button>
-<a class="btn" href="/some-page">Some Page</a>
-​```
-*/
-
-.btn {
-	background-color: black;
-	color: white;
-}
-```
+	/*---
+	title:   Buttons
+	section: Base CSS
+	---
+
+	Button styles can be applied to any element. Typically you'll want to use
+	either a `<button>` or an `<a>` element:
+
+	```example:html
+	<button class="btn">Click</button>
+	<a class="btn" href="/some-page">Some Page</a>
+	```
+	*/
+
+	.btn {
+		background-color: black;
+		color: white;
+	}
 
 ![screenshot](https://cloud.githubusercontent.com/assets/188426/11217538/cfeb322a-8d1e-11e5-9a64-2c5373968663.png)
 
@@ -125,6 +123,14 @@ require('mdcss')({
 })
 ```
 
+Theme-specific options may also be passed in from the theme module itself, but note that any global options would then be ignored.
+
+```js
+require('mdcss')({
+	theme: require('mdcss-theme-github')(/* options */)
+})
+```
+
 #### `destination`
 
 Type: `String`  
@@ -187,15 +193,16 @@ either a <code>&lt;button&gt;</code> or an <code>&lt;a&gt;</code> element:</p>
 The contents of a section may also be imported from another file.
 
 **buttons.md**:
-```md
-Button styles can be applied to **any** element. Typically you'll want to use
-either a `<button>` or an `<a>` element:
 
-​```html
-<button class="btn">Click</button>
-<a class="btn" href="/some-page">Some Page</a>
-​```
-```
+	Button styles can be applied to **any** element. Typically you'll want to use
+	either a `<button>` or an `<a>` element:
+
+	```html
+	<button class="btn">Click</button>
+	<a class="btn" href="/some-page">Some Page</a>
+	​```
+
+**base.css**:
 
 ```css
 /*---
@@ -204,6 +211,8 @@ import: buttons.md
 ---*/
 ```
 
+The contents of a section may be automatically imported as well. For example, had the `import` been omitted, a sibling file of `base.buttons.md` or `base.md` would have been used (in that order of preference) if they existed.
+
 ### Details
 
 Additional heading details are added before a second set of three dashes `---` in a section. These heading details are parsed and added to the [`documentation` object](#documentation-object).

index.js

@@ -2,7 +2,7 @@ var fs     = require('fs-promise');
 var marked = require('marked');
 var path   = require('path');
 
-var isDoc  = /^\s*-{3,}\n(?:([\W\w]*?)\n\s*-{3,})?/;
+var isDoc = /^\s*-{3,}\n((?:[A-z][\w-]*\s*:\s*[\w-][^\n]*\n*)*)(?:\s*-{3,})?/;
 var isMeta = /([A-z][\w-]*)\s*:\s*([\w-][^\n]*)/g;
 
 module.exports = require('postcss').plugin('mdcss', function (opts) {
@@ -19,15 +19,17 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {
 	if (typeof opts.theme !== 'function') throw Error('The theme failed to load');
 
 	// conditionally set theme as executed theme
-	if (opts.theme.type === 'mdcss-theme') opts.theme = opts.theme();
+	if (opts.theme.type === 'mdcss-theme') opts.theme = opts.theme(opts);
 
 	// set destination path
 	opts.destination = path.join(process.cwd(), opts.destination || 'styleguide');
 
 	// return plugin
-	return function (css) {
-		// set directory, documentation list, hash, and unique identifier
-		var dir  = css.source.input.file ? path.dirname(css.source.input.file) : process.cwd();
+	return function (css, result) {
+		// set current css directory or current directory
+		var dir = css.source.input.file ? path.dirname(css.source.input.file) : process.cwd();
+
+		// set documentation list, hash, and unique identifier
 		var list = [];
 		var hash = {};
 		var uniq = 0;
@@ -50,19 +52,54 @@ module.exports = require('postcss').plugin('mdcss', function (opts) {
 					return '';
 				}, opts.marked).trim());
 
+				// conditionally set the closest documentation name
+				if (doc.title && !doc.name) doc.name = titleToName(doc.title);
+
 				// conditionally import external content
-				if (!doc.content && doc.import) try {
-					doc.content = marked(fs.readFileSync(path.join(dir, doc.import), 'utf8').trim());
-				} catch (error) {
-					comment.warn('Imported content could not be read');
+				if (!doc.content) {
+					// get comment source path
+					var src = comment.source.input.file;
+
+					// if the comment source path exists
+					if (src) {
+						// get the closest matching directory for this comment
+						var localdir = src ? path.dirname(src) : dir;
+
+						var mdbase = doc.import;
+						var mdspec;
+
+						// conditionally use a sibling md files if no import exists
+						if (!mdbase) {
+							mdbase = mdspec = path.basename(src, path.extname(src));
+
+							if (doc.name) {
+								mdspec += '.' + doc.name;
+							}
+
+							mdbase += '.md';
+							mdspec += '.md';
+						}
+
+						// try to read the closest matching documentation
+						try {
+							if (mdspec) {
+								doc.content = fs.readFileSync(path.join(localdir, mdspec), 'utf8');
+							} else throw new Error();
+						} catch (error1) {
+							try {
+								doc.content = fs.readFileSync(path.join(localdir, mdbase), 'utf8');
+							} catch (error2) {
+								doc.content = '';
+
+								comment.warn(result, 'Documentation comment could not be read.');
+							}
+						}
+					}
 				}
 
 				// set documentation context
 				doc.context = comment;
 
-				// conditionally set documentation name
-				if (doc.title && !doc.name) doc.name = titleToName(doc.title);
-
 				// insure documentation has unique name
 				var name = doc.name || 'section' + --uniq;
 				var uniqname = name;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdcss",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Easily create and maintain style guides with CSS comments using Markdown",
   "keywords": [
     "postcss",
@@ -21,25 +21,20 @@
   ],
   "author": "Jonathan Neal <jonathantneal@hotmail.com>",
   "license": "CC0-1.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/jonathantneal/mdcss.git"
-  },
+  "repository": "jonathantneal/mdcss",
   "homepage": "https://github.com/jonathantneal/mdcss",
-  "bugs": {
-    "url": "https://github.com/jonathantneal/mdcss/issues"
-  },
+  "bugs": "https://github.com/jonathantneal/mdcss/issues",
   "dependencies": {
-    "fs-extra": "^0.26.2",
+    "fs-extra": "^0.26.4",
     "fs-promise": "^0.3.1",
     "marked": "^0.3.5",
-    "mdcss-theme-github": "^2.0.1",
-    "postcss": "^5.0.12"
+    "mdcss-theme-github": "^2.1.0",
+    "postcss": "^5.0.14"
   },
   "devDependencies": {
-    "eslint": "^1.9.0",
-    "tap-spec": "^4.1.0",
-    "tape": "^4.2.2"
+    "eslint": "^1.10.3",
+    "tap-spec": "^4.1.1",
+    "tape": "^4.4.0"
   },
   "scripts": {
     "lint": "eslint . --ignore-path .gitignore",

test/index.js

@@ -9,7 +9,8 @@ var tests = {
 				examples:    {
 					css: ['../fixtures/basic.css']
 				}
-			}
+			},
+			warning: 1
 		}
 	}
 };