quarkiverse/quarkiverse-docs

Add link to GitHub repository automatically on each extension doc

Closed this issue · 6 comments

ia3andy commented

👆

holly-cummins commented

There's already an indirect version of this capability. If you know to click the 'edit this page' link, you can get to the github repo – but that's obviously dependent on people knowing the trick. :)

This also raises some interesting questions about how much overlap we want between the various sites, such as code.quarkus.io, docs.quarkiverse.io, and extensions.quarkus.io. For example, quarkusio/extensions#251 covers putting part of the docs on the main panel on extensions.quarkus.io, so it's sort of the opposite of this issue; if we did both, the two sites would become very similar.

From an implementation point of view, the overlap is slightly irritating, because it means duplicated code. From a user perspective, however, I can't think of any downside. Well, no downside as long as the 'extra' content doesn't add so much clutter that interferes with the core function of the site. For example, we'd want to carefully limit the amount of information on code.quarkus.io, because otherwise it becomes hard to use for app creation. The other thing we want to be cautious of is having so much overlap that users get confused about why we have several sites and what they should do on each one.

However, I think we will see more convergence between the three/four sites as time goes on.

(And the TLDR of that comment for this request is that I agree we should do it. :) )

jmini commented

I was about to open the same issue, because right now I am using the 'edit this page' link for that and then manually edit the location in the address bar or click on the project name to go back to the github home of the project.

Often I click on the 🏠 icon in the bar (because I am thinking let's go to the github home), and then I regret my click.

Screenshot 2024-09-12 at 11 13 50

--> if there is an option in Antora to hide this button you should do it, since you already have the logo at the top left corner to go to the "Quarkiverse documentation" page.

For me a button (with the github logo or whatever) would be perfect:

Screenshot 2024-09-12 at 11 06 49

And then, maybe it is out-of-scope for this issue, but I think you should make sure (or encourage the maintainer to configure it) that each quarkiverse project that has a guide also sets its guide as github project's website. This way you would have a standard link to the guide:

Screenshot 2024-09-12 at 11 17 24
holly-cummins commented

And then, maybe it is out-of-scope for this issue, but I think you should make sure (or encourage the maintainer to configure it) that each quarkiverse project that has a guide also sets its guide as github project's website. This way you would have a standard link to the guide:
Screenshot 2024-09-12 at 11 17 24

That would definitely be a different issue. @gastaldi, could the terraform scripts and the registry cooperate in some way to do that? I'm thinking get the extension list from the registry, for anything with an scm-url that points to the quarkiverse, update the repo description to include the guide link as the last line?

holly-cummins commented

Thanks, @gastaldi. Could we automate it? So it wasn't done manually? I guess that's probably more effort than it's worth.

gastaldi commented

Probably once (and if) we automate the creation of the Terraform scripts someday :)

  • 😄1