Hi Thomas, Agree with a lot of what you say - we've made some decisions that in hindsight were bad ones that are now causing pain (even though they were the correct decisions at the time - back when Brooklyn first started, before Apache, Jekyll was just about the only static site generator with a lot of traction).
I've a couple of points to make: In your description about why website is on a separate branch, you've omitted that website and docs have big differences in their lifecycles. There's always only one branch of the website, but there's multiple versions of the documentation. Mixing website and docs has the problem of making multiple versions of the website. Only one branch will contain the "real" website and all others will necessarily be out-of-date copies. For that reason I'd prefer that the website and the docs are kept in distinct branches. I don't have any particular view on which static site generator is best other than to say I'm wary of fast-moving targets. Jekyll and Ruby bit us like that - you have to keep your content and infrastructure up-to-date - stand still for too long and suddenly it's a pain building your tooling and a hefty job to upgrade. I'm very wary of the Node.js, Yarn, NPM ecosystem for that reason and I wouldn't want us to be in a similar position to now a year or two down the line. I'd be happier with a generator written in Go as it usually has simpler distributions and setup (native static-linked binaries) that have a longer shelf-life. Richard. On Tue, 7 Jan 2020 at 09:58, Thomas Bouron <[email protected]> wrote: > 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 >
