Ambiguous files option and watchers

[maiertech]

I tested this plugin earlier today and I would like to point out a few observations. My initial setup was metalsmith-watcher plus metalsmith-serve. My goal was to replace metalsmith-serve with metalsmith-browser-sync to benefit from BrowserSync's auto reload/inject features.

The first point where I stumbled was the files option. I assumed from the documentation that this was BrowserSync's files option. Then I was wondering why the default config watches Markdown files. I thought it should rather watch the build directory, while metalsmith-watcher would take care of the Metalsmith builds. But then I ran into endless BrowserSync reloads and then noticed two things in the source code:

1. files indicated the files that should trigger a Metalsmith rebuild upon change. It is not BrowserSync's files In the source code files is explicitly removed from the options before handing them over to BrowserSync. That's not really intuitive.
2. The next thing is the fact that under the hood this plugin uses BrowserSync to set up some watchers. This should be mentioned in the documentation. I expected this plugin to fire up BrowserSync only with no watchers.

The question is whether or not one should use Browsersync's watchers or leave the watching part to something else like Gulp or in my case metalsmith-watchers. This goes beyond this plugin, of course. The downside if this plugin's implementation is that simple BrowserSync watchers always trigger a full Metalsmith rebuild and reload, even if that's not necessary. metalsmith-watcher can do partial rebuilds.

That's why for me it feels like the watching part should be separate from the preview server part. And this would mean that metalsmith-browser-sync should just look at the build directory and reload when there is a change and another plugin should take care of the watching part and triggering (partial) rebuilds when source files change.