AsciiDoc offers syntax for most of the things that Markdown requires you to use raw HTML for. Also, the default output format for AsciiDoc looks a lot nicer than Markdown, but that’s always customizable.
> On Sep 28, 2023, at 10:35 AM, Ralph Goers <ralph.go...@dslextreme.com> wrote: > > 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 >>>> >> >
