From 4e93d2197454d82e75ebb02e7c86a089552a0776 Mon Sep 17 00:00:00 2001 From: Jon Koops Date: Wed, 2 Oct 2024 12:41:42 +0200 Subject: [PATCH] Improve documentation in README Closes #503 Signed-off-by: Jon Koops --- README.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 94872024..88452fcd 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,35 @@ # Sources for keycloak.org -Can be built locally from IDE by running AutoBuilder main method or with Maven by running: +Can be built locally from IDE by running `AutoBuilder` main method or with Maven by running: - mvn clean install - -After the build is completed open `target/web/index.html` in your favourite web browser. - -There's also an auto-builder utility that watches the filesystem and continuously rebuilds the website. This can be very useful when working on the website, especially making stylesheet changes, etc. This can be run from your IDE by running `AutoBuilder`, or from the command-line with: +```sh +KC_URL=http://localhost:8080 mvn clean install +``` - mvn -Pauto-run exec:java +Once built you can serve the `target/web` directory from a local web server, for example using [http-server](https://www.npmjs.com/package/http-server): -To serve the website locally with a web browser specify the base URL with `KC_URL`: +```sh +npx http-server target/web +``` - export KC_URL=http://localhost:8000 - mvn install +To serve the website locally from a different domain or port you can set the base URL with the `KC_URL` environment variable. +There's also an auto-builder utility that watches the filesystem and continuously rebuilds the website. This can be very useful when working on the website, especially making stylesheet changes, etc. This can be run from your IDE by running `AutoBuilder`, or from the command-line with: + +```sh +mvn -Pauto-run exec:java +``` + Finally, when building the website to be published you need to include `-Dpublish`. This should usually not be done manually though as there is a GitHub Action that takes care of building and publishing to `https://github.com/keycloak/keycloak.github.io`. ## Server and Operator guides Server and Operator guide sources are located at `https://github.com/keycloak/keycloak/tree/main/docs/guides` and are retrieved as a Maven dependency. By default the latest released version is used, but if you want to build the website with the latest guides from `main` first build the guides: - git clone https://github.com/keycloak/keycloak - cd keycloak - mvn -pl docs clean install +```sh +git clone https://github.com/keycloak/keycloak +cd keycloak +mvn -pl docs clean install +``` Then simply build the website locally with `mvn clean install`, and the locally built guides will be available in `target/web/nightly/guides.html`.