Getting Started

Installation

Prerequisites

• Node.js version 18 or higher.
• Terminal for accessing VitePress via its command line interface (CLI).
• VSCode is recommended, along with the official Vue extension.

After you have cloned UI5 VitePress, you need to install the dependencies using:

npm install

Up and Running

You can use the following npm scripts inside your package.json:

{
  ...
  "scripts": {
    "dev": "vitepress --open",
    "build": "vitepress build",
    "preview": "vitepress preview --port 8080",
    "deploy": "cf push"
  },
  ...
}

Script	Description
dev	Start a local dev server running at http://localhost:5173 with instant hot updates.
build	Build the VitePress site for production (SSR to ./site).
preview	Locally preview the ./site production build.
deploy	Deploy it to SAP BTP Cloud Foundry (or Other Platforms) depending on the settings inside the manifest.yaml.

SAP BTP Deployment

Prerequisite

Make sure to Log in with the CLI to your Cloud Foundry instance:

cf login -a API-URL -u USERNAME -p PASSWORD -o ORG -s SPACE

Deploy your builded site directory to SAP BTP CloudFoundry using the following manifest.yaml file leveraging the Staticfile buildpack:

---
applications:
- name: ui5-vitepress
  path: .
  memory: 32M
  disk_quota: 128M
  buildpacks:
    - staticfile_buildpack

Memory usage

NGINX requires 20 MB of RAM to serve static assets. When using the Staticfile buildpack, Cloud Foundry push the apps with the -m 64M option to reduce RAM allocation from the default 1 GB that are allocated to containers by default.

The file ./cfignore controls, which files should be excluded from CF upload:

# folder
.vitepress/
.vscode/
node_modules/
src/

# files
.gitignore
LICENSE
odata2ts.config.ts
package-lock.json
package.json
postcss.config.ts
README.md
tailwind.config.js
tsconfig.json

# OSX
.DS_Store
.AppleDouble
.LSOverride

The Staticfile configuration inside the file Staticfile offers options for the NGINX server setup:

root: site
#enable_http2: enabled // (only if using a custom domain!)
location_include: includes/*.conf
force_https: true
http_strict_transport_security: true
http_strict_transport_security_include_subdomains: true
server_tokens: off
ssl_protocols: TLSv1.2 TLSv1.3

VS Code Extensions

This project comes with extension recommendations, that are very helpful:

Extension	Description
Vue.volar	Language support for Vue 3.
bradlc.vscode-tailwindcss	Intelligent Tailwind CSS tooling for VS Code.
humao.rest-client	REST Client for Visual Studio Code.
jebbs.plantuml	Rich PlantUML support for Visual Studio Code.
terrastruct.d2	Support for .d2 files.
joaompinto.vscode-graphviz	GraphViz (dot) language support for Visual Studio Code.

File Structure

The following file structure is used, where docs are lcoated inside (./src).

The srv directory is considered the project root of the VitePress site. The .vitepress directory is a reserved location for VitePress' config file, dev server cache, build output, and optional theme customization code.

.
├─ .vitepress
│  ├─ cache
│  ├─ syntaxes
│  │  └─ <TextMateGrammar>.tmLanguage.json
│  ├─ theme
│  │  ├─ components
│  │  │  ├─ Badgen.vue
│  │  │  ├─ ToDo.vue
│  │  │  ├─ ToDoItem.vue
│  │  │  └─ ToDoList.vue
│  │  │  └─ Trippin.vue
│  │  ├─ mixins
│  │  │  ├─ u-zoom-vanilla.js
│  │  │  └─ UI5WebComponentsMixin.js
│  │  ├─ custom.css
│  │  └─ index.ts
│  └─ config.js
├─ src
│  ├─ guide
│  │  └─ <Guide>.md
│  ├─ public
│  ├─ about.md
│  └─ index.md
├─ .cfignore
├─ manifest.yaml
├─ package.json
├─ postcss.config.js
├─ Staticfile
├─ tailwind.config.js
└─ package.json