diff --git a/packages/core/src/lib/readDocumentation.js b/packages/core/src/lib/readDocumentation.js
index edd11de6e6..9e633259ab 100644
--- a/packages/core/src/lib/readDocumentation.js
+++ b/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);
+    }
+  }
 };
diff --git a/packages/core/src/lib/ui_builder.js b/packages/core/src/lib/ui_builder.js
index 4a077a613e..b5730dc1c8 100644
--- a/packages/core/src/lib/ui_builder.js
+++ b/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;
     }
diff --git a/packages/core/test/ui_builder_tests.js b/packages/core/test/ui_builder_tests.js
index 00fd29ec04..21defffb23 100644
--- a/packages/core/test/ui_builder_tests.js
+++ b/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);
 
diff --git a/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/_colors.hbs b/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.hbs
similarity index 100%
rename from packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/_colors.hbs
rename to packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.hbs
diff --git a/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md b/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md
new file mode 100644
index 0000000000..20ceb0395a
--- /dev/null
+++ b/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md
@@ -0,0 +1,3 @@
+---
+hidden: true
+---
\ No newline at end of file