Hello, I have had a talk with Volkan over the topic and felt that I did not explain my cause very well. I would like to try again.
On Tue, Sep 26, 2023, at 23:23, Matt Sicker wrote: > Infra supports publishing any sort of site output as long as it’s > published via committing to either subversion or git. For git, this is > via the normal asf-site and asf-staging branches similar to ghpages > branches on GitHub. Since we can set up GitHub Actions to commit to > those branches, we can support any static site generator that can be > invoked from an Action. Yes it is possible, but it is not as easy as this: https://github.com/apache/privacy-website/blob/main/.asf.yaml > > Given Volkan’s argument around JBake, I agree that it would be the > easiest thing to use. Site generators based on Python or Ruby tend to > ossify around a bunch of random dependencies thanks to the clusterfuck > that is Python and Ruby package management which is somehow only > slightly less bad than the C and C++ ecosystem. Honestly, I have been using Jekyll for many years and I have never had any problems. If you don't want to mess up your system, I have made a Docker file. So you are safe and don't have to deal with any package management. You can also install Jekyll as a binary and that works extraordinary well. No package management needed In that case, you would to have to run: jekyll s You don't need Docker, just install it using brew (or whatever). > > Also agreed on AsciiDoc; Volkan’s reasoning here is exactly why I > migrated various documentation to AsciiDoc here in the past. Jekyll supports AsciiDoc as well, using this plugin: https://github.com/asciidoctor/jekyll-asciidoc JBake is a limited system to me and definitely not the easiest solution. It does not support SCSS and also does not support Data files. https://jekyllrb.com/docs/datafiles/ Jekyll is the standard for Github pages and has proven to be very stable. It has a big community and is operated by blogs all over the world. It has a very specific way of doing things and is pretty much a no-brainer for developing. For me, JBake's only benefit is you run it using Maven. It will cost me a lot more time to update it so it is doing the job. And in some cases, as SCSS it just doesn't work, so I have to use old-school CSS for layout changes. Also, we only have 1 single page that uses AsciiDoc. This page is the team page. This page should actually not be maintained as AsciiDoc table, but it should be a data file and generate nice HTML. I am surprised that there is such strong support for JBake, for this always was a niche tool (and still is). That said, I want to achieve one goal quickly: I would like to see the news/blog section in a format that is nice to make those announcements, including publishing the deprecation plan. Since I seem to be the only person currently driving this forward, I still would like to have the PMCs blessing to move to Jekyll. If you are still not OK after what I did, we can roll back to JBake and spend the extra hours rebuilding. Please let me know if any of you is actually a -1, then I save the effort. However, I would be very unhappy to spend more time than anticipated working on JBake. Kind regards, Christian > — > Matt Sicker > >> On Sep 25, 2023, at 04:20, Volkan Yazıcı <vol...@yazi.ci> wrote: >> >> 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 >>>
