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
>>>

Reply via email to