From c44cd5ac0eb92f6c98831e17ec7115f2bd4e4ca3 Mon Sep 17 00:00:00 2001
From: Alain Reguera Delgado <areguera@centosproject.org>
Date: Jun 22 2024 19:09:07 +0000
Subject: docs: 📚 simplify jekyll build and serve processes


Use pre-baked container images with jekyll and all required dependencies
necessary to run jekyll build and jekyll serve command. This
significantly reduces the configuration time necessary to get started
with sites based on jekyll-theme-centos theme.

---

diff --git a/README.md b/README.md
index 2a7d06b..c150b6f 100644
--- a/README.md
+++ b/README.md
@@ -28,29 +28,28 @@ Let's assume the following (so feel free to update):
     export git_upstream="ssh://git@git.centos.org/forks/<ACO_LOGIN>/centos/centos.org.git" # replace with your ACO username
     export git_directory="${HOME}/git/" # where you'll git clone git repo
 
-Let's first clone git repo and ensure that some files in container will be owned by jekyll:
+Let's first clone git repo:
 
     test -d ${git_directory} || mkdir -p ${git_directory}
     pushd ${git_directory}
     test -d centos.org || git clone ${git_upstream}
 
-    for i in .jekyll-cache vendor vendor/bundle _site ; do
-      podman unshare mkdir -p ${git_directory}/centos.org/${i}
-      podman unshare chown -R $(id -u):$(id -u) ${git_directory}/centos.org/${i}
-    done
-    podman unshare chown -R $(id -u):$(id -u) ${git_directory}/centos.org/Gemfile.lock
-    popd
+Let's now for the first time launch jekyll using jekyll-theme-centos container
+image `v2.51.1-beta.49` version:
 
-Let's now for the first time launch jekyll:
+    install -d public
+    podman run --rm \
+      --name $@ \
+      -v $PWD/src:/site \
+      -v $PWD/public:/public \
+      registry.gitlab.com/centos/artwork/centos-web/jekyll-theme-centos:v2.51.1-beta.49 \
+      bundle exec jekyll build --config /site/_config.yml -s /site -d /public
 
-    podman images |grep -q jekyll || podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" --rm -it jekyll/jekyll bundle update
+### Versioning
 
-If that works, you'll have everything you need. You can then render/build the
-website (under _site directory) like this:
-
-    podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" \
-      --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" \
-      --rm -it jekyll/jekyll jekyll build
+The `jekyll-theme-centos` theme may introduce updates from time to time and
+produce newer container images with them. To keep your site presentation
+consistent, always use a fixed version when you run the jekyll build command.
 
 ## Running
 
@@ -59,12 +58,16 @@ website (under _site directory) like this:
 The better way to work on local changes is to have jekyll to automatically
 "watch" for local changes, and rebuild automatically on the fly when it detects
 that files were added/modified. To do this, and then to be able to browse
-"live" onhttp://localhost:4000, launch Jekyll like this:
-
-    podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" \
-      --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" \
-      -p 4000:4000/tcp \
-      --rm -it jekyll/jekyll jekyll serve
+"live" on http://localhost:4000, launch Jekyll like this:
+
+    install -d public
+    podman run --rm -d \
+      --name $@ \
+      -v $PWD/src:/site \
+      -v $PWD/public:/public \
+      -p 0.0.0.0:4000:4000 \
+      registry.gitlab.com/centos/artwork/centos-web/jekyll-theme-centos:v2.51.1-beta.49 \
+      bundle exec jekyll serve -H 0.0.0.0 -p 4000 --config /site/_config.yml -s /site -d /public
 
 ### Production