Update docs metadata generation

[ebullient]

• Summary: Use the first sentence of the preamble or the 'summary' attribute value.
• Use a 'categories' attribute for gross category grouping, including 'get-started' for "Getting Started" / introductory tutorials.

[michelle-purcell]

@ebullient - Looks good 👍

What if both the 'summary' attribute and the asciidoc 'preamble' exist? Which takes precedence and gets added to the "summary:" (formerly "description") bit of the index.yml file, as per the screencap below? Apologies if I missed this in the code. Thanks :-)

[ebullient]

What if both the 'summary' attribute and the asciidoc 'preamble' exist? Which takes precedence and gets added to the "summary:" (formerly "description") bit of the index.yml file, as per the screencap below? Apologies if I missed this in the code. Thanks :-)

The summary wins.

quarkus/docs/src/main/java/io/quarkus/docs/generation/YamlMetadataGenerator.java

Line 118 in 30b8c32

String result = (summary != null ? summary.toString() : content.orElse(""))

[maxandersen]

looks fine - is the output of this hooked into the publishing yet or is that a TDB?

[michelle-purcell]

@ebullient - FYI and related to this PR:
As per our discussion last week, I started to add some guidance in PR27286 about how to write a 'good' abstract and how it (will) dynamically generate the one-liner for the home page.

Also...

Ideally, the first-sentence summary of the abstract (aka asciidoc preamble) should be less than 26 words. Would it make sense to add a validation check? Thanks.

[ebullient]

looks fine - is the output of this hooked into the publishing yet or is that a TDB?

Not hooked into publishing yet. All of this is still in-flight / under review. The lastest changes are after reviewing with Michelle, which gave me some ideas for making the intent of some fields easier to understand.

[maxandersen]

lgtm