[Enhancement] Documentation

[Diegovsky]

Since unfortunately it is not possible to keep evil-helix marked as a fork, it is hard to diff both repositories to compare changes.

I would love to help document how evil-helix is different from helix, which keybinds it has by default, how to setup the modeline, etc.

Would you give me some pointers/quick summaries? I'm hoping to improve book/ with this documentation, and hopefully host it in GH-Pages.

[usagi-flow]

Hi @Diegovsky, thank you very much for offering your help (much appreciated!) and sorry for replying just now. Truth be told, when you posted this issue, I wasn't exactly certain of how I wanted to proceed with the documentation and with a website in general.

But in the meanwhile, I've been thinking about it, and I'm starting to get a better idea of what I believe would be a great solution. I'll put a tl;dr: down below. :)

The most important part is the ability to use/re-use upstream documentation without running into countless conflicts when merging upstream changes. Therefore just blindly changing content under book/ will probably be a no-go in most situations (unless we're fixing the content and planning on submitting the fix upstream).

To implement a solution, I created a GH Pages repository, evil-helix/evil-helix.github.io, which deploys to evil-helix.github.io.

The GH Pages repository will at least host the non-documentation part of the website (which I expect to be a static site with some links, images, and with a link to the docs, of course).

Now regarding the actual evil-helix-specific docs, I'm thinking about creating another directory, e.g. evil-book/ or maybe a subdirectory under book/. Either way, I'm expecting to stick to the same tooling (mdBook).

Finally, I'm considering having the upstream and evil docs combined in such a way that the evil docs would be a "layer" over the upstream docs; i.e. if upstream says A and evil says B, then the website shows B.
This would be an ideal situation, I believe, but I have yet to find a decent solution to do so, without hacking a complex github workflow (suggestions are very welcome!).

---

tl;dr: Since we shouldn't blindly modify upstream code under book/, I'm considering separating evil-helix docs. The docs, together with the rest of the site, will be built by the evil-helix/evil-helix.github.io repository.

[Diegovsky]

Hey @usagi-flow, thank you very much for not only sharing my concerns but also for giving it a lot of thought! It is completely fine to not answer is straight away, I'm sure we're all busy with life.

I think you're right: since evil-helix is a fork which mainly adds stuff, it wouldn't make much sense to fork the whole docs. I would be way better instead to write our own docs that focus on contrasting the changes instead.We could even have some metadata (if you were to choose mdbook or some other markdown-based static site generator) that links an evil page with the helix page, that way both helix's docs and our docs are easily accessible within a couple of clicks.

As to how to achieve that, I'm not sure. I like simple and pragmatic solutions, so simply linking to the corresponding/relevant helix docs would suffice for me. As in "to know about more available functionality, check out helix's page: '".

If mdbook ends up not being chosen, I have experience with zola, and its I18n support is very nice, alongside nice features such as page search.