docs: Enable documentation ci

.github/workflows/deploy-vitepress-docs.yaml

@@ -0,0 +1,101 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+name: Deploy VitePress site to gh-pages
+
+on:
+    push:
+        branches: [main]
+    workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+    contents: write
+    pages: write
+    id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+    group: pages
+    cancel-in-progress: false
+
+jobs:
+    # Build job
+    deploy-docs:
+        runs-on: ubuntu-24.04
+        env:
+            DOC_VERSION: v5 # The directory in gh-pages where the documentation would be deployed
+            DOC_ALIAS: next # Change this to update the alias route. Note: Check the old alias when changing this!
+            GIT_COMMITTER_NAME: "OpenUI5 Bot"
+            GIT_COMMITTER_EMAIL: "[email protected]"
+            GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v5
+              with:
+                  fetch-depth: 0
+            - name: Setup Node
+              uses: actions/setup-node@v6
+              with:
+                node-version: 22.20.0
+                cache: npm
+            - name: Setup Pages
+              uses: actions/configure-pages@v4
+            - name: Install dependencies
+              run: npm ci --engine-strict # --engine-strict is used to fail-fast if deps require node versions unsupported by the repo
+            - name: Install documentation dependencies
+              working-directory: packages/documentation
+              run: npm ci --engine-strict # --engine-strict is used to fail-fast if deps require node versions unsupported by the repo
+            - name: Fetch gh-pages branch
+              run: git fetch origin gh-pages --depth=1
+            - name: generate CLI doc
+              working-directory: packages/documentation
+              run: npm run generate-cli-doc
+            - name: Build vitepress build
+              working-directory: packages/documentation
+              run: |
+                # The base output
+                npm run build:vitepress -- --base="/${{ github.event.repository.name }}/${DOC_VERSION}/"
+                npm run build:assets -- ./dist
+                # The alias output
+                npm run build:vitepress -- --base="/${{ github.event.repository.name }}/${DOC_ALIAS}/" --outDir="dist-${DOC_ALIAS}"
+                npm run build:assets -- ./dist-${DOC_ALIAS}
+            - name: Build jsdoc
+              working-directory: packages/documentation
+              run: npm run jsdoc-generate
+            # TODO: Skip for now deployment of the schema until we do a Schema Version 5 release
+            # - name: Build Schema
+            #   run: |
+            #       npm run schema-generate
+            #       npm run schema-workspace-generate
+            - name: Checkout gh-pages
+              uses: actions/checkout@v5
+              with:
+                  ref: gh-pages
+                  path: gh-pages
+            - name: Copy the additional resources to gh-pages
+              run: |
+                  # TODO: Skip for now deployment of the schema until we do a Schema Version 5 release
+                  # rm -rf ./gh-pages/schema
+                  # cp -R ./site/schema ./gh-pages/
+                  rm -rf ./gh-pages/${DOC_VERSION}
+                  rm -rf ./gh-pages/${DOC_ALIAS}
+
+                  # Main version route
+                  cp -R ./packages/documentation/dist ./gh-pages/${DOC_VERSION}/
+
+                  # Alias route. E.g., next, latest, stable, etc.
+                  # For vitepress must be a copy with different config, not a symlink
+                  cp -R ./packages/documentation/dist-${DOC_ALIAS} ./gh-pages/${DOC_ALIAS}/
+                  # Symlink the api docs to avoid duplication
+                  ln -s ../${DOC_VERSION}/api ./gh-pages/${DOC_ALIAS}/api
+
+                  # TODO: Enable when v5 release is done
+                  # cp ./packages/documentation/scripts/resources/custom404.html ./gh-pages/404.html
+            - name: Publish Docs
+              run: |
+                  cd ./gh-pages
+                  git config --local user.email $GIT_COMMITTER_EMAIL
+                  git config --local user.name $GIT_COMMITTER_NAME
+                  git add .
+                  git commit -m "Updating supplemental resources for ${DOC_VERSION} documentation deployment"
+                  git push

.github/workflows/github-ci.yml

@@ -40,10 +40,14 @@ jobs:
       run: npm run coverage
 
     - name: Generate JSDoc documentation
-      run: cd packages/documentation && npm ci && npm run jsdoc-generate
+      working-directory: packages/documentation
+      run: |
+        npm ci
+        npm run jsdoc-generate
 
     - name: Generate merged JSON schema
       run: npm run schema-generate
 
     - name: Generate CLI documentation
+      working-directory: packages/documentation
       run: npm run generate-cli-doc

README.md

@@ -51,3 +51,6 @@ Please check our [Contribution Guidelines](https://github.com/UI5/cli/blob/main/
 ## Support
 
 Please follow our [Contribution Guidelines](https://github.com/UI5/cli/blob/main/CONTRIBUTING.md#report-an-issue) on how to report an issue. Or chat with us in the [`#tooling`](https://openui5.slack.com/archives/C0A7QFN6B) channel of the [OpenUI5 Community Slack](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com). For public Q&A, use the [`ui5-tooling` tag on Stack Overflow](https://stackoverflow.com/questions/tagged/ui5-tooling).
+
+## Kudos
+Thanks goes out for the amazing [UI5 VitePress|https://github.com/hschaefer123/ui5-vitepress] project offered by [Holger Schäfer|https://github.com/hschaefer123] on which the UI5 CLI documentation is based.

REUSE.toml

@@ -26,4 +26,10 @@ SPDX-License-Identifier = "Apache-2.0"
 path = "packages/builder/lib/processors/jsdoc/lib/**"
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2025 SAP SE or an SAP affiliate company and OpenUI5 contributors"
-SPDX-License-Identifier = "Apache-2.0"
+SPDX-License-Identifier = "Apache-2.0"
+
+[[annotations]]
+path = "packages/documentation/.vitepress/**"
+precedence = "aggregate"
+SPDX-FileCopyrightText = ["2019-present, Konrad Kost, Holger Schäfer, Yuxi (Evan) and VitePress contributors"]
+SPDX-License-Identifier = "MIT"

package.json

@@ -30,7 +30,6 @@
 		"coverage": "npm run coverage --workspaces",
 		"schema-generate": "node ./scripts/buildSchema.js ui5",
 		"schema-workspace-generate": "node ./scripts/buildSchema.js ui5-workspace",
-		"generate-cli-doc": "node ./scripts/generateCliDoc.js",
 		"depcheck": "depcheck --ignores @ui5/builder,@ui5/cli,@ui5/fs,@ui5/logger,@ui5/project,@ui5/server,local-web-server,@commitlint/config-conventional,husky && npm run depcheck --workspaces",
 		"check-licenses": "licensee --errors-only"
 	},
@@ -53,7 +52,6 @@
 		"eslint-plugin-ava": "^15.1.0",
 		"eslint-plugin-jsdoc": "^61.1.0",
 		"globals": "^16.4.0",
-		"handlebars": "^4.7.8",
 		"husky": "^9.1.7",
 		"licensee": "^11.1.1",
 		"local-web-server": "^5.4.0",

packages/documentation/.vitepress/config.ts

@@ -7,7 +7,8 @@ import MarkdownItImplicitFigures from "markdown-it-implicit-figures";
 
 export default defineConfig({
 
-  base: "/cli/v5/", // GitHub Pages deployment base path
+  // Would be set in CI job via CLI arguments. For local development, it's just root.
+  base: "/",
   srcDir: "docs",
   outDir: "dist",
   lang: "en-US",
@@ -104,17 +105,17 @@ function nav() {
       items: [
         {
           text: 'V4',
-          link: '../v4/',
+          link: `/../v4/`,
           target: "_self"
         },
         {
           text: 'V3',
-          link: '../v3/',
+          link: `/../v3/`,
           target: "_self"
         },
         {
           text: 'V2',
-          link: '../v2/',
+          link: `/../v2/`,
           target: "_self"
         }
       ]
@@ -274,7 +275,8 @@ function guide() {
     },
     {
       text: "API Reference",
-      link: "https://ui5.github.io/cli/api/index.html",
+      link: "/api/index.html",
+      target: "_blank"
 
     },
 

packages/documentation/docs/index.md

@@ -10,7 +10,7 @@ import VPButton from "vitepress/dist/client/theme-default/components/VPButton.vu
 const { isDark } = useData()
 </script>
 
-<img :src="isDark ? '/cli/v5/images/O_UI5_H_noBG.png' : '/cli/v5/images/UI5_logo_wide.png'" alt="UI5 logo" style="max-width: 100%; height: auto;">
+<img :src="isDark ? './images/O_UI5_H_noBG.png' : './images/UI5_logo_wide.png'" alt="UI5 logo" style="max-width: 100%; height: auto;">
 
 # UI5 CLI