search

winstromming / sassdown

Generates styleguides from Markdown comments in CSS, SASS and LESS files using Handlebars
253 stars 22 forks source link

Feature Request: YAML front-matter syntax to extend Page Object #34

Open m5o opened 10 years ago

m5o commented 10 years ago

Sorry for the second feature request in this week. Like to share my thought...

This time, it is a feature I saw on the trulia/hologram styleguide repository. They use YAML front-matter syntax to specify vars or custom metadata.

YAML front matter is quite popular, read more:

Think of this optional section that is placed at the beginning of an documentation block. It is for optional metadata that will be extend the Page Object in some way. Goal is to access this variable section somewhere in the handlebar templates.

In this Example you define metadata for the iframe context in the template.hbs. I would be cool if it's possible to extend the generated iframe with this parameters. 

/*

---
body_class: article
assets:
 - public/styleguide/article_styles.css

---

Alerts
======

Creates an alert box notification using the `.alert-` prefix. The following options are available:

    <div class="alert-success">Success</div> 
    <div class="alert-warning">Warning</div> 
    <div class="alert-error">Error</div>

*/

This then can be parsed with something like this. (I am a handlebar noob) Hope you can guess the wanted result. Want to filter the inclusion of specific assest and define a custom body class attribute.

<html>
    <head>
        <!-- use result.assets if any otherwise global assets -->
        {{> assets ||= result.assets}}'
    </head>
    <body class="{{result.meta.body_class}}">
        {{result}}
    </body>
</html>

What do you think? :]

Greets, m5o

winstromming commented 10 years ago

You may want to investigate Assemble, which does exactly this sort of thing. I don't feel that YAML belongs within the scope of this project, but there is no reason you couldn't accomplish object-specific asset inclusion like this:

/*

Alerts
======

Creates an alert box notification using the `.alert-` prefix.
The following options are available:

    <div class="alert-success">Success</div> 
    <div class="alert-warning">Warning</div> 
    <div class="alert-error">Error</div>
    <link rel="stylesheet" href="public/styleguide/article_styles.css" />

*/
m5o commented 10 years ago

Maybe you misunderstood this. I want to find a way to get control to the generated output.

The case is. If for example, if you fetch the assets via wildcards in Gruntfile.js: But then, how exclude assets except for one (or more) specific files.

sassdown: {
    styleguide: {
        options: {
            assets: [
                'public/css/**/*.min.css',
                'public/js/*.min.js'
            ],
        },
    }
},

I don't want to load all assets here. Only the specific one defined in the front matter section.

But in general what do you think of extending the Page Object in some way? The asset thingy was only a dump example. ;-)

It's about find a smart technique to extend the page object with optional syntax. Could also be something else. I only referenced YAML front matter because it was already used in the styleguide context (by trulia) or in some other popular syntax sugar projects.

winstromming commented 10 years ago

But then, how exclude assets except for one (or more) specific files.

You can use Grunt globbing patterns to exclude files you do not wish to match. For example:

sassdown: {
    styleguide: {
        options: {
            assets: [
                'public/css/**/*.min.css',
                '!public/css/not-this-one.css',
                'public/js/*.min.js'
            ],
        },
    }
},

It's about find a smart technique to extend the page object with optional syntax

I understand that, but what is it you would like to extend it with - that cannot be done using Markdown/HTML? My issue is including another type of syntax to the documentation; the original point was to keep it simple with just Markdown.

m5o commented 10 years ago

hehe.. argh you don't get me yet. :sunny:

I want that sassdown include that assets specified by the wildcard.

Think of a really large site with various different page styles. e.g.

Now you would document for example "Alerts" in the shop Context. So for this case it is necessary not to load all stylesheets for the documented section in the styleguide to display the alerts generated with the public/css/shop.css.

Next document section is Alerts in the Community context...

winstromming commented 10 years ago

No, I'm afraid I don't quite follow?

m5o commented 10 years ago

Use Case: Imagine a really large website, with various CSS-Styles organized in separate stylesheets files (e.g. checkout.css, product.css, shop.css, community.css) Separated because from context to context Modules (e.g. Alerts) had different styles for example in community.css or checkout.css

sassdown: Common setup. Nothing special. Load sassdown.styleguide.options.assets with simple globbing pattern (e.g. public/css/*.css).

Documentation Task: I would document the "Alerts" Module inside the community.css context AND also document "Alerts" inside the checkout.css context. Problem: Sassdown currently load all assets from sassdown.styleguide.options.assets into the iframe. It is not possible to control sassdown output in some smart way.

Goal: Find a smart technique to extend the page object with optional data. Somehow. To get control or change for example asset loading inside the generated iframe. Or add optional attributes (<iframe><body id="foo" class="bar">{{result}}</body></iframe>)

Proactive: I did a research and find tools and the YAML front-matter technique and thought this would be a idea and a possible way to start a discussion.

These examples are only two Use Cases. Think global, think big about optional metadata for the page object that can control / extend the handlebars template.

winstromming commented 10 years ago

I understand. What you want is something like:

#page-foo .alert {
  width: 50%;
}
#page-bar .alert {
  width: 100%;
}

However I don't feel this needs to be appended to a <body id="page-foo">. It adds another layer of abstraction that just isn't necessary. Instead, you could do this:

/*

Alerts
======

Creates an alert box notification using the `.alert-` prefix. The following options are available:

    <div id="page-foo">
        <div class="alert-success">Success</div> 
        <div class="alert-warning">Warning</div> 
        <div class="alert-error">Error</div>
    </div>

*/

Better still, you could modify the CSS to allow for a more modular approach, like so:

@mixin alert($colour){
    color: darken($colour, 50%);
    background: $colour;
    border-radius: 5px;
    margin-bottom: 1em;
    padding: 1em;
    // Allow for page variants
    &.type-foo { width: 50%; }
    &.type-bar { width: 100%; }
}
.alert-success { @include alert(#e2f3c1) }
.alert-warning { @include alert(#fceabe) }
.alert-error   { @include alert(#ffdcdc) }

... and then structure your HTML like so:

<div class="alert-success type-foo">Success</div> 
<div class="alert-warning type-bar">Warning</div>
winstromming commented 10 years ago

But, that said, if you really want to include page-specific markup on the results iframe, you can do that by modifying the existing Handlebars template file (or creating your own!). Nothing stops you doing this; in fact, it would be your best option. Handlebars is meant to be extensible.

m5o commented 10 years ago

Jep now you get me. Thank you for your structure concept. It is one of many ways, as always ;-)

In my project I had large legacy components also strict structure that could not be changed easily. For this project I've found a workaround and modified the handlebar template. This works good. So fine on this side.

One main purpose of this feature request was to share thoughts and pitfalls with sassdown. I really enjoyed building the styleguide with it. On my research I tried some other styleguide concepts and ways. Only wanted to mention these, here inside this repo and start a discussion. Sometimes maintainers didn't know their competitors and other concepts.

These are no negative words, don't get me wrong here :sunny:

winstromming commented 10 years ago

Thank you for your comments and feedback. Sorry for misunderstanding the original question. I have marked this issue under the feature and enhancement labels - it may be something I revisit later in time. If you have other ideas, feel free to let me know :-)