Hi all. It's been a couple of weeks that I started to look at how to improve and simplify the Brookyln website[1]. As I said on the Brooklyn 1.0 thread[2], I think we need to sort this out before releasing 1.0.
I have looked for a framework / library to handle both the website and documentation the same way we do it right now. To determine what was the best fit, I based my analysis on the following criteria: - Able to take markdown files and generate HTML from them. - Keep the folder structure intact (currently, pages that seems in the same logical group - take pages in the download section[3] menu - jump into a different folder/category/section which is very confusing) - Be skinnable - Able to handle versions for documentation. - Able to generate PDF version of documentation. - Be as "stock" as possible to limit maintenance and pain during upgrade (our current website still uses Jekyll 2.x). 2 contenders clearly jumped out from this: - Jekyll[4] - Gitbook[5] ---- Jekyll With the version 3, Jekyll now has a concept of collections[6] which can generate pages from markdown files and keep the folder structure. The menu can be generated based on this folder structure (with depth limitation for example) in combination of some clever liquid tags and `include`. However, it will be hard to control the order of items appearing on the menu. Another easy solution would be maintain list of links for the menu to be generated. There are plugins to generate PDF[7], which happens during compile time. Finally, Jekyll is highly skinnable with built-in or custom themes. ---- Gitbook Gitbook, in its open source version, handles out of the box doc versioning, PDF generation at runtime (so it seems) HTML pages generation from markdown. The menu is built-in feature, based on a simple markdown list of links[8]. This means we need to maintain it but there is a good chance we will have to do this with Jekyll as well. Finally, Gitbook is also easily skinnable[9]. ---- Both frameworks offer mostly the same features. However, Jekyll is easier to build a website that looks like a "corporate" one whereas with Gitbook, you are "stuck" with the design principals it was created, i.e. serve documentation only. But for this very purpose, it is extremely good and easy. Our website is the combination of both a "corporate website" (i.e. about, getting started, community, etc - few pages that describe the project) and a documentation. Which leads me to my proposal: separate the website from the documentation, at least in terms of how we build it. What I mean by this is: - Use Jekyll (or even nothing) for the website, except the documentation part. This will let us build a nice theme (based on Bootstrap 4 for example) without to worry about complicated plugins and custom code for the documentation. - Use Gitbook for the documentation alone, applying/adapting the theme we will create from the point above. Best. [1] https://brooklyn.apache.org/ [2] https://lists.apache.org/thread.html/dae4468aa7ef77af9dc8aca24b8434e9782efbd50fa876618cccf980@%3Cdev.brooklyn.apache.org%3E [3] https://brooklyn.apache.org/download/index.html [4] https://jekyllrb.com/ [5] https://github.com/GitbookIO/gitbook [6] https://jekyllrb.com/docs/collections/ [7] http://abemedia.co.uk/jekyll-pdf/ [8] https://toolchain.gitbook.com/pages.html [9] https://toolchain.gitbook.com/themes/ -- Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation • https://cloudsoft.io/ Github: https://github.com/tbouron Twitter: https://twitter.com/eltibouron
