quarkusio / quarkusio.github.io

Website for Quarkus project

Quarkus.io Website Based on Jekyll

Getting Started

These instructions will get you a copy of the Quarkus.io website up and running on your local machine for development and testing purposes.

Installation

Using Docker or Podman

1. Install Docker Desktop or Podman Desktop.

2. Fork the project repository, then clone your fork.

    git clone [email protected]:YOUR_USER_NAME/quarkusio.github.io.git
   

3. Change into the project directory:

    cd quarkusio.github.io
   

4. Run Docker Compose using compose.sh

    compose.sh
   

5. OR run docker compose manually setting SELINUX to "Z:" or "" dependent on OS:

    _SELINUX_=Z: docker-compose up # Linux
    _SELINUX_=   docker-compose up # Mac or Windows
   

6. Now browse to http://localhost:4000

Using a local Ruby environment

Jekyll static site generator docs.

1. Install a full Ruby development environment. If you use rvm, run: rvm use 3.2.3.

2. Install bundler gems

    gem install bundler
   

3. Fork the project repository, then clone your fork.

    git clone [email protected]:YOUR_USER_NAME/quarkusio.github.io.git
   

4. Change into the project directory:

    cd quarkusio.github.io
   

5. Use bundler to fetch all required gems in their respective versions

    bundle install
   

6. Build the site and make it available on a local server

    ./serve.sh
   

   Or if you want it faster and okay to not have guides included use the following:

    ./serve-noguides.sh
   

7. Now browse to http://localhost:4000

If you encounter any unexpected errors during the above, please refer to the troubleshooting page or the requirements page, as you might be missing development headers or other prerequisites.

For more regarding the use of Jekyll, please refer to the Jekyll Step by Step Tutorial.

Deploying to GitHub Pages

The website deployment is automatically performed by GitHub Actions (when commits are pushed to the develop branch). If for some reason you need to deploy from your local machine, follow these instructions:

1. Install the act executable to run GitHub Actions locally
2. Run act -s GITHUB_TOKEN=<GITHUB_TOKEN>, where <GITHUB_TOKEN> needs to be replaced with a token that allows you to push to the https://github.com/quarkusio/quarkusio.github.io repository.

Writing a blog

To write a blog:

• create an author entry in _data/authors.yaml

  • emailhash you can get by running echo -n [email protected] | md5sum on Linux or echo -n [email protected] | md5 on macOS using an email you have registered from the Gravatar service,

• create an blog entry under _posts

  • the file name is yyyy-mm-dd-slug.adoc Set the date to the same value in the asciidoc preamble.

• tags should be used with some care as an archive page is created for of them. Below are some basic rules to try follow:

  • quarkus-release used for Quarkus release blogs
  • announcement used for general announcement with some impact.
  • extension used for blogs related to a specific extension.
  • user-story used for stories from users/companies adopting Quarkus.
  • development-tips used for blogs with tips to develop using Quarkus or Quarkus itself.
  • add a tech specific, like kafka, if your post has a significant mention/relevance to that technology.
  • tags is space separated list tags:extension grpc
  • tags must be in lowercase

• it's in asciidoc format, there is an example as shown with 2019-06-05-quarkus-and-web-ui-development-mode.adoc

  • Be aware that the date attribute in the asciidoc preamble defines when the article will be published. Add a --future flag when testing locally to ensure the article is included in the generated site.

• send a pull request against the develop branch and voilà

Translations/Localization (l10n)

The primary site (quarkus.io) is written in English.

There are separate repositories for community driven localized versions of quarkus.io:

• ja.quarkus.io for Japanese
• cn.quarkus.io for Chinese (simplified)
• es.quarkus.io for Spanish
• pt.quarkus.io for Brazilian Portuguese

If you want to contribute to those efforts read the README in those projects. If you would like to start another translation, please open an issue in this main repo.

Enable DNS for l10n site

Once a localized site has enough of its content translated, DNS needs to be enabled. To do that get one of the Red Hat admins to submit a ticket to IT asking for XX domain:

We need a CNAME record set up for XX.quarkus.io to have it serve out GitHub pages. 

The CNAME record for XX.quarkus.io should point to "quarkusio.github.io.".

See Step 5 on https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site for more information.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Important: the guides are maintained in the main Quarkus repository and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc.

License

This website is licensed under the Creative Commons Attribution 3.0.

quarkusio.github.io's Issues

Add background image for guides / extensions / community

Add background image for guides / extensions / community

Similar to image background for https://quarkusio.github.io/get-started/

Code example missing in Reactive tab of Imperative and Reactive in one programming model section

https://quarkusio.github.io/
=> Imperative and Reactive in one programming model
=> Reactive tab

  $ Hello world!
  $ Hello world!
  $ Hello world!
  $ Hello world!

Instead of code

Links in the header navigation are 'sticky'

Start from the top level page and click on any of the links in the header navigation, for ex, 'Get Started'. Now 'Get Started' is underlined with the green line as expected. Move the cursor to the next link, 'Guildes' - you will see both 'Get Started' and 'Guildes' being underlined at the same time

404 for the validation guide

Verify and fix the unnecessary horizontal and vertical scrolling of the code samples

They are all rendered with some additional indentation on the first line.
Please fix this :) as it helps understanding them.

Introduce Rouge syntax highlighting

Fix link to Hibernate to be https

Remove Quarkus repository maven settings from guides

quarkus artefacts will be published to maven central, we need to remove the custom nexus settings for maven from the guides

community link is broken

https://quarkusio.github.io/community/

Swap Imperative and Container first sections on the home page

List guides by categories

0-glossary.adoc -> ignore
application-configuration-guide.adoc -> Core (first / no category)
application-lifecycle-events-guide.adoc -> Core (first / no category)
attributes.adoc -> ignore
building-native-image-guide.adoc -> Getting started
building-substrate-howto.adoc -> ignore
cdi-reference.adoc -> Core (first / no category)
cli-tooling.adoc -> ignore
docinfo.html -> ignore
extension-authors-guide.adoc -> Writing extensions
faq.adoc -> ignore
getting-started-guide.adoc -> Getting started
getting-started-knative-guide.adoc -> Cloud
getting-started-testing.adoc -> Core (first / no category)
gradle-config.adoc -> ignore
gradle-tooling.adoc -> Tooling
hibernate-orm-guide.adoc -> Data
hibernate-orm-panache-guide.adoc -> Data
images -> ignore
index.adoc -> ignore
infinispan-client-guide.adoc -> Data
jwt-guide.adoc -> Web and Security
kotlin.adoc -> Alternative languages
kubernetes-guide.adoc -> Cloud
logging-guide.adoc -> core (first / no category)
maven-tooling.adoc -> Tooling and Getting started
native-and-ssl-guide.adoc -> Core (first / no category)
opentracing-guide.adoc -> Observability
performance-measure.adoc -> Miscellanous
quarkus-intro.adoc -> ignote
README.adoc -> ignore
rest-client-guide.adoc -> Web
rest-json-guide.adoc -> Web, Serialization
scheduled-guide.adoc -> Miscellanous
security-guide.adoc -> Security
spring-di-guide.adoc -> Migration
tooling.adoc -> Tooling
transaction-guide.adoc -> Data
validation-guide.adoc -> Data, Web
websocket-guide.adoc -> Web

Item 4 get started with quarkus needed for *native* applications

I think step 4. should be re-worded to "You’ll need GraalVM for native applications"

Building a Native image guide uses a wrong Dockerfile path

Unordered lists have too much spacing

Add <head><title> to all the pages

It should probably be done by adding a title: variable in the .md files but I don't know Jekyll so we would have to test that.

Code blocks have odd indentation

Code blocks have odd initial indentation:

I couldn't figure out why this is happening; there does not seem to be any initial space or any CSS that affects this.

Building a Native Image guide - a clement-specific path in Note

Once you have downloaded GraalVM, expand the archive and set the GRAALVM_HOME variable to this location: export GRAALVM_HOME=~clement/Development/graalvm/

Should we have a no compromises section on the home page?

Looking at John's email on our position, I wonder about $subject

Landing page refers to protean-dev mailing list

We should delete that and just keep the Zulip as there is no quarkus-dev mailing list.

Hyperlinks inside of inline code bits are not monospaced

Block-style code is fine.

Bad:

OK:

Consider a animated gif for developer joy

We will go for a static image as backup but an animated gif showing the effect of live reload would be more powerful.

Readme is missing bundle install command

Before launching bundle exec jekyll serve contributor should launch bundle install to install all project dependencies

No space before (or after?) admonitions

This should probably be handled in the CSS for admonitions I would guess.

The code tab in home does not work well on a phone

Click on the reactive and you will see tabs jiggle.
Worse case we can hide it in a mobile.

Align names of guides with TOC

They're different.

Try and include attributes.adoc in our own adoc documentation to mimick website need

Developer joy list on home page needs more vertical spacing

It's barely readable:

Usability: Arrow or some other indicator to page down front page

We noticed that it's really easy to not notice there is content below the GET STARTED button on the front page. Perhaps there could be some sort of arrow or see more or something to indicate more content?

Main page - too big distance between Developer Joy and Best of Breed Libraries and Standards

Main page - too big distance between Developer Joy and Best of Breed Libraries and Standards section

Populate extension description on YAML structure

Based on the category GitHub issue.

Additional logos for the home page

On the home page we have a list of logos (hibernate, resteasy, vert.x, microprofile, etc) for projects that Quarkus consumes or interoperates with. Please add the following logos:

Kubernetes:

Jaeger:

OpenShift:

Prometheus

Admonitions don't look good

Guides page: the list is missing a few guides and some links are broken

Move highlightjs selectors into _sass

...so we can use variables and stuff.

Fix the second code snippet in the home (container first)

Check dead links in guides and fix them

Discuss and choose developer joy side image

Jason Broke proposed some, let's discuss and adapt text potentially.

Callouts not rendering

Callouts aren't working:

asciidoctor: WARNING: getting-started-knative-guide.adoc: line 113: no callout found for <1>
                    ...done in 1.187541 seconds.

It might magically start working once #43 is resolved.

Some front-page library logos are transparent

And they look VERY wrong on black background.

Tables have an nth-child (even) but no nth-child (odd) style

This causes odd rows to be "transparent" but even rows to be black. It should probably alternate between two grays, or gray and black, or red and dark red maybe.

Developer Joy section has comment on command line

Code does not render well in notes

From https://quarkusio.github.io/guides/getting-started-knative-guide, Deploy Key is in a code element but that's not visible.

Add Google group to home page?

@emmanuelbernard

The mailing list link has been removed here: #23 .

But I thought we wanted to have a Google Groups mailing list? Should we add it instead?

Issues to fix on the website

Mandatory

• Fix mailing list + Zulip link on front page
• Fix license information in footer: the dependencies are not all AL2 and is LGPL compatible with AL2?
• Fix link to https://jbossorg.github.io/protean/guides/json-and-validation-guide, it should be validation-guide
• Check all the guides are up to date and correctly linked (we added a few very late)
• Fix case of cohesive platform from config to build. on home page
• Should the GitHub link points to the org (as it is now) or to the quarkus project?

Nice to have

• Bob was wondering if we should point directly to the GraalVM download page from https://jbossorg.github.io/protean/get-started/ , instead of the home page
• Fix the first line alignment issue in code blocks
• Remove the scrollbars from code
• Syntax highlighting for code

Some footers have a weird rendered logo

The footer looks nice on https://quarkusio.github.io/

But on https://quarkusio.github.io/guides/infinispan-client-guide it looks like:

Links to guides and getting started are broken on quarkusio.github.io

Settle on the getting started 4 points

Do we mention Gradle?
remove knative and mention Kube?

Missing Infinispan logo in section "Best of Breeds Libraries and Standards"

Please add the infinispan logo to the section mentioned in the subject line. Infinispan logo can be found here:
http://design.jboss.org/infinispan/

and here's the 600px one:
http://design.jboss.org/infinispan/logo/images/infinispan_logo_600px.svg

Thanks,
Cesar

Choose a monospace font

And do whatever CSS magic is necessary to ensure that the font is available on user agents.

Give numbers to Jason Brock to generate the performance graph image