Allow a custom template for the examples section

[ronaldlokers]

I would like to be able to assign another template to a specific section.

So for example I have a file which defines the fonts my project has, I would like to have a separate template for this section to only show the fonts and not any code that can be copy/pasted. But the rest of the project would have the default template which has a example of the markup in it.

[JohnAlbin]

If you use kss-node --init mycustomtemplate, it will create a clone of the default template. You can then edit the index.html file to add {{unlessReference myfontsection}} around the code sample part of the template.

[matthewferry]

Using {{unlessReference mysection}} is fine if you only have a couple of templates that require modification, but if you have more than a few sections that have special needs, the resulting logic in the base template gets kinda unwieldy. It would be interesting if you could, in the markup section of your CSS add a "wrapper" of html that the entire section would be injected into before looping over the modifiers. This would help for special cases where one section may need additional html, like a different bg color for showing inverted text or context-specific components.

Something like:

// Buttons
// 
// Markup:
// <button class="btn {{modifier_class}}">Button</button>
// 
// Wrapper:
// <div class="bg--contrasted">
//   {{markup}}
// </div>
//
// .btn--inverted - inverted button
//
// Styleguide - Buttons

[JohnAlbin]

So for example I have a file which defines the fonts my project has, I would like to have a separate template for this section to only show the fonts and not any code that can be copy/pasted. But the rest of the project would have the default template which has a example of the markup in it.

Hmm… I actually do something similar with my Sass color variables.

[JohnAlbin]

Okay, I ran into this problem again yesterday. And now I know how to fix it properly.

Currently, kss-node reads the markup file specified in the markup property // Markup: template.twig and then uses it in 2 places:

1. Renders the default style and the modifier styles under the "Examples" heading
2. Shows the HTML in a code block below the examples

It would be nice if we kss-node would look for an alternate file to use if it exists next to the file specified in the markup: property.

If a kss-example-[markup filename] file exists, then it should use that markup file instead of the default one for option 1 above (rendering the markup for examples).

So if the KSS comment has // markup: messages.twig, the style guide will show that as the example code, but if a kss-example-messages.twig file exists next to messages.twig, it will render that file instead of messages.twig in the examples.

These would fix 2 different use cases:

1. "I always need to render this component inside a specific container." You put the specific wrapper markup in the kss-example-* file and then use Handlebars {{ > "template.hbs" }} or Twig {% include/extend/embed %} to include the component markup.
2. "The markup file has logic triggered by different variable values and I'd like to show how the resulting HTML for all logical inputs."

[jonespen]

Does this work with markup from .html files? I couldn't find a way to render the markup, only the kss-example-*.html was rendered