From c69f5f447d36cd6c2933d502d959fb7952bbec68 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 17:00:34 +0100 Subject: [PATCH 01/11] Migrate from Material for MkDocs to Zensical (#1) * Initial plan * Migrate from Material for MkDocs to Zensical Co-authored-by: pattacini <3738070+pattacini@users.noreply.github.com> * Update .github/workflows/gh-pages.yml * Update .github/workflows/test-pr.yml --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: pattacini <3738070+pattacini@users.noreply.github.com> Co-authored-by: Ugo Pattacini --- .github/workflows/gh-pages.yml | 8 +++----- .github/workflows/test-pr.yml | 8 +++----- README.md | 27 +++++++++++---------------- 3 files changed, 17 insertions(+), 26 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 4457a460d..e8a1e2b51 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -23,9 +23,7 @@ jobs: run: | sudo apt update sudo apt install -y python3-wheel python3-setuptools - pip install --break-system-packages --upgrade Jinja2 - pip install --break-system-packages --user mkdocs - pip install --break-system-packages --user $(mkdocs get-deps) + pip install --break-system-packages --user zensical pymdown-extensions pip install --break-system-packages --upgrade pygments echo "${HOME}/.local/bin" >> ${GITHUB_PATH} @@ -36,9 +34,9 @@ jobs: git config --global user.email "actions@github.com" git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git - - name: Build Mkdocs + - name: Build Zensical run: | - mkdocs build + zensical build - name: Create and prepare gh-pages anew run: | diff --git a/.github/workflows/test-pr.yml b/.github/workflows/test-pr.yml index b647228b9..2d85ae7f3 100644 --- a/.github/workflows/test-pr.yml +++ b/.github/workflows/test-pr.yml @@ -14,15 +14,13 @@ jobs: run: | sudo apt update sudo apt install -y python3-wheel python3-setuptools - pip install --break-system-packages --upgrade Jinja2 - pip install --break-system-packages --user mkdocs - pip install --break-system-packages --user $(mkdocs get-deps) + pip install --break-system-packages --user zensicalm pymdown-extensions pip install --break-system-packages --upgrade pygments echo "${HOME}/.local/bin" >> ${GITHUB_PATH} - - name: Build Mkdocs + - name: Build Zensical run: | - mkdocs build --strict > log 2>&1 + zensical build --strict > log 2>&1 - name: Print Log if: always() diff --git a/README.md b/README.md index 0fd5ed77c..f7ff78ee2 100644 --- a/README.md +++ b/README.md @@ -40,18 +40,14 @@ Follow the steps below where you have to correctly fill up the signature `your-f ## 💻 Install the environment yourself If you prefer to work on the documentation on your own computer without using Cloud IDEs as described in the previous section, -you need to install [**`mkdocs`**](https://www.mkdocs.org/) first. +you need to install [**`zensical`**](https://zensical.org/) first. -Once installed, just clone this repo, navigate to it and install the required dependencies: +Once installed, just clone this repo, navigate to it and serve the content: ```console git clone https://github.com/icub-tech-iit/documentation.git cd documentation -pip install --break-system-packages $(mkdocs get-deps) -``` - -Finally, serve the content: -```console -mkdocs serve +pip install zensical +zensical serve ``` ## 📦 Rely on package managers @@ -61,19 +57,18 @@ In the next sections, we will describe in detail how to install the required dep You can use the [conda-forge](https://conda-forge.org/) distribution to install the required dependencies on Linux, macOS or Windows. First of all you need a conda distribution, for example [Miniforge3](https://github.com/conda-forge/miniforge). -If you already have a conda distribution, just create a new [environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) (for example called `mkdocs-env`) and install in it the require dependencies: +If you already have a conda distribution, just create a new [environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) (for example called `zensical-env`) and install in it the required dependencies: ```console git clone https://github.com/icub-tech-iit/documentation.git cd documentation -conda create -n mkdocs-env -conda activate mkdocs-env -conda install --channel conda-forge mkdocs -conda install --channel conda-forge $(mkdocs get-deps) +conda create -n zensical-env +conda activate zensical-env +pip install zensical ``` -After the installation, whenever you need to test the website just activate the `mkdocs-env` environment and call `mkdocs serve` in the `documentation` directory: +After the installation, whenever you need to test the website just activate the `zensical-env` environment and call `zensical serve` in the `documentation` directory: ```console cd documentation -conda activate mkdocs-env -mkdocs serve +conda activate zensical-env +zensical serve ``` From d00415f7d6edab628b3e0e36bc86a55d0b252785 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:09:10 +0100 Subject: [PATCH 02/11] Update gh-pages.yml --- .github/workflows/gh-pages.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index e8a1e2b51..1494a1dac 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -23,8 +23,9 @@ jobs: run: | sudo apt update sudo apt install -y python3-wheel python3-setuptools - pip install --break-system-packages --user zensical pymdown-extensions - pip install --break-system-packages --upgrade pygments + pip install --break-system-packages --user zensical + # pip install --break-system-packages --user zensical pymdown-extensions + # pip install --break-system-packages --upgrade pygments echo "${HOME}/.local/bin" >> ${GITHUB_PATH} - name: Configure Git From 71e8b7885d8cc40176500238de0732fba24bbc24 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:15:31 +0100 Subject: [PATCH 03/11] Update gh-pages.yml --- .github/workflows/gh-pages.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 1494a1dac..6e43fcf64 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -24,8 +24,6 @@ jobs: sudo apt update sudo apt install -y python3-wheel python3-setuptools pip install --break-system-packages --user zensical - # pip install --break-system-packages --user zensical pymdown-extensions - # pip install --break-system-packages --upgrade pygments echo "${HOME}/.local/bin" >> ${GITHUB_PATH} - name: Configure Git From 56eae34a8efc04d90fd8e223cdeb469914e690b7 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:15:53 +0100 Subject: [PATCH 04/11] Modify Zensical installation in test-pr.yml Updated installation command for Zensical in CI workflow. --- .github/workflows/test-pr.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/test-pr.yml b/.github/workflows/test-pr.yml index 2d85ae7f3..ac5659687 100644 --- a/.github/workflows/test-pr.yml +++ b/.github/workflows/test-pr.yml @@ -14,8 +14,7 @@ jobs: run: | sudo apt update sudo apt install -y python3-wheel python3-setuptools - pip install --break-system-packages --user zensicalm pymdown-extensions - pip install --break-system-packages --upgrade pygments + pip install --break-system-packages --user zensical echo "${HOME}/.local/bin" >> ${GITHUB_PATH} - name: Build Zensical From 75a502905178be1d583305d045c6ed3b7ea4a2c7 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:18:05 +0100 Subject: [PATCH 05/11] Replace mkdocs installation with zensical --- .devcontainer/Dockerfile | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index e2673a9b7..36ce2dbde 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -10,10 +10,7 @@ RUN apt update && \ apt install -y sudo apt-utils bash-completion wget ruby git magic-wormhole \ python3 python3-pip python3-setuptools python3-wheel -RUN pip install --break-system-packages mkdocs && \ - wget https://raw.githubusercontent.com/icub-tech-iit/documentation/master/mkdocs.yml && \ - pip install --break-system-packages $(mkdocs get-deps) && \ - rm mkdocs.yml +RUN pip install --break-system-packages zensical RUN gem install yaml From 46347e71b1e791d5d006a0f86a816d4c6a2b7987 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:20:39 +0100 Subject: [PATCH 06/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f7ff78ee2..00ad03aae 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ When forking the repository, remember to copy out all the branches. Then, work o Follow the steps below where you have to correctly fill up the signature `your-fork`: - Browse to https://github.com/your-fork/documentation/actions and enable the actions if they got disabled. - Browse to https://github.com/your-fork/documentation/actions/workflows/gh-pages.yml and click on the Run workflow button. -- Browse to https://github.com/your-fork/documentation/settings/pages, select the `gh-pages` branch and wait until the GitHub Pages link becomes green to click on! +- Browse to https://github.com/your-fork/documentation/settings/pages, select Deploy from a branch button and then the `gh-pages` branch and wait until the GitHub Pages link becomes green to click on! # 🔽 Local Workflow From c3bf6eec7108f4427dce38cda19678d055cfb076 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:21:42 +0100 Subject: [PATCH 07/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 00ad03aae..409c3780c 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ When forking the repository, remember to copy out all the branches. Then, work o Follow the steps below where you have to correctly fill up the signature `your-fork`: - Browse to https://github.com/your-fork/documentation/actions and enable the actions if they got disabled. - Browse to https://github.com/your-fork/documentation/actions/workflows/gh-pages.yml and click on the Run workflow button. -- Browse to https://github.com/your-fork/documentation/settings/pages, select Deploy from a branch button and then the `gh-pages` branch and wait until the GitHub Pages link becomes green to click on! +- Browse to https://github.com/your-fork/documentation/settings/pages, select Deploy from a branch button and then the couple `gh-pages` branch and `/root`; finally, wait until the GitHub Pages link becomes green to click on! # 🔽 Local Workflow From d8c42d1a047085d2e01ba32b82a5b0c01c3482e1 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:25:57 +0100 Subject: [PATCH 08/11] Update gh-pages.yml --- .github/workflows/gh-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 6e43fcf64..9dc8134f0 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -35,7 +35,7 @@ jobs: - name: Build Zensical run: | - zensical build + zensical build --clean - name: Create and prepare gh-pages anew run: | From 84edb2176ef6a1cd32281ac5f9bf9984b5ea6b97 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:26:19 +0100 Subject: [PATCH 09/11] Update test-pr.yml --- .github/workflows/test-pr.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-pr.yml b/.github/workflows/test-pr.yml index ac5659687..90bcc4c8c 100644 --- a/.github/workflows/test-pr.yml +++ b/.github/workflows/test-pr.yml @@ -19,7 +19,7 @@ jobs: - name: Build Zensical run: | - zensical build --strict > log 2>&1 + zensical build --cleana --strict > log 2>&1 - name: Print Log if: always() From 952c6e9ad8d874f95b7c6d0e4a7d4a9708c60781 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:26:26 +0100 Subject: [PATCH 10/11] Update test-pr.yml --- .github/workflows/test-pr.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-pr.yml b/.github/workflows/test-pr.yml index 90bcc4c8c..250ad6678 100644 --- a/.github/workflows/test-pr.yml +++ b/.github/workflows/test-pr.yml @@ -19,7 +19,7 @@ jobs: - name: Build Zensical run: | - zensical build --cleana --strict > log 2>&1 + zensical build --clean --strict > log 2>&1 - name: Print Log if: always() From 897a1a52f0ea200c2ff1f273623f1fdb7177c134 Mon Sep 17 00:00:00 2001 From: Ugo Pattacini Date: Sat, 20 Dec 2025 17:32:32 +0100 Subject: [PATCH 11/11] Update mkdocs.yml --- mkdocs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index cde22f2fe..cedb43537 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,7 +16,7 @@ theme: # Palette toggle for automatic mode - media: "(prefers-color-scheme)" toggle: - icon: material/brightness-auto + icon: lucide/sun-moon name: Switch to light mode # Palette toggle for light mode - media: "(prefers-color-scheme: light)" @@ -24,15 +24,15 @@ theme: primary: indigo accent: indigo toggle: - icon: material/brightness-7 + icon: lucide/sun name: Switch to dark mode # Palette toggle for dark mode - media: "(prefers-color-scheme: dark)" scheme: slate primary: indigo - accent: indigo + accent: orange toggle: - icon: material/brightness-4 + icon: lucide/moon-star name: Switch to system preference font: