-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve guide on extension development #1202
Comments
Transferring to https://github.com/hexojs/site as that's the source of documentation. |
I do agree the documentation on extension development needs improvement. I initially learned plugin dev mostly by looking through the source code of existing ones and only use the doc for additional clarification. I believe most plugin devs also learned it this way. I'm not saying this approach is ideal though, it would significantly help newcomer by having more thorough examples and step-by-step guides. To clarify on the current doc, the API docs is split into two sections: Core and Extensions. For extension dev, you can start from Extensions section. Most of the time, that section should be sufficient, unless you need to modify specific files. An approach that I use to test extension is that I have a Let's say I want to test In order to use that hexo-uglify that I just downloaded (instead of the npm-published version), I would add/change the package.json in the -"hexo-uglify": "^1.0.0"
+"hexo-uglify": "file:../hexo-uglify" Then I either delete the whole Then I run either Let me know if you need any more help. |
Well, seriously? You don't have to create a hexo instance if you are developing plugins, because the hexo runtime invoked from the CLI will load your script instead. That's merely the very first meaningful sentences of you API document, and it's wrong. At least please add some restriction and provide some context, and avoid making too general statements, otherwise it could be very confusing to new plugins developer.
Some pages of the document is just brusque, like Processor.
Last thing. It's good we have all those API document around, but that's not a "guide" on extension development. Are we supposed to write our extension right in the
node_modules
directory under the hexo root? Or should we put it in some separate directory and refer to it in thepackage.json
of hexo? In the latter case should we addhexo
independencies
? OrdevDependencies
? Or not at all? At least I was expecting some recommendation or pros-and-cons from the official team, not from some personal blogs.I don't think that quality of developmental documentation is consistent with a 28k stars repo. Do you have any plan to improve it?
The text was updated successfully, but these errors were encountered: