Skip to content
This repository

Default plugin config is not overridden with docpad config? #313

Closed
emirotin opened this Issue October 05, 2012 · 6 comments

3 participants

Eugene Mirotin Benjamin Arthur Lupton Bruno Heridet
Eugene Mirotin

I'm probably doing something wrong, but I'm stuck

I've created a simple plugin: https://github.com/emirotin/docpad-plugin-client-jade. It's structure is completely developed after docpad-plugin-sass
Now in my test project (https://github.com/emirotin/zombie) I have:

plugins:
  cjade:
    namespace: 'window.JST'
  sass:
    compass: true

Now, I see that for the sass plugin compass value does properly override plugin's default (false).
But for my own cjade the namespace is still 'JST' as defined in the plugin.

Please help :)

Eugene Mirotin

Gosh, I found it...
It's here https://github.com/bevry/docpad/blob/master/src/lib/plugin-loader.coffee:

@pluginName = pathUtil.basename(@dirPath).replace(/^docpad-plugin-/,'')
config = balUtil.deepExtendPlainObjects({}, @docpad.config.plugins[@pluginName], userConfiguration)

It would be much more logical (as to me) to use the Plugin.prototype.name - otherwise what is it for?

Benjamin Arthur Lupton
Owner

Hey @emirotin thanks for posting this, and nice find.

Firstly I'll explain a bit of background, DocPad Plugins should have the same plugin name in the prototype name, the directory name (e.g. docpad-plugin-pluginName) and the filename pluginName.plugin.coffee|js. Aditionally, plugin names should not contain any symbols (only alphanumeric characters). While some of these conventions are a bit more laxed than others, they should probably be enforced more stricter - as such, I'll add some warnings to DocPad for when this convention is not followed to prevent such issues from getting so far, I'll also update the documentation in the wiki about this too.

Now, it is perfectly valid to say, why not just use the prototype name in that instance, but that would cause some discrepancies between the original value of @pluginName based of the directory convention and the new value based on the prototype name. Ideally, discrepancies should be avoided more often than not.

The alphanumeric only convention came from having many different plugins published with dashes and without dashes, and it was confusing when would a particular plugin use a dash, or not use a dash, so we've gone no dashes and symbols, to make plugin names easier to remember.

Sorry again for having DocPad waste some of your time by making this more clear, and thanks for posting this, it's a good step to making DocPad more aware of such discrepancies and provide the correct warnings.

Eugene Mirotin

Thanks for explanation
Yet the whole thing doesn't 'feel' proper, may be because initially I didn't found any complete tutorial on writing plugins.

I think you should invest some time in docs, because the product itself is great with big potential. But curreтtly it doesn't look mature (to me) mainly because of the docs.

Anyway thanks for DocPad as it's what I wal looking for to migrate from Middleman (ruby) and still be able to use Sass + Compass and be able to trivially write plugins for some custom things I need (like client-side Jade templates).

BTW, may be you'd like taking https://github.com/emirotin/docpad-plugin-client-jade under docpad-extra? I think it's a good opportunity to use the same templates on client and server.

Benjamin Arthur Lupton
Owner

DocPad v6.7.3 (just published) now includes the warnings. Note, you'll want to change client-jade to clientjade or cjade (due to the only alphanumeric convention).

Yeah, documentation is definitely the weakest point of DocPad currently. We've realised this and are working really hard on refreshing it all, and with a proper website etc.

For getting client-jade inside docpad-extra, perhaps not yet, as we're re-evaluating whether or not the docpad-extras repo should be split up into submodules or not. Will keep it in mind though. But be sure to list it on the plugins wiki page

Benjamin Arthur Lupton balupton closed this October 07, 2012
Benjamin Arthur Lupton balupton referenced this issue from a commit October 08, 2012
Benjamin Arthur Lupton v6.7.3. Fix. Improvement
- v6.7.3 October 8, 2012
	- Fixed logging when a fatal error occurs during initialisation
	- We now do warnings when plugins do invalid naming conventions
		- Closes [#313](#313)
		- Help by [Eugene Mirotin](https://github.com/emirotin)
	- We now display the plugin versions in the plugin listing information
		- Help by [ashnur](https://github.com/ashnur)
	- More localization progress
1d9ad2c
Eugene Mirotin

OK, great

Bruno Heridet

Good improvements. Thanks guys.

Here's one official plugin (related) suffering from this small issue :
docpad/extras#26

Benjamin Arthur Lupton balupton referenced this issue from a commit October 08, 2012
Benjamin Arthur Lupton v6.7.3. Fix. Improvement
- v6.7.3 October 8, 2012
	- Fixed logging when a fatal error occurs during initialisation
	- We now do warnings when plugins do invalid naming conventions
		- Closes [#313](#313)
		- Help by [Eugene Mirotin](https://github.com/emirotin)
	- We now display the plugin versions in the plugin listing information
		- Help by [ashnur](https://github.com/ashnur)
	- More localization progress
a6f8fbd
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.