Merge acaf695 into 7050836

packages/core/src/lib/readDocumentation.js

@@ -1,7 +1,8 @@
 'use strict';
 
-const path = require('path');
 const _ = require('lodash');
+const path = require('path');
+const fs = require('fs-extra');
 
 const ch = require('./changes_hunter');
 const logger = require('./log');
@@ -10,14 +11,14 @@ const mp = require('./markdown_parser');
 const changes_hunter = new ch();
 const markdown_parser = new mp();
 
-let fs = require('fs-extra'); //eslint-disable-line prefer-const
+const FILE_EXTENSION = '.md';
 
 module.exports = function(pattern, patternlab) {
   try {
     const markdownFileName = path.resolve(
       patternlab.config.paths.source.patterns,
       pattern.subdir,
-      pattern.fileName + '.md'
+      pattern.fileName + FILE_EXTENSION
     );
     changes_hunter.checkLastModified(pattern, markdownFileName);
 
@@ -78,4 +79,68 @@ module.exports = function(pattern, patternlab) {
       logger.warning(err);
     }
   }
+
+  // Read Documentation for Pattern-Group
+  // Use this approach, since pattern lab is a pattern driven software
+  try {
+    const markdownFileNameGroup = path.resolve(
+      patternlab.config.paths.source.patterns,
+      pattern.patternType,
+      pattern.patternGroup + FILE_EXTENSION
+    );
+    const markdownFileContentsGroup = fs.readFileSync(
+      markdownFileNameGroup,
+      'utf8'
+    );
+    const markdownObjectGroup = markdown_parser.parse(
+      markdownFileContentsGroup
+    );
+
+    if (!_.isEmpty(markdownObjectGroup)) {
+      pattern.patternGroupData = markdownObjectGroup;
+    }
+  } catch (err) {
+    // do nothing when file not found
+    if (err.code !== 'ENOENT') {
+      logger.warning(
+        `'there was an error setting pattern group data after markdown parsing for ${path.join(
+          pattern.patternType,
+          pattern.patternGroup + FILE_EXTENSION
+        )}`
+      );
+      logger.warning(err);
+    }
+  }
+
+  // Read Documentation for Pattern-Subgroup
+  try {
+    const markdownFileNameSubGroup = path.resolve(
+      patternlab.config.paths.source.patterns,
+      pattern.patternType,
+      pattern.patternSubType,
+      pattern.patternSubGroup + FILE_EXTENSION
+    );
+    const markdownFileContentsSubGroup = fs.readFileSync(
+      markdownFileNameSubGroup,
+      'utf8'
+    );
+    const markdownObjectSubGroup = markdown_parser.parse(
+      markdownFileContentsSubGroup
+    );
+
+    if (!_.isEmpty(markdownObjectSubGroup)) {
+      pattern.patternSubGroupData = markdownObjectSubGroup;
+    }
+  } catch (err) {
+    // do nothing when file not found
+    if (err.code !== 'ENOENT') {
+      logger.warning(
+        `'there was an error setting pattern sub group data after markdown parsing for ${path.join(
+          pattern.patternSubType,
+          pattern.patternSubGroup + FILE_EXTENSION
+        )}`
+      );
+      logger.warning(err);
+    }
+  }
 };

packages/core/src/lib/ui_builder.js

@@ -77,11 +77,11 @@ const ui_builder = function() {
       return true;
     }
 
-    // skip underscore-prefixed files
-    isOmitted = pattern.isPattern && pattern.fileName.charAt(0) === '_';
+    // skip marked as hidden patterns
+    isOmitted = pattern.isPattern && pattern.hidden;
     if (isOmitted) {
       logger.info(
-        `Omitting ${pattern.patternPartial} from styleguide patterns because it has an underscore prefix.`
+        `Omitting ${pattern.patternPartial} from styleguide patterns because it is marked as hidden within it's documentation.`
       );
       return true;
     }
@@ -96,13 +96,13 @@ const ui_builder = function() {
       return true;
     }
 
-    // this pattern is contained with a directory prefixed with an underscore (a handy way to hide whole directories from the nav
+    // this pattern is contained with a directory documented as hidden (a handy way to hide whole directories from the nav
     isOmitted =
-      pattern.relPath.charAt(0) === '_' ||
-      pattern.relPath.indexOf(path.sep + '_') > -1;
+      (pattern.patternGroupData && pattern.patternGroupData.hidden) ||
+      (pattern.patternSubGroupData && pattern.patternSubGroupData.hidden);
     if (isOmitted) {
       logger.info(
-        `Omitting ${pattern.patternPartial} from styleguide patterns because its contained within an underscored directory.`
+        `Omitting ${pattern.patternPartial} from styleguide patterns because its contained within an hidden directory.`
       );
       return true;
     }

packages/core/test/ui_builder_tests.js

@@ -72,7 +72,8 @@ tap.test(
   function(test) {
     //arrange
     var patternlab = createFakePatternLab({});
-    var pattern = new Pattern('00-test/_ignored-pattern.mustache');
+    var pattern = new Pattern('00-test/ignored-pattern.mustache');
+    pattern.hidden = true;
 
     //act
     var result = ui.isPatternExcluded(pattern, patternlab, uikit);
@@ -108,7 +109,7 @@ tap.test(
     var pattern = Pattern.createEmpty({
       relPath:
         path.sep +
-        '_hidden' +
+        'hidden' +
         path.sep +
         'patternsubtype' +
         path.sep +
@@ -118,6 +119,10 @@ tap.test(
       patternPartial: 'hidden-foo',
     });
 
+    pattern.patternGroupData = {
+      hidden: true,
+    };
+
     //act
     var result = ui.isPatternExcluded(pattern, patternlab, uikit);
 
@@ -134,12 +139,16 @@ tap.test(
     var patternlab = createFakePatternLab({});
     var pattern = Pattern.createEmpty({
       relPath:
-        'shown' + path.sep + '_patternsubtype' + path.sep + 'foo.mustache',
+        'shown' + path.sep + 'patternsubtype' + path.sep + 'foo.mustache',
       isPattern: true,
       fileName: 'foo.mustache',
       patternPartial: 'shown-foo',
     });
 
+    pattern.patternSubGroupData = {
+      hidden: true,
+    };
+
     //act
     var result = ui.isPatternExcluded(pattern, patternlab, uikit);
 

packages/docs/src/docs/pattern-documenting.md

@@ -53,5 +53,5 @@ We'd name our documentation file:
 
 ## Adding More Attributes to the Front Matter
 
-A future update of Pattern Lab will support more front matter attributes including: excludeFromStyleguide, order, hidden and links.
+A future update of Pattern Lab will support more front matter attributes including: excludeFromStyleguide, order and links.
 It will also support adding custom attributes that could be utilized by plugins. For example, GitHub issues related to patterns.

packages/docs/src/docs/pattern-hiding.md

@@ -9,14 +9,43 @@ eleventyNavigation:
   order: 170
 ---
 
-To remove a pattern from Pattern Lab's drop-down navigation and style guide add an underscore (`_`) to the beginning of the pattern name. For example, we may have a Google Map-based pattern that we don't need for a particular project. The path might look like:
+Removing a pattern from Pattern Lab's drop-down navigation and style guide is accomplished by setting the `hidden` frontmatter key on any pattern's companion `.md` file. For example, we may have a Google Map-based pattern that we don't need for a particular project. The path might look like:
 
     molecules/media/map.mustache
 
-To "hide" the pattern we add the underscore and re-generate our site:
+We would create or edit a file in the same location, calling it `map.md`:
 
-    molecules/media/_map.mustache
+```
+---
+hidden: true
+---
+The map component...
+```
+
+## Hiding Pattern Groups
+
+The same concept applies to `pattern-groups`. For example, we have a `pattern-group` named `atoms` and we create a companion `.md` file for that group under `_patters/atoms/atoms.md`. In that case the whole `pattern-group` and all its components will be hidden in the UI.
+
+```
+---
+hidden: true
+---
+# atoms.md file
+```
+
+## Hiding Pattern Sub Groups
+
+The same concept applies to `pattern-sub-groups`. For example, we have a `pattern-sub-group` named `buttons` which is structured under `atoms` and we create a companion `.md` file for that group under `_patters/atoms/buttons/buttons.md`. In that case the whole `pattern-sub-group` and all its components will be hidden in the UI.
+
+```
+---
+hidden: true
+---
+# buttons.md file
+```
+
+## Additional Information
 
 A hidden pattern can still be included in other patterns.
 
-Not all PatternEngines support hiding patterns.
+Not all PatternEngines support hiding patterns.

packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md

@@ -0,0 +1,3 @@
+---
+hidden: true
+---