Include the extension status explanation and use status derived from extensions if not defined explicitly by marko-bekhta · Pull Request #2519 · quarkusio/quarkusio.github.io

marko-bekhta · 2026-01-20T14:34:33Z

Follows up on Add labels to guides with extension status (if available) #2508
Requires Include "derived status" based on statuses of extensions referenced in the guides metadata quarkus#52100

This updated asciidoc extension would inject the status label and explanation next to it, so we wouldn't need to remember to include the extension-status.adoc include and make things a bit more "automated"

A few previews:

cc: @yrodiere @FroMage @insectengine @rolfedh

…extensions if not defined explicitly

github-actions · 2026-01-20T14:39:41Z

🎊 PR Preview 77cc3bd has been successfully built and deployed to https://quarkus-site-pr-2519-preview.surge.sh

Images of blog posts older than 3 months are not available.
Newsletters older than 3 months are not available.

insectengine · 2026-01-20T15:52:45Z

For the guides, I'd say we keep it simple text link.

I also again question not having "stable" visible as a status instead of the invisible default. This way people know and it could prevent confusion.

marko-bekhta · 2026-01-20T16:03:18Z

thanks 🙂, having just a link looks good and we wouldn't need to repeat the text in multiple places 👍🏻 I like that too 🙂

As for the label, you think we shouldn't keep the colour ? (my thinking was that it would be nice to show the user the same "coloured label" they noticed on the search results when they open the guide itself ... but if you think it's better without colors here I'm fine with that 🙂)

About stable ... yeah I agree with you, I just thought that that was the conclusion that we don't show it so I didn't include it... 😔

FroMage · 2026-01-20T16:24:50Z

@insectengine the idea with the bright colours was to make sure people would never use this extension by accident without knowing their status. So we need something more visual than just a regular link.

Perhaps it should be a simple link for "stable", and colours and warning and inline text for anything else? This would achieve the "disclaimer" function we want.

gsmet

I'm all for this but I think we need to discuss this part a bit. See inline.

gsmet · 2026-01-20T17:19:10Z

+
+      if status.nil? || status.empty?
+        extension_statuses = doc.attr('extensions', '').split(',')
+            .map(&:strip)
+            .reject(&:empty?)
+            .map { |s| s.gsub(/[.:]/, '-') + '-extension-status' }
+            .map { |s| doc.attr(s, '') }
+        status = ['experimental', 'preview', 'deprecated'].find { |s| extension_statuses.include?(s) }
+      end


This part is a bit dangerous IMO. IIRC, the extensions metadata can be a bit broad as they are used for search.

I wonder if maybe you should only take into account the first one? But then we would have to check the metadata is correct and that the first one is ALWAYS the right one.

The "upstream" part of the docs (quarkusio/quarkus#52100) will always include a definitive status based on the list of extensions per guide, by selecting the "least favourable" status.
I'm not sure how we can fall into this branch if that's the case.

mmm I remember seeing the guide link in the extension metadata yaml:

https://github.com/quarkusio/quarkus/blob/39f7eb8c51ff55216bf50626efa46362490e7971/extensions/hibernate-search-standalone-elasticsearch/runtime/src/main/resources/META-INF/quarkus-extension.yaml#L13

if we go with that ? meaning if we get the status from that extension's yaml and "assign" it to the guide it mentions, instead of just taking the list of extensions specified in the adoc ( https://github.com/quarkusio/quarkus/blob/39f7eb8c51ff55216bf50626efa46362490e7971/docs/src/main/asciidoc/hibernate-search-standalone-elasticsearch.adoc?plain=1#L12)

so after going through all yamls we'd have a map of <guide, List<extension>> ? would that be a more reliable source ?

(just thinking out loud 🫣 🙂 )

another idea I had was to say something like:

this guide mentions extensions that are in the following statuses : ...

and show them in a "table format" with status, and list of extensions in that status

I'm not following the discussion here. What does #52100 do then if not fetch the statuses of all extensions per guide, so it can be used here?

right, it fetches the statuses of extensions from their yaml files, and then it looks at the :extensions: attribute inside of the adoc file to see which extension statuses to "combine"

quarkusio.github.io/_guides/aws-lambda.adoc

Line 11 in 26264d7

:extensions: io.quarkus:quarkus-amazon-lambda

and I was asking if "ignoring" the attribute in the guide (:extensions: ) and instead using the guide link in the extension's yaml:

guide: "https://quarkus.io/guides/hibernate-search-standalone-elasticsearch"

would be better...

I've no idea, maybe that's the same info just in two different places, maybe not 🤷🏻 🫣 🙂

There must be something I don't understand. If quarkusio/quarkus#52100 will correctly set the :extension-status: for every guide, why can't we use it here instead of trying to recompute it?

insectengine · 2026-01-20T17:41:30Z

@insectengine the idea with the bright colours was to make sure people would never use this extension by accident without knowing their status. So we need something more visual than just a regular link.

Perhaps it should be a simple link for "stable", and colours and warning and inline text for anything else? This would achieve the "disclaimer" function we want.

Agreed. The text can change color for each of the statuses to match the tags in the extensions catalog.

holly-cummins · 2026-07-14T13:25:17Z

Where are we with this? We've just had a complaint about the statuses being out of sync, and I think this might help that (as well as being generally useful and good): https://stackoverflow.com/questions/79980670/quarkus-aws-lambda-http-in-preview-state

marko-bekhta · 2026-07-14T14:11:20Z

We've just had a complaint about the statuses being out of sync

😭

Where are we with this?

Me personally somewhere in the undecided/confused area 🙈 🙂. As to why ?! ... My understanding is that:

a single guide (adoc file) can have a list of extensions in it
each extension inside it's yaml file (quarkus-extension.yaml in the project's META-INF/resources) can have a link to a guide.

Now, my confusion comes from:

what should we take as a source of truth:
- guide adoc file metadata
- quarkus-extension.yaml
- combine both of the above ^
- or validate the above and fail Quarkus doc build on mismatch?
if a guide is referenced from multuple extensions -- how do we want to compute the "final" status that we show to the user on the guide page ?
- the "worst" one wins
- show all as pairs extension-status
- something else

I'd personally go for "validate and fail" + "show pairs of extension-status" .... but ... 🤷🏻 🙂

holly-cummins · 2026-07-14T16:03:09Z

This PR is at risk from the Roq migration. Most site content I can migrate in an automated way. That means any PRs that miss the train can be patched up using the same scripts. However, the plugins needed to be hand-crafted. That work's already been done, so for where we are, I'll either need to redo the plugin work to incorporate this, or this will need to be ported to java after #2683 merges. Since it's been hanging around for a while, and has some open questions, selfishly, I propose we revisit it post-migration. That does mean we shouldn't do any more coding work before the migration.

marko-bekhta · 2026-07-14T21:45:31Z

I'm ok with adding the extension later in ascidoctorj 🙂,
In the meantime, if we could have a decision on how to derive the status, it would be nice 🙂 🤞🏻

holly-cummins · 2026-07-16T09:31:28Z

My view is we should be as DRY as possible: the extension metadata is the preferred source of truth for status, and ideally, the only source of truth. So I'd say:

We try quite hard to never include a status in a guide, although this may be hard to stick to, since sometimes a feature will be immature even though an extension is mature
Where a guide refers to multiple extensions, we list them all and show the status pairs

But I'm perhaps making comments that are more relevant to the pre-#2508 world.

marko-bekhta · 2026-07-16T12:18:56Z

since sometimes a feature will be immature even though an extension is mature

so maybe ..... we have an extension status -- we'll show it on the main page where all the guides are listed and then at the top of the guide... but at the same time we allow for a "status badge" at a section title level where a feature described in that section is tagged as experimental (or whatever other status it is in != stable)?

edit: here's an example of how we do it in Search: https://docs.hibernate.org/stable/search/reference/en-US/html_single/#architecture-examples-outbox-polling-elasticsearch

holly-cummins · 2026-07-16T15:42:41Z

Sounds perfect.

rolfedh

Thanks @marko-bekhta — I really like the direction here. The old tooltip was easy to miss (its text never appears on touch devices), and deriving the status from extension metadata removes a whole class of silent failures: nobody has to remember the include, and the banner stays correct when an extension is promoted later. The side-by-side layout in your previews looks clean.

Having caught up on the thread: +1 to listing the extensions with their statuses — your table idea from the January inline discussion, and Holly's "list them all and show the status pairs". For guides that cover several extensions, that answers the reader's real question: which extension is the non-stable one.

My two inline comments are about the text rather than the code — a typo fix, and a copy edit of the explanation wording, aligned with extension-status.adoc — so they should stay relevant for whichever implementation lands after the Roq migration; they are not a request to resume coding now. Glad to help remove the now-redundant extension-status.adoc includes once this work lands in whatever form it takes.

rolfedh · 2026-07-18T16:48:58Z

+            '<p>The extension(s) discussed here request early feedback to mature the idea.</p><p>There is no guarantee of stability nor long term presence in the platform until the solution matures. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a></p>.'
          when 'preview'
-            'This extension\'s backward compatibility and presence in the ecosystem is not guaranteed'
+            '<p>The backward compatibility and presence in the ecosystem of extension(s) discussed here is not guaranteed.</p><p>Specific improvements might require changing configuration or APIs, and plans to become <em>stable</em> are under way. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a>.</p>'
          when 'stable'
-            'This extension\'s backward compatibility and presence in the ecosystem are taken very seriously'
+            '<p>The backward compatibility and presence in the ecosystem of the extension(s) discussed here are taken very seriously.</p>'
          when 'deprecated'
-            'This extension is likely to be replaced or removed in a future version'
+            '<p>The extension(s) discussed here is likely to be replaced or removed in a future version.</p>'


Wording suggestion — text-level feedback, so it should carry over to whichever implementation lands after the Roq migration:

Align the explanation text with extension-status.adoc (the text readers already see on guides today), with one uniform lead-in pattern: "For X extensions, …". This avoids the "extension(s)" construction, which style guides recommend against, and it stays accurate whether a page discusses one extension or several.

The include's lead-in says "In experimental mode", but these are statuses (that's what the FAQ calls them), and "mode" already means something else in Quarkus (dev mode, native mode).

Light copy edits along the way: "no guarantee of stability or long-term presence" (after a negative like "no", plain "or" is standard, and "long-term" takes a hyphen before a noun); "are not guaranteed" ("backward compatibility and presence" is two things — the stable text already uses "are"); "plans are under way for them to become stable" (it is the extensions that become stable, not the plans); and the experimental period moves inside  — right now it renders below the paragraph, stuck to the FAQ sentence.

The FAQ entry keeps the older wording for now; I can send a small follow-up to align it.

Suggested change

'The extension(s) discussed here request early feedback to mature the idea.There is no guarantee of stability nor long term presence in the platform until the solution matures. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a>.'

when 'preview'

'This extension\'s backward compatibility and presence in the ecosystem is not guaranteed'

'The backward compatibility and presence in the ecosystem of extension(s) discussed here is not guaranteed.Specific improvements might require changing configuration or APIs, and plans to become stable are under way. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a>.'

when 'stable'

'This extension\'s backward compatibility and presence in the ecosystem are taken very seriously'

'The backward compatibility and presence in the ecosystem of the extension(s) discussed here are taken very seriously.'

when 'deprecated'

'This extension is likely to be replaced or removed in a future version'

'The extension(s) discussed here is likely to be replaced or removed in a future version.'

'For experimental extensions, early feedback is requested to mature the idea.There is no guarantee of stability or long-term presence in the platform until the solution matures. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a>.'

when 'preview'

'For preview extensions, backward compatibility and presence in the ecosystem are not guaranteed.Specific improvements might require changing configuration or APIs, and plans are under way for them to become stable. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a>.'

when 'stable'

'For stable extensions, backward compatibility and presence in the ecosystem are taken very seriously.'

when 'deprecated'

'Deprecated extensions are likely to be replaced or removed in a future version of Quarkus.'

rolfedh · 2026-07-18T16:48:58Z

+        staus_block_html = %(<div class="extension-status">#{label_html}#{explanation_inner_html}</div>)
+        label_block = create_pass_block doc, staus_block_html, {}


Tiny typo: staus → status.

Suggested change

staus_block_html = %(<div class="extension-status">#{label_html}#{explanation_inner_html}</div>)

label_block = create_pass_block doc, staus_block_html, {}

status_block_html = %(<div class="extension-status">#{label_html}#{explanation_inner_html}</div>)

label_block = create_pass_block doc, status_block_html, {}

Include the extension status explanation and use status derived from …

263610a

…extensions if not defined explicitly

marko-bekhta mentioned this pull request Jan 20, 2026

Include "derived status" based on statuses of extensions referenced in the guides metadata quarkusio/quarkus#52100

Open

gsmet reviewed Jan 20, 2026

View reviewed changes

rolfedh reviewed Jul 18, 2026

View reviewed changes

		staus_block_html = %(<div class="extension-status">#{label_html}#{explanation_inner_html}</div>)
		label_block = create_pass_block doc, staus_block_html, {}

Uh oh!

Conversation

marko-bekhta commented Jan 20, 2026

Uh oh!

github-actions Bot commented Jan 20, 2026

Uh oh!

insectengine commented Jan 20, 2026

Uh oh!

marko-bekhta commented Jan 20, 2026

Uh oh!

FroMage commented Jan 20, 2026

Uh oh!

gsmet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

insectengine commented Jan 20, 2026

Uh oh!

holly-cummins commented Jul 14, 2026

Uh oh!

marko-bekhta commented Jul 14, 2026

Uh oh!

holly-cummins commented Jul 14, 2026

Uh oh!

marko-bekhta commented Jul 14, 2026

Uh oh!

holly-cummins commented Jul 16, 2026

Uh oh!

marko-bekhta commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

holly-cummins commented Jul 16, 2026

Uh oh!

rolfedh left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rolfedh Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

marko-bekhta commented Jul 16, 2026 •

edited

Loading

rolfedh left a comment •

edited

Loading

rolfedh Jul 18, 2026 •

edited

Loading