search

hexojs / site

The website for Hexo. https://hexo.io/
https://hexo.io
MIT License
660 stars 1.29k forks source link

Improve guide on extension development #1202

Open cedric-sun opened 4 years ago

cedric-sun commented 4 years ago

Initialize

First, we have to create a Hexo instance.

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 the package.json of hexo? In the latter case should we add hexo in dependencies? Or devDependencies? 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?

curbengh commented 4 years ago

Transferring to https://github.com/hexojs/site as that's the source of documentation.

curbengh commented 4 years ago

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. Router API is an example where you want to add/modify/delete very specific file, as in more specific than Renderer which only operate on file extension.

An approach that I use to test extension is that I have a develop folder. In that folder, I have a blog-test folder with sample posts and a sample theme (example content).

Let's say I want to test hexo-uglify, I would clone it under develop folder, so now develop folder has "blog-test" and "hexo-uglify".

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 blog-test,

-"hexo-uglify": "^1.0.0"
+"hexo-uglify": "file:../hexo-uglify"

Then I either delete the whole node_modules/ in blog-test or just node_modules/hexo-uglify, I usually go for the former to be safe. I run npm install again. Now develop/blog-test/node_modules/hexo-uglify becomes a symlink of develop/hexo-uglify.

Then I run either hexo generate or hexo server (depending on use case), check the test blog on browser or check the content of public/.

Let me know if you need any more help.