Document include blocks

[aleclarson]

By the looks of it, pug-parser allows blocks when using include with pug file paths. Please document this phenomenon. 😉

[ForbesLindesay]

The short answer is that imported templates can yield to add in the block, this works just like block in a mixin. It's a slightly odd feature, that I've long been tempted to either deprecate, or attempt to unify with extends/mixin blocks.

[skn3]

I just found yield after 2 years of using pug! Please o please document this!

It makes doing things with separate templates much cleaner!

e.g.:

list.pug

div.list
    each row in vars.rows
        -__vars = vars;vars = row;
        include ./row
            | custom content
        -vars = __vars;

row.pug

    div.row
        input(type='checkbox', value=vars.id)
        yield
        div.menu
            each item in vars.menu
                div !{item.name}

I get the "weirdness" of yield in that there isn't technically a scope for the include, so it seems odd. You can get around that by swizzling your locals into vars and just design your templates to always expect a root object called vars.

It would be pretty cool actually if we could do something like this instead: scope(context1=something1, context2=something2) ./includePathHere.pug

This would act the same as include, but would wrap the include in its own local context. It would then import whatever you provide as the (context1=something1, context2=something2) as the root locals context. This way yield would make more sense and we can still utilise the awesomeness of nesting content in an include from the parent template! We wouldn't have to do swizzling as my example demonstrates either.

So with scope it would look like:

list.pug

div.list
    each row in vars.rows
        scope(vars=row) ./row
            | custom content

row.pug

    div.row
        input(type='checkbox', value=vars.id)
        yield
        div.menu
            each item in vars.menu
                div !{item.name}