From 235a6c8c75a573ce3810d4e1a7423bcc7cc5b943 Mon Sep 17 00:00:00 2001 From: Josef Bredreck Date: Sun, 16 Aug 2020 20:42:51 +0200 Subject: [PATCH 1/3] Deprecate underscore prefix --- packages/core/src/lib/readDocumentation.js | 71 ++++++++++++++++++- packages/core/src/lib/ui_builder.js | 14 ++-- .../01-global/{_colors.hbs => colors.hbs} | 0 .../_patterns/00-atoms/01-global/colors.md | 3 + 4 files changed, 78 insertions(+), 10 deletions(-) rename packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/{_colors.hbs => colors.hbs} (100%) create mode 100644 packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md 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/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 From 5c0353cdb8c5c8d936f9c8ff2a08e2b56b708f63 Mon Sep 17 00:00:00 2001 From: Josef Bredreck Date: Sun, 16 Aug 2020 20:55:20 +0200 Subject: [PATCH 2/3] #1237: Update tests to use new "hidden" functionality --- packages/core/test/ui_builder_tests.js | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) 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); From acaf69535bfe62c45420f0ecc8bf998aeccc97f7 Mon Sep 17 00:00:00 2001 From: Josef Bredreck Date: Mon, 17 Aug 2020 16:18:51 +0200 Subject: [PATCH 3/3] #1237: Add Documentation --- packages/docs/src/docs/pattern-documenting.md | 2 +- packages/docs/src/docs/pattern-hiding.md | 37 +++++++++++++++++-- 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/packages/docs/src/docs/pattern-documenting.md b/packages/docs/src/docs/pattern-documenting.md index 8cdcdb4658..7563629afa 100644 --- a/packages/docs/src/docs/pattern-documenting.md +++ b/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. diff --git a/packages/docs/src/docs/pattern-hiding.md b/packages/docs/src/docs/pattern-hiding.md index 52ba3acaec..a6fff15898 100644 --- a/packages/docs/src/docs/pattern-hiding.md +++ b/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. \ No newline at end of file