Refactor Readme.md

[Confectrician]

Since the docs are generated with vuepress in the future and we are changing the repo structure in #665, we have to adapt the readme file too.

I would wait for the ne generation and resctructuring process to be finished, until we refactor that.
We already could remove the jekyll related stuff to prevent some confusion.

Wdyt?

[ghys]

Agreed.
What would be very cool at some point in the future when #700 and #665 are in place is to add a VuePress config in the master branch, with only the documentation but in the style of the website, and configure Netlify to build preview deploys.
This way instead of requiring users to set up an environment to preview, they could see the results directly with a link from the PR page. The reviews would be far easier too - broken links and images would be immediately visible.

[Confectrician]

and configure Netlify to build preview deploys.

I have seen that in the website repo and loved it, wanted to ask you about it anyway. :)

[Confectrician]

What about versioning? See: https://github.com/openhab/openhab-docs#documentation-versioning

I have recently added a 2.3-patch branch from the tag commit.
Can we reuse those branches for versioned docs, or do you generate own vuepress vontents while building?
I still haven't had time to follow the process there.

[ghys]

Currently it uses tags only to generate the stable release's websites.
The need to document this process is tracked here: openhab/website#72

[Confectrician]

Currently it uses tags only to generate the stable release's websites.

Question would be, how important it could be to adapt the docs for version 2.X after tagging.
If it never gets used, we should ask ourselfs if we need an "archive-branch" for those versioned states.

[ghys]

You can always make a release branch and re-tag its head if you happen to add commits to it (this should be quite rare). Also actually when the websuite build script clones this repo for a specific release it uses e.g.
git clone --branch 2.3.0 ...
which will clone the branch or tag named 2.3.0 (docs here) so if you want to use branches instead of tags that's up to you :)

[Confectrician]

so if you want

I have no preferences, it's just the situation that is currently existing in the repo. :)