Feature Request: Allow Display of other files in pattern docs

[davejtoews]

I would like to be able to attach other files to my pattern documentation. I break my SCSS and javascript files into pattern specific files. It would be nice to be able to reference these on the front end, perhaps by specifying additional files in the markdown metadata, like so:

files:
  - type: SCSS
    path: /css/scss/example.scss
  - type: Javascript
    path: /js/example.js

Hopefully resulting in something like this:

[bradfrost]

Hey @davejtoews! The ability to add tabs is available as a plugin. I don't know the status of it in the PHP version or if it's just a Node plugin. @bmuenzenmeyer, any guidance here?

That said, we're in the process of revisiting how we wrangle pattern meta data, and this (or something like this) seems sensible from a syntax standpoint. @EvanLovely @bmuenzenmeyer, you would know more than me on where we're at with code tabs; any insights here?

[bmuenzenmeyer]

My plugin is node only, yes.

…

On Thu, Oct 26, 2017, 10:01 PM Brad Frost ***@***.***> wrote: Hey @davejtoews <https://github.com/davejtoews>! The ability to add tabs is available as a plugin <https://github.com/pattern-lab/plugin-node-tab>. I don't know the status of it in the PHP version or if it's just a Node plugin. @bmuenzenmeyer <https://github.com/bmuenzenmeyer>, any guidance here? That said, we're in the process of revisiting how we wrangle pattern meta data, and this (or something like this) seems sensible from a syntax standpoint. @EvanLovely <https://github.com/evanlovely> @bmuenzenmeyer <https://github.com/bmuenzenmeyer>, you would know more than me on where we're at with code tabs; any insights here? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#144 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASNw_3dSO1alISPzO3QXLr9ptr0vJU3ks5swUdugaJpZM4QDnTM> .

[davejtoews]

Thanks for the info @bradfrost. I'm happy to see all the attention the PHP version is getting recently, and I'm looking forward to see what's next.

[sghoweri]

@davejtoews does #95 match up with what you were hoping for here? Perhaps we could combine the two and look into bumping this up the list of priorities?

[davejtoews]

@sghoweri As I currently use PatternLab, my SCSS and JS/JSX files have their own parallel patterns (atoms, molecules, organisms, etc) directories. My webpack config looks in scss/ and es2015/ and their subdirectories to find such files and bundle them into a single main.css and bundle.js. This structure is easy enough to duplicate in projects where I deploy my patterns.

In issue #95, @sbuckpesch suggests throwing all files for a pattern into the appropriate _patterns/ subdirectory. I've got a couple of questions about that:

1. Does this set up allow for bundling/transpiling all these assets, or are they there for documentation purposes only?
2. How does this structure compare to the actual use of the patterns in production sites/apps?

I'm sure there is a solution to the transpiling/bundling, it's just not my current setup. Ideally I just want my patterns in PatternLab to be as easy to implement as possible outside of PatternLab. I know my own setup isn't universal, but I'd think we'd want to avoid building PatternLab specific architecture that doesn't translate to outside use since no one is using PatternLab just for its own sake.

[bradfrost]

Great conversation here, thanks!

I think there's a lot of flexibility needed here to set things up the way different teams operate.

Some spitball thoughts here:

Perhaps a smart default would be for the code tabs to automatically display files that are bundled with a pattern. So this:

accordion.mustache
accordion.scss
accordion.js
accordion.md

Would end up displaying tabs like so: Mustache | HTML | SCSS | JS

BUT! Architecturally it may not make sense for teams to cluster things like this. In my own projects, I have separate css/scss and js directories where SCSS and JS are defined. In that case, we may want to add config options to define the paths to those directories. The patternlab-config.json file in PL Node already defines paths.source.css and paths.source.js, so we may be able to piggyback off of that and/or define others like paths.source.scss, which could look something like this:

"paths": {
  "source": {
    "scss" : "./source/css/scss/components/"
  }

If a file name matches the pattern filename in those config directories, those tabs would appear alongside the pattern. So if we're looking at accordion.mustache, if there's a file called accordion.scss in '/source/css/scss/components/', the SCSS would appear as a code tab.

Lastly, if none of these are defined, or if custom paths are required, we could follow the conventions @davejtoews outlined above, so:

files:
  - type: SCSS
    path: /custom/css/path/scss/accordion.scss
  - type: Javascript
    path: /custom/css/path/js/example.js

I like the ideas of having defaults to automagically pull in files, but still give people the option to override those. Thoughts? /cc @bmuenzenmeyer @EvanLovely

[EvanLovely]

I'd like to see the config happening for files in the pattern meta file (pattern.md). I also like the idea of having the same name files automatically become tabs (pattern.scss or _pattern.scss).

[sghoweri]

Just a couple thoughts I wanted to add to the mix:

1. I 100% agree on defaulting to the pattern name itself as the starting point. Unless otherwise specified or configured (more on that in a minute), assume that X pattern is always Y file with the same base file name.

Ex. https://github.com/bolt-design-system/bolt/tree/develop/src/_patterns/02-components/bolt-image/src

image.js
image.json
image.scss
image.twig

2. I also 100% agree on the additional need(s) to "help clarify" all the different associations (or even correct potential mismatches) Pattern Lab might try to make when mapping up a pattern to an associated asset / file / resource etc goes by another name.

This second piece probably being the most important in my opinion given a lot of the hands on observations (and brick walls) we've been discovering getting our Design System up and running.

3. (Controversial?) With that said, I really really hate the idea of only allowing this second manual config approach to be done at the global level.

Yes, perhaps this would be more than enough for some projects / use cases of Pattern Lab, but when trying to have PL power your entire multi-site Design System, flexibility and encapsulation in how things can get configured makes a world of difference.

I do agree with @EvanLovely's comment about using the frontmatter data in a pattern to set this config however there's other instances such as the one we have where even the markdown file itself won't automatically get picked up by Pattern Lab because we're naming each component's markdown file README.md to reduce duplicate / redundant files + support publishing these packages out to NPM for mass consumption:

https://github.com/bolt-design-system/bolt/tree/develop/src/_patterns/02-components/bolt-ordered-list

This is precisely why I think either allowing for a secondary (alt) config via a component's package.json file could make sense... or perhaps we take a page out of Babel, Stylelint or ESLint and support a .patternlabrc config -- either globally at the top level and/or at the pattern specific level.

Thoughts?