I think we should at least consider "making good" the existing system which, although it has some technical warts, I think does much of what we need. What are the issues it has?
I am dubious that any radical overhaul will give us a perfect solution. Some of the issues are quite hard, eg menu order, nice PDF, and there's a big chance we'd spend a lot more effort in one of the new shiny systems bending it to our needs and end up with something just as jury-rigged. Better the devil you know... FWIW the biggest issues IMO are: * for the examples, import source code that is actually used in tests (!!!) * check links * think through user flow None of these would be addressed by an overhaul. (And fwiw getting jekyll to import source code nicely was painful, that pain may likely still be there!) Best Alex On 5 October 2017 at 11:23, Thomas Bouron <thomas.bou...@cloudsoftcorp.com> wrote: > 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/dae4468aa7ef77af9dc8aca24b8434 > e9782efbd50fa876618cccf980@%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 >
