[RFC] Add static guides site generator

[tvdeyen]

Add a static guides site generator

We have so many great guides written by @benjaminwil (Thanks Buddy!).

Although it is possible to read the guides in the GitHub interface, I think it's time now to add a static site generator that makes it possible to read the guides in a nicer way.

Why VuePress?

I chose VuePress as static site generator, because it is build solely for the purpose of serving technical docs, fast and feature rich:

1. Build in search
2. Easy customizable default theme or build your own theme
3. "Edit this page" links for easy contribution to guides
4. Easily deployable to GitHub pages
5. Run locally for writing guides is very easy

The best thing is that it's served as static site and then turned into a SPA powered by Vue.js

How to run this locally

cd guides 
yarn install
yarn run vuepress dev .

That's it \o/

Demo

https://tvdeyen.github.io/solidus/

Some screenshots

[peterberkenbosch]

This is awesome!

[peterberkenbosch]

[tvdeyen]

@peterberkenbosch Bedankt, Peter! I added an online demo https://tvdeyen.github.io/solidus/

[peterberkenbosch]

Nice @tvdeyen! Static sites are sooooo fast too

[kennyadsl]

Just left a comment to keep the root of the project untouched and avoid confusion. I'm pro everything that improve the current documentation status. IMO when we'll have something better we could change this, that is better than having nothing.

Thanks!

[kennyadsl]

what about moving this into /guide? I just don't want to confuse devs that see this package.json in the root and maybe expect to be able to build something useful for solidus development? I think that the yarn commands can be run into that folder directly as well, right?

[tvdeyen]

This was my first take, but something led me to move this into the root folder. I will try again, because I agree that this should not be in the root folder.

[tvdeyen]

@kennyadsl made the requested changes. Working like charm 👍

Also updated the styles to the new colors and fonts from the shiny new marketing site.

[tvdeyen]

Extracted the fixes for guide files into #2709

[kennyadsl]

What about also updating the description of this PR with instructions?

It should be:

cd guides 
yarn install
yarn run vuepress dev .

[tvdeyen]

@kennyadsl thanks, updated

[tvdeyen]

The stembolt folks were working on a new guides site as well, while working on the shiny new website. I will close this in favor of the other PR coming up soon. Thanks for all the great feedback. We think about migrating the soon-to-be released guides site to VuePress as well.