Quarkus.io Website

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.

Prerequisites

• Java 21+
• Maven (or use the included ./mvnw wrapper — no separate Maven install required)

Running locally

1. Fork the project repository, then clone your fork:

   git clone git@github.com:YOUR_USER_NAME/quarkusio.github.io.git

2. Change into the project directory:

   cd quarkusio.github.io

3. Start the dev server:

   ./serve.sh

   This runs mvn quarkus:dev and serves the full site (including guides) at http://localhost:8042.

   For a faster startup without guides:

   ./serve-noguides.sh

   Or with only the latest guides (latest and main branches):

   ./serve-only-latest-guides.sh

Note

The startup process may take a minute or two on the first run while Maven downloads dependencies and Roq generates the site. Subsequent starts are faster. Once ready, you will see output like:

Listening on: http://0.0.0.0:8042

5. Now browse to http://localhost:8042.

Deploying to GitHub Pages

The website deployment is automatically performed by GitHub Actions (when commits are pushed to the main 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

Warning

Using generative AI in assisting writing is fine, but please don't use it to write entire posts. Used badly, generative AI has a tendency to use complex words and phrasing. This makes the content hard to read and understand. Always review your blog with a human reader in mind, make sure it's factually correct and especially keep the human touch and opinions in the content. We want your voice!

To write a blog:

• create an author entry in _data/authors.yaml

  • emailhash you can get by running echo -n your@email.org | md5sum on Linux or echo -n your@email.org | md5 on macOS using an email you have registered from the Gravatar service,

• create a blog entry under content/posts

  • the file name is yyyy-mm-dd-slug.adoc (the publication date of the blog).

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

  • quarkus-release used for Quarkus release blogs
  • announcement used for general announcements 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 tag like kafka if your post has a significant mention/relevance to that technology.
  • tags is a space-separated list: tags: extension grpc
  • tags must be in lowercase

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

  • Be aware that the date attribute in the file name defines when the article will be published. Posts with a future date will not be visible in production until that date arrives; the pull request preview, dev mode and ./serve.sh show them regardless of date.

• send a pull request against the main 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.