[phillip-kruger]

Every SmallRye project's documentation is now published on this site at /docs/<project>/<version>/, from the project's own repository, as AsciiDoc laid out like the Quarkus guides. Antora leaves the build, and the per-project MkDocs/mike sites are replaced.

Project	Versions	Today's source
GraphQL	latest (3.0.0.Beta8), 2, 1, main	MkDocs
Config	latest (4.0.0), 3, 2, main	MkDocs
Fault Tolerance	latest (7.0.0), 6, 5, main	Antora
Health, JWT	latest, main	Antora
Metrics (archived)	3, 2	Antora
Reactive Messaging	latest (5.0.0-RC1), 4, 3, main	MkDocs
Mutiny	latest (3.3.0), 2, main	MkDocs
Stork	latest (3.0.3), 2, 1, main	MkDocs
Mutiny Zero	latest (1.3.1), 0, main	MkDocs
Mutiny Vert.x bindings	latest (4.0.2), 3, 2, main	MkDocs
Jandex	latest (3.6.0), main	Antora (own site)

The newest release of each older major line is published too, so the old MkDocs sites can go entirely (old addresses redirect, see Cutover).

Each project gets a PR moving its sources to AsciiDoc (smallrye/smallrye-graphql#2732 first). The site does not wait for those PRs: a release whose docs are still MkDocs or Antora is converted on the fly, so all current releases are published as soon as this is merged.

Reviewing: why 2,482 files

Almost all of the diff is documentation copied in from the projects, not code.

Part	Files	Lines added
Code to review: tools/docs/, templates, CSS/JS, workflows, data/docs.yml, README, blog links	47	~5,900
Synced docs: content/docs/ (39 versions of 12 projects) and data/docversions.yml	2,435	~144,000

• What the synced docs are. Each version is a full copy of its pages:
  • 1,182 .adoc pages;
  • 905 Java/Kotlin example sources (only the ones pages include);
  • 309 images, about half of them the generated dark versions.
• The biggest share. Reactive Messaging alone is 1,069 files: four versions of about 290 files each.
• Why it is committed. The site builds from this copy, so the build needs nothing from the projects, and every change to the published docs shows in git history.
• To review only the code, hide content/docs/ and data/docversions.yml in the PR's file filter.
• Keeping the copy up to date. No PRs and no manual steps:
  • every night, Sync project documentation re-syncs each version whose main commit or release tag moved, and commits to develop as the CI GitHub App, which triggers the normal build and deploy;
  • it can also be run by hand for one project or one version;
  • docs changes are reviewed in each project's own PRs, where Check project documentation renders them with this site's tools.

How it works

• Registry. data/docs.yml lists every project with docs: repository, docs path, the versions followed, and the addresses published before. It also drives the /docs/ hub.
• Tools. One Java program run with JBang, tools/docs/Docs.java: Java and JBang are all it needs. Each subcommand was checked byte for byte against the Python scripts it replaced, including the full nightly sync (28 versions of 13 projects).
• Sync. Docs.java sync copies a project's docs from a branch, tag or local checkout into content/docs/<project>/<version>/, and records versions and navigation in data/docversions.yml. It also:
  • copies only the example sources pages include;
  • renders diagram blocks to SVG through Kroki;
  • takes build-generated files from the released jars (Reactive Messaging's connector tables).
• Converters. Docs.java mkdocs2adoc and Docs.java antora2adoc do the one-off conversion of a project, and the on-the-fly one. The MkDocs converter covers the docissimo macros (insert, javadoc, image, attributes), admonitions, tabs, PlantUML and nested pages.
• Workflows
  • Sync project documentation: nightly (main branches, new release tags) and on demand. It commits to develop.
  • Check project documentation: reusable. Project PRs render their docs with this site and fail on a broken include or a page that does not render.
  • Build: Antora and its Kroki services are gone. A step writes redirect pages for the 1,524 old Antora addresses (/docs/<project>/<release>/<page>.html) to the same page in the version replacing them.
• Layout.
  • Sidebar, version picker (pre-move versions as "Older versions…"), on-this-page list.
  • Tabs, and "main"/"archived" notices.
  • Old #_snake_case anchors are mapped to the new Quarkus-style ids.
  • Dark theme: diagrams and drawings show a dark version (Docs.java dark-images, run by the sync): the project's own x.dark.png, or the same hues with lightness inverted and white made transparent. Screenshots and photos keep a light background; roles no-dark/dark-invert override.
• Blog. Posts link to the new addresses. Docs.java rewrite-links checked each page and anchor against the generated site, including sections renamed in later releases.

Preview a project's docs locally (once this is merged)

In the project's checkout:

./mvnw -Pdocs-preview

Then open http://localhost:8080/docs/<project>/main/, for example http://localhost:8080/docs/smallrye-fault-tolerance/main/.

• Save a page or an included example, wait a few seconds, then refresh the page.
• Ctrl+C stops it.

What it does:

• No smallrye.github.io checkout, no paths, no Python: only Java and Maven. The docs-preview profile (added by each project PR) runs jbang docs-preview@smallrye/smallrye.github.io, and installs JBang if needed.
• It finds the project from its checkout, downloads this site's sources from develop once a day, and publishes the project's docs as the main version.
• The first run downloads the site's Maven dependencies, so it takes a few minutes. After that it starts in about 20 seconds.
• Options (where JBang is installed, jbang docs-preview@smallrye/smallrye.github.io --help):
  • --port <port> for another port;
  • --site ../smallrye.github.io to preview against a local checkout of this site, for example to try layout changes.
• Generated tables, such as Reactive Messaging's and Stork's config tables, come from the project's own local build when one exists, otherwise from the latest release.

It only works once this PR is merged, because it runs the tools and the site from develop.

Security

The PR check renders untrusted pull-request content, so:

• sync and converters never follow symbolic links;
• every read stays inside the checkout, and every write inside the target;
• ids, refs and nav entries are validated (nav links must be http(s));
• Asciidoctor's SAFE-mode jail is the site root.

Checked locally

• 792 docs pages render with no errors and no Asciidoctor warnings, apart from Reactive Messaging's own issues:
  • its RabbitMQ pages include examples that don't exist in its repository;
  • one example lacks a tag end marker;
  • 5.0.0-RC1 links to a page it doesn't have.
• 52,017 internal links and images checked: 2 broken, both that Reactive Messaging link.
• All old addresses used by blog posts and the Quarkus guides lead to an existing page.

After merge

• Repo settings: the CI GitHub App (CI_APP_ID/CI_APP_PRIVATE_KEY) is reused by the sync workflow.
• Project PRs: merge them one by one; the nightly sync picks up each AsciiDoc main.
• Cutover: the old MkDocs sites go entirely. On each project's gh-pages, Docs.java gh-pages-redirects turns every page of every old version into a redirect to the same page of its major line here (e.g. /smallrye-graphql/2.8.0/federation/ → /docs/smallrye-graphql/2/federation/, or the version's start page if the page no longer exists). Tried on all seven branches: 12,739 redirect pages, none broken, 85% to the same page. Javadoc (apidocs/) stays as it is. Jandex's old site gets the same treatment.

[phillip-kruger]

Screenshots of each project's documentation before (its MkDocs or Antora site today) and after (the project's AsciiDoc from its PR, rendered by this branch locally), updated for the header and sidebar changes. On smallrye.io the sidebar starts closed (the ☰ button opens it, and it stays open on the next pages for that reader); its groups are folded except the one holding the current page. The project and version picker sit in the header next to the logo, so a start page has no separate title; further down, a start page lists the documentation, from its navigation. Each project PR has more pages, including one with the sidebar open.

Before	After
jandex · smallrye/jandex#733 · old page
smallrye-config · smallrye/smallrye-config#1603 · old page
smallrye-fault-tolerance · smallrye/smallrye-fault-tolerance#1351 · old page
smallrye-graphql · smallrye/smallrye-graphql#2732 · old page
smallrye-health · smallrye/smallrye-health#713 · old page
smallrye-jwt · smallrye/smallrye-jwt#935 · old page
smallrye-mutiny · smallrye/smallrye-mutiny#2220 · old page
smallrye-mutiny-vertx-bindings · smallrye/smallrye-mutiny-vertx-bindings#1475 · old page
smallrye-mutiny-zero · smallrye/smallrye-mutiny-zero#376 · old page
smallrye-reactive-messaging · smallrye/smallrye-reactive-messaging#3577 · old page
smallrye-stork · smallrye/smallrye-stork#1385 · old page
Sidebar open (smallrye-reactive-messaging, nested groups)
Further down the start page: its contents, listed from the navigation
Dark theme (smallrye-reactive-messaging): light paper behind the drawing (before) and its dark version (after)
Dark theme (smallrye-mutiny): light paper behind the drawing (before) and its dark version (after)
Dark theme (smallrye-stork): light paper behind the drawing (before) and its dark version (after)
Dark theme (smallrye-mutiny-zero): light paper behind the drawing (before) and its dark version (after)

Dark theme: the same screenshots with the dark theme

The old Antora sites and the GraphQL, Vert.x bindings and Mutiny Zero MkDocs sites have no dark theme, so their "before" stays light; the other old MkDocs sites were switched to their own dark palette.

Before (dark theme)	After (dark theme)
jandex · smallrye/jandex#733 · old page
smallrye-config · smallrye/smallrye-config#1603 · old page
smallrye-fault-tolerance · smallrye/smallrye-fault-tolerance#1351 · old page
smallrye-graphql · smallrye/smallrye-graphql#2732 · old page
smallrye-health · smallrye/smallrye-health#713 · old page
smallrye-jwt · smallrye/smallrye-jwt#935 · old page
smallrye-mutiny · smallrye/smallrye-mutiny#2220 · old page
smallrye-mutiny-vertx-bindings · smallrye/smallrye-mutiny-vertx-bindings#1475 · old page
smallrye-mutiny-zero · smallrye/smallrye-mutiny-zero#376 · old page
smallrye-reactive-messaging · smallrye/smallrye-reactive-messaging#3577 · old page
smallrye-stork · smallrye/smallrye-stork#1385 · old page
Sidebar open (smallrye-reactive-messaging, nested groups)
Further down the start page: its contents, listed from the navigation

[Ladicek]

Hey @phillip-kruger, this looks amazing! One question: are we supposed to merge your PRs in the individual projects before this one is merged, or after? Or it doesn't matter?

[Ladicek]

Oh one more thing: the way we preview individual project docs locally is not good. I mean, it's probably the best we can do at the moment, and I usually don't mind because IntelliJ's built-in Asciidoc renderer is good enough for most cases, but when it's not... Well, I guess I'll get used to it. At least it's documented :-)

[phillip-kruger]

Thanks @Ladicek! Best is this one first, then the project PRs in any order.

• Each project PR adds a "Documentation" check that calls a workflow from this PR, so that check fails until this one is merged.
• The current site still builds the Antora docs, and for JWT it reads doc/ on main. Move the documentation from Antora to AsciiDoc pages published on smallrye.io smallrye-jwt#935 is merged already, so the next build of the current site would fail on JWT until this PR (which drops Antora) is in. Fault Tolerance and Health are fine either way, as the current site reads their tags and the 3.0.x branch.
• Nothing waits for the project PRs: once this is merged, smallrye.io converts every project's current release on the fly, and the nightly sync picks up each project's own AsciiDoc on main the night after its PR is merged.

[Ladicek]

OK, thanks! I'll review the PRs but wait with merging until this is done.

[phillip-kruger]

@Ladicek I'll add something that make local preview easier.

[phillip-kruger]

@Ladicek about previewing locally: that should be much better now.

In a project's checkout, ./mvnw -Pdocs-preview shows its documentation on a local smallrye.io at http://localhost:8080/docs/<project>/main/, and publishes it again whenever a page or an included example is saved (a few seconds, then refresh). No smallrye.github.io checkout, no paths, no Python: only Java. The profile runs the docs tools with JBang (and installs JBang if needed); with JBang installed, jbang docs-preview@smallrye/smallrye.github.io does the same.

To make that possible, the tools in this PR are now Java (one JBang program, tools/docs/Docs.java) instead of Python; each tool was checked byte for byte against the Python version, including the whole nightly sync (28 versions of 13 projects). Every project PR has the profile and an updated "Previewing" section in its docs README (I folded your README fixes in: the path is gone). It works once this PR is merged, since it runs the tools from develop.

[Ladicek]

Sounds much better, thanks!