I don’t mind AsciiDoc but I have had a few things I couldn’t format with AsciiDoc. I am not really sure why AsciiDoc is preferred over Markdown. The only problem I have had with Markdown is that some tools don’t support some of the latest features.
Ralph > On Sep 26, 2023, at 2:23 PM, Matt Sicker <m...@musigma.org> 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. > > 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 >>> >
