Hello Brooklyners, and welcome into this new decade! (i.e. Happy New Year!)
To start off nicely, I would like to make a proposal regarding the Brooklyn website/doc. *Background* Currently, we have 2 separate projects in `brooklyn-docs`: - the docs are using `gitbooks` and sources live in the `master` branch. - the rest of the website is using an ancient version `Jekyll` and sources live in the `website` branch. We did this because: 1. the ancient version of Jekyll requires a very specific version of ruby which is a pain to setup locally and on the CI. Meaning it was virtually impossible to contribute the docs alone. 2. if there is a change in the docs, it didn't make sense to update the website part and vice-versa. 3. we wanted to automatically publish the changes live as soon as PRs were merged. *Issue* The problem with this approach is that we need to have 2 CI jobs to build 2 different parts and to somehow push these live. We never managed to automatically publish updates to website/docs through Jenkins. We also picked a tool that is unfortunately not maintained anymore (gitbooks) as their team is pushing for a commercial offering. Our Jekyll setup is very old and impossible to upgrade currently, as it's using custom plugins that would need to be rewritten. And finally, our setup is, in my view, way too complicated and clunky to use. *Proposal* I took a look at different solutions and found one that seemed to tick all the boxes, it's called vuepress [1] and let us to: - reconciled the website and docs under the same branch as it supports multiple layouts, hence build both in one go. - have a custom navigation, based on whatever configuration we write. - defined custom blocks that can use hardcoded HTML or vue templates (we do have custom blocks for the blueprint tours, tips, alerts, etc...) - have custom search like gitbooks + be responsive and SEO friendly. - have a toolchain that is maintained, open source and easy to use. On top of that, having the full website build in one go will enable us to push, from Jenkins, the compiled files to another branch (like `asf-pages`) and leverage a new service called `.asf.yaml` [2] which takes care of publishing it. WDYT? Best. [1] https://vuepress.vuejs.org/ <https://vuepress.vuejs.org/guide/#how-it-works> [2] https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=127405038#id-.asf.yamlfeaturesforgitrepositories-WebSiteDeploymentServiceforGitRepositories -- Thomas Bouron Senior Software Engineer *Cloudsoft <https://cloudsoft.io/> *| Bringing Business to the Cloud GitHub: https://github.com/tbouron Twitter: https://twitter.com/eltibouron
