docs(configuration): add ignore

[curbengh]

• Others (Update, fix, translation, etc...)

Closes #1095

Related: hexojs/hexo#3797

[SukkaW]

For most users, it is something quite confuse.

For me, I assume include and exclude is used to control what to be included or excluded statically, .nojekyll (as excluded by Hexo's default) as an example. While ignore will exclude files during render process so neither will they be transformed nor be included in the public dir.

[curbengh]

I also find it confusing myself. I see ignore: as a stop-gap workaround for hexojs/hexo#2179

Last time when I tried to add examples to include/exclude, I find it odd that they only apply to source/.

Perhaps, we could drop ignore: and enhance include/exclude to include every folder (instead of just source/), v5 roadmap perhaps?

[SukkaW]

@curbengh

Maybe not.

include / exclude determines whether files should be copied into public dir. For example, .nojekyll should be included although it is a "hidden file". And .nojekyll will neither be rendered nor transformed.

There is also an option, skip_render, which is used do determines a "renderable" files (Maybe a custom 404.html or a JSON file like now.json) should be rendered or not.

[curbengh]

include / exclude determines whether files should be copied into public dir.

ignore: also does that, in addition to ignoring files from watch.

If include/exclude can be enhanced to cover every folder, for example include can be used to include _foo.js in themes/. Currently there's no way to do that (tested with '_foo.js', '**/_foo.js', '**/*/_foo.js').

[SukkaW]

@curbengh An enhanced version of include / exclude requires update current config to source/ prefixed. It is a breaking changes and I agree to add it to Hexo v5 roadmap.

[curbengh]

cc @seaoak, thought you might be interested to our discussion.

[seaoak]

I think this PR will close hexojs/hexo#2855.

For skip_render: option, the explanation in the comment in hexojs/hexo#2855 seems very clear.

For include: and exclude: option, I think @SukkaW 's comment above is very clear.

include / exclude determines whether files should be copied into public dir.

Might I also add, exclude: takes priority over include:.
https://github.com/hexojs/hexo/blob/master/lib/plugins/processor/asset.js#L111-L113
But because depending on this behavior might not be recommended,
no additional explanation will be necessary.

For ignore: option, it is difficult to explain because only this option is for different layer.
I think I will not recommend this option to users who don't know enough about Hexo's implementation.
I think this option should be used as a work-around to avoid performance or system-resource issue.
But I don't have good idea for documentation of this option...(sorry

[SukkaW]

@seaoak
FYI, hexojs/hexo@4eaec8a has ignored node_modules inside themes dir. But when I run hexo clean && hexo g --debug, I can still see node_modules under themes dir have been processed.

[curbengh]

FYI, hexojs/hexo@4eaec8a has ignored node_modules inside themes dir. But when I run hexo clean && hexo g --debug, I can still see node_modules under themes dir have been processed.

My understanding is that hexojs/hexo#3797 + ignore: **/themes/*/node_modules config (currently not default yet) should prevent the folder from being processed and shouldn't show up in debug mode. I'll test it.

Anyway, we're digressing from this PR. I assume everyone here agree ignore: option should be documented, yes? If the commit looks fine, I'll duplicate to other languages.

[SukkaW]

ignore: options works fined. Only hexojs/hexo@4eaec8a is not works as it should be.

And I think it is ok to duplicate to other languages.

[curbengh]

Added to other langs.