Great initiative to revamp the Logging Services landing page! Go for it! But don't change JBake and stick to AsciiDoc, please.
*Summary:* 1. JBake is great, reproducible, and familiar 2. "INFRA support" is not a valid argument 3. Markdown is a dead end 4. The future should ideally not be individual websites *JBake is feature-wise on par with alternatives* There are a plethora of static site generators; Jekyll, Pelican, Hugo, JBake, etc. Almost every language ecosystem has its own take on it. But they all boil down to a couple of basic conveniences: - pick a typesetting format of your preference (AsciiDoc, Markdown, etc.) - generate pages with a templating engine of your preference (Velocity, FreeMarker, Handlebars, etc.) - compile it to a bunch of static HTML files Some even include batteries: - built-in plugins (sitemap, tagging/labeling, search, etc.) - preview (so you don't even need an HTTP server of yours) - hot reload (so you don't need to compile it manually every time) JBake excels in all these areas. > docker run --rm -p 4000:4000 --mount type=bind,src=$PWD,dst=/root/build --mount type=volume,dst=/root/build/node_modules -it apache/privacy_apache_org serve --watch --incremental Uh... That hurts. This is how you can achieve the same in JBake: `./mvnw jbake:watch`. *The unspoken killer feature: reproducibility* I have been tinkering with static site generators for more than a decade – I love them. I don't know of your experience, but anything beyond Java sucks a big time when it comes to reproducibility. You cannot run a Ruby application written 10 years ago on a modern operating system. Many Ruby libraries depend on system libraries that either are not shipped with the distro anymore or broke the ABI in the past. I need to use this hand-crafted `Dockerfile` <https://github.com/vy/vy.github.io/blob/source/Dockerfile> running on Ubuntu `14.04` with a particular constellation of Ruby dependencies so that I can install a version of `nanoc` that compiles my website. It is an operational nightmare. But let's talk about Java and JBake: `./mvnw jbake:watch`. This only requires the host to have a decent OS, shell, and JDK. That is all. No more, no less. Docker? Nah. Python? Nah. Some weird OS package? Nah. I can confidently say this command will highly likely run without a single line of change for several decades. Given its historical track record, I don't think any other alternative can beat Java in this area and it is of uttermost importance given how hard it is for the PMC to afford time on the website. *The argument of familiarity* 90% of Logging Services committers are Java developers. That is where our expertise lies in. If you throw at them a `pom.xml` and a bunch of AsciiDoc files in `src/site/asciidoc`, without blinking an eye, they would correctly guess what to do. Moving away from this safe zone to uncharted territories, in particular, without factually justifying the rationale, will simply do more harm than benefit, if there is any at all. *The argument of "INFRA supports Jekyll and Pelican"* What does that support exactly entail? You don't need to compile the site and push changes to a particular branch that INFRA monitors to serve the actual domain? It is a dozen lines of GitHub Actions workflow YAML. I volunteer to do this. ASF INFRA serves projects by providing infrastructural functions that didn't exist... decades ago? Many of its offerings are superseded by far better alternatives in platforms like GitHub, GitLab, etc. *Markdown-vs-AsciiDoc* If you look close (and long?) enough to a Markdown-based document collection, you will notice HTML tags, everywhere. Wait a second? Why did we decide to use Markdown in the first place? To avoid manually typing HTML! Yup. The moment you want to do formatting that is slightly sophisticated (putting a code block under a bullet, annotating source code, admonitions, etc.) Markdown collapses. Hence, people reach out to sprinkle HTML into their Markdown. This makes templating impossible in the long run, since every single hand-written HTML will have its own style, formatting, structure, etc. which totally defeats the purpose of using a unified markup language. Hence, please use a markup language that would suffice the formatting needs of a technical document. Given its rich feature set, wealthy ecosystem, and large community, I doubt if there is an alternative here besides AsciiDoc. *The future of Logging Services websites* In its current state, we have several projects erecting their own websites by tooling of their preferences: Log4cxx uses Doxygen, Log4j Scala API uses `asciidoc-maven-plugin`, Log4j 2 and Log4j Kotlin API uses `maven-site-plugin`, etc. Such a diverse ecosystem requires significant maintenance investment. Maintenance of not just the tooling, but also styling. In my opinion, ideally, projects should simply provide a set of global pages (about, support, etc.) in their `main` branch and version-specific programmer-friendly-formatted (in AsciiDoc!) manuals stored in branches next to the code they document, e.g., `2.x`, `3.x`, etc. That should be the territory where committers deal with their websites. Enabled GitHub Issues for the project? Edit `support.adoc` in the `main` branch. Is there a typo in the "Getting Started" page? Edit `getting-started.adoc` in `2.x` branch, and so on. The rest – converting these into HTML pages, pushing this to a website, generating release notes, adding a search bar, styling the page, syntax highlighting source code, etc. – should be done by a separate "tool" located elsewhere. This will enable the committers to stop worrying about the website and its intricacies once and for all. As a bonus, Logging Services will have a one uniform beautifully-dressed look to the outside world where they can navigate with ease. The good news is, the tooling is there and it is called Antora <https://antora.org/>. Somebody just needs to spearhead this effort and put a handful of strongly-opinionated guys on the same page. 😅 *Saving the day* Do you just want to save the day? Go ahead, JBake and AsciiDoc are a great combo. People will appreciate it. It will certainly be an improvement. Do you want to build the future? You should look beyond a single project and its individual website. On Fri, Sep 22, 2023 at 8:48 PM Christian Grobmeier <grobme...@apache.org> wrote: > Hello, > > the current landing page: > https://logging.apache.org/ > > is done with JBake. We have rather complicated instructions on how to > re-generate the landing page: > > https://cwiki.apache.org/confluence/display/LOGGING/Managing+the+Logging+Services+Web+Sites > > The Infra team recommends Pelican or Jekyll to create these kinds of > pages. I have in-depth knowledge of Jekyll and would like to propose > migrating the current landing page to Jekyll. > > The benefits: > > - autodeploy of our changes > - great support of blogging (I'd like to create one) > - easy handling and supported by Infra > - writing content in Markdown > > I am aware that we have a discussion open on how to do documentation in > the future. I would still like to migrate the page asap and - if deemed > necessary - touch it again later. > > So far, I will leave all design/content intact until migrated, and come > back with additional changes (as the blog) after migration to be discussed > separately. > > If there are no objections, I will start with this move sometime next week. > > Thanks! > Christian > > -- > The Apache Software Foundation > V.P., Data Privacy >
