goals for refactor

[jonschlinkert]

• faster
• take advantage of es6 classes and inheritance
• simplify logic for caching views (renameKey, etc)
• built-in support for permalinks
• built-in support for pagination

[mootari]

This might be considered blasphemy, but I would also revisit the current practice of automatically adding singular/plural collection shorthands to the parent object, because:

• Logic for derived singular forms may not work in all cases, probably hard to debug when it happens.
• Easy to run into conflicts with existing properties if wrong name is chosen.
• Application instance is already pretty crowded due to multiple inheritance and mixins.

If I may be so bold as to offer a suggestion: expose collection shorthands through a dedicated property. While this would require marginally more typing, it would take a lot of the black magic when using Templates through additional layers, like e.g. in Assemble.

[mootari]

I just realized my request doesn't exactly fall under "refactoring". Should I move it into a separate issue?

[jonschlinkert]

I just realized my request doesn't exactly fall under "refactoring". Should I move it into a separate issue?

No, I think it definitely fits with this topic, and it's great feedback. Although it does seem like two topics:

1. A suggestion to move collection methods to a different property
2. A suggestion to get rid of inflection handling

Before I dive into those though, if you don't mind sharing this, are there features and things about templates or assemble that you really like? Anything that stands out that we might want to emphasize as we're making improvements or writing docs? What can we do more of, or do better? etc. Even if you wanted to do a list like: "I like X, but not Y".

Of course, I'm sure you're very busy so I have no expectations, but if you have a minute to list things that would be great

[mootari]

As a disclaimer, I'm still bloody new to the Assemble ecosystem, so my opinions are probably ripe with misconceptions and false expectations.

A suggestion to get rid of inflection handling

No, not that. I see the value in being able to directly work with an item returned from the .addView shorthand. In fact, I can see how the current interface as a whole might allow for a good flow once you've internalized it. Getting to that point without hitting your head too many times is a bit tricky though.

From the top of my head, my wishlist:

• Direct access to collections (currently you have to call their shorthands without arguments to get the instance). I wasted some time wondering why certain methods weren't available on e.g. .pages() that should cleary be present on a collection.
• Marrying the per-view on* events with streams. With through2 I can pass a flush handler for when a set of views has been processed. I didn't see how I can do that with the fn(view, next) callback signatures.
• In the assemble domain: The biggest pain point is definitely path handling. Most examples seem to use path.join(__dirname, ...), which becomes less of an option once you split up your tasks into multiple modules. Also tricky for operations that don't use collections (like copying of assets). .copy and .dest already set the .base property to the cwd (I'f I'm not mistaken), so any way to hook into that would already be a huge help.
• In the composer domain: Making the parent (depending) task known to an executing task, and returning the results of all dependencies back to a task. That way tasks could a) change their result depending on wether they're run standalone or as part of a larger build, and b) a task could easily act on multiple collections (or other ... stuff) that get added by other tasks.
• Cleaner events. There's .emit all over the place, and then there are the .on* handlers. I believe exposing more of the underlying events would give more power and also encourage users to use custom events themselves (warning: pure unfounded speculation).

[mootari]

Finally some background on my use case with which I went into assemble:

• Load markdown files, merge existing frontmatter with some metadata from JSON files.
• Fetch and compile release notes from Github.
• Fetch .d.ts definitions from Github, parse them with typedoc, compile the pages with assemble.
• During the build create a shared registry of all pages and their permalinks and metadata so that those can be accessed when resolving links in other pages.
• Provide a global, shared navigation for all pages.
• Move config stuff into config files so that people don't have to bother with the build logic most of the time.
• Bring all of that in a self-explanatory project structure that someone else who doesn't know assemble can understand.
• Keep everything extensible and maintainable, because "big plans".

[jonschlinkert]

great feedback! I'm going offline for a little bit, but I'll spend more time reviewing your bullets when I get back on. Thanks!