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.
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. Also agreed on AsciiDoc; Volkan’s reasoning here is exactly why I migrated various documentation to AsciiDoc here in the past. When we first used XDoc, this was an annoying mix of XML and XHTML where our files typically didn’t even validate under the referenced XSDs. I had initially migrated those files to Markdown, but I had to use HTML occasionally. AsciiDoc was the first markup format that didn’t require these escape valves, and they theoretically support template variables, too, so there’s no need to run them through a preprocessor. — 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 >>
