Formally declare markdown with yaml as Pattern Meta (patternMeta)

[EvanLovely]

Each *.md has been consider "Documentation" and appears in various ways to tell more about the pattern. Originally, changing the file name of the pattern informed pattern lab about it: _pattern.twig to hide it, -pattern.twig to only show in menu, [email protected] to show state. Those all are less than ideal as not only are they cryptic and limited, but systems outside of Pattern Lab that don't understand the Pattern Lab Partial Syntax get thrown off by files constantly having to be renamed. Here is what I'm proposing for being able to go into a Pattern Meta markdown file:

---
title: My title 
state: inprogress
hidden: true
noviewall: true
order: 5
tags:
  - products
  - teasers
annotations:
  - 
    title: Masthead
    element: .c-header
    annotation: The main header of the site doesn't take up too much screen real estate in order to keep the focus on the core content. It's using a linear CSS gradient instead of a background image to give greater design flexibility and reduce HTTP requests. 
links:
  - 
    label: Demo
    url: "#"
  - 
    label: Article
    url: "#"
  - 
    label: Source
    url: "#"
---
My *super* cool markdown description...

OK, there's a lot there, let's break it down:

• title - Overrides pattern name derived from file name.
  • Already implemented in PHP & Node
• state - Sets state. Replaces appending @inprogress to filename.
  • Was how Node version did it already
  • PHP version updated to this method this week at v2.8.4.
• hidden - Hides pattern everywhere aka prepending _ to filename.
  • Implemented in PHP version this week at v2.8.4
• noviewall - Hides pattern from View All lists, but keeps in menu aka prepending - to filename.
  • Added this week in PHP at v2.8.4
• order - Order of pattern, would replace prepending filename by 05-.
  • Not done in PHP (issue here)
• tags - Arbitrary tags for whatever the future may hold.
• annotations - Discussed very recently over in Move annotations to markdown file #33
• links - Collection of links - useful as they would all require target="_blank" or target="_parent" to work correctly in the <iframe> and covers all sorts of Jira ticket, documentation, or inspiration article scenarios one would want.

Again, a lot there, but I wanted to summarize the best I could. I'm down to narrow that down a bit or whatever, but I think it's a good idea to say: "this is where we keep information about the pattern itself". Since everything *.yml / *.json is all about data passed to the pattern, I think it'd be best to do it this way.

Additionally, I think that we should create a JSON Schema that defines this data model that both PHP & Node could pull into validate.

I know a lot of discussion has gone on around this already, but I've done my best to aggregate it all. I'd love to see this in the PL Docs as "Pattern Meta" and under the hood in PHP/Node as patternMeta with the same structure.

Thoughts? Am I missing anything?

Related Issues

• Implement better ordering patternlab-php-core#138
• Move annotations to markdown file #33
• Discussion and Vote: Pattern State Declaration, and other Pattern Metadata #16
• Discussion & Vote: Pattern Type Documentation #28

Related code blocks

• Node passing data from MD files - pattern_assembler.js

---

/cc @pattern-lab/voting-members

[bradfrost]

Fantastic, @EvanLovely! This is a great round-up of a lot of the discussion we've been having.

I've created a gist for the IA for a pattern contained in a style guide. Being that we're marching towards having PL serve as a storefront as well as a workshop, I think it's important to be thinking/talking about them now, even if they aren't current or near-future features.

shortDescription: 
usage: |
  Long, arbitrary block of formatted text describing how to properly implement pattern.
version: 1.3
codeDocumentation:
  - 
    selector: c-btn
    description: description of code

@EvanLovely, I'm not sure what links is; are those links to resources? If so, we might want to consider changing that label to be a bit more descriptive.

None of these attributes need to be baked in or required, but broadly speaking, @bmuenzenmeyer and I discussed there should be an [extra] area that allows people to define their own meta info. By default, we could loop through and print out all these custom key-value pairs after the pattern description, and others could customize the PL UI to display that data in a way that works for them.

I have to give a workshop now, but I'll hop on later. Thanks again for putting this together!

[bmuenzenmeyer]

wow, a lot to unpack here

I think a lot of this was already covered in #16 but a round up of issues doesn't hurt.

I've updated my PL Node tracking issue of this spec discussion: pattern-lab/patternlab-node#376

Also, as you can see by the gist below, tags and links are currently being shoved into extraOutput and should probably be first-class citizens if we plan to do something with them - as we don't want users misappropriating their use.

https://gist.github.com/bmuenzenmeyer/fb51a07a5089422ee0b1aa036714b996

@EvanLovely, I'm not sure what links is; are those links to resources? If so, we might want to consider changing that label to be a bit more descriptive.

I like it being called links. Leaves it open to many uses. Jira link, link to sketch file, link to supporting document somewhere else, link as mailto: prefilled with the name of the pattern for feedback.

@bmuenzenmeyer and I discussed there should be an [extra] area that allows people to define their own meta info

as of right now this is extraOuput, but I am open to change. It doesn't surface on the UI, only in the data we expose about each pattern.

---

As a small housekeeping note, I have found success in creating tracking issues like pattern-lab/patternlab-node#713 to display the status of an individual spec enhancement, which links back to the spec discussion. This avoids the big tracking spec issue and epic that I linked above and makes contribution simpler.