Should I be able to see fully rendered components?

[chrisfromredfin]

I have the following code.

// Import Herman utilities so we can access the various and sundry utilities.
@import "node_modules/sassdoc-theme-herman/scss/utilities";

// Import utility functions that don't generate output.
@import "util";

/// @group components
/// @name button
/// @example scss
///   .button {
///     @extend %button;
///   }
/// @example html
///   <a href="#" class="button">Click me!</a>
.button {
  @extend %button;
  background-color: blue;
}


// A final export of anything for sass-json.
@include herman-export;

My "util" partial contains the extend (and various other no-actual-css-generating code). Everything appears to be working.

My question is, should I expect that the rendered example of markup would contain the styles - that is, I should actually see it as a green and white rounded-corner button? Or am I to only expect basic rendered HTML with user agent styles?

#45 seems to imply this is possible (based on screenshot, unless those circles are images?).

#153 seems to imply this is maybe being worked on (open issue). Or maybe this is just for some additional custom CSS?

I've tried @example html and @example njk - but without a real template for the njk. Is this an example where I would include a link to the CSS in my own nunjucks template? If so, is there a way to use Herman's default templates and merge in just my own, or should I copy all the templates from node_modules to my own folder? Right now I'm using Herman's template path:

nunjucks:
  templatepath: "node_modules/sassdoc-theme-herman/templates"

Y'all have been extremely helpful, and I'm thankful. :)

[mirisuzanne]

It both exists, and is being worked on. :)

For the current functionality, check out the customCSS option - for passing a CSS file into all examples. In your case, it looks like that should do what you need.

What we don't have yet, is a way to create linked CSS & HTML examples - that would allow you to add example-specific CSS to what is rendered, without adding it to your main CSS output. Does that make sense? It's a bit more of an edge case, but we run into it on occasion, and plan to make it possible.

[chrisfromredfin]

Blerg, totally forgot about customCSS, but yes, that should be perfect in my case! Thanks again (as always!)

I also absolutely see the use case for option 2, but agree that it's a bit more edge-casey. But I see the utility in it.

[jgerigmeyer]

It's worth noting that the nunjucks.templatepath setting is only required if you want to use @example njk annotations, where you're showing some Nunjucks/Jinja2 markup that may {{ include "..." }} another Nunjucks/Jinja2 file. You don't need to point it toward the Herman-specific templates -- they are self-contained and should be safe to ignore entirely.