Appearance

wayscloud-docs ​

The VitePress site behind docs.wayscloud.services — the customer-facing documentation for all WAYSCloud services.

What is in here ​

  • Hand-written pages: guide/, build/, compare/, integrations/, index.md, trust-center.md.
  • Generated pages: api/ (API reference per tag) and services/ (service pages). These are written by the sync from the public_docs database and the OpenAPI spec — do not hand-edit them, they get overwritten.
  • public/ — static assets, the OpenAPI spec and generated data.
  • .vitepress/ — VitePress config (config.mts, SEO/structured data) and the built output in .vitepress/dist/.

Build and deploy ​

The site is built and deployed on the docs server (217.170.195.55) from the checkout at /var/www/docs.wayscloud.services:

bash
# full pipeline: fetch OpenAPI, validate, sync docs, generate API pages, build, sitemap, leak scan
bash scripts/build.sh

# build only
npx vitepress build

build.sh is also triggered by provision-api after a publish. Nginx serves .vitepress/dist (HTML Cache-Control: no-store, hashed assets immutable).

How content flows ​

Console / doc generator ─▶ public_docs (DB) ─export─▶ scripts/sync-docs.py ─▶ *.md in this repo
        ▲                                                                          │
        │                          daily 04:15: inject pricing + API examples, then build
        │                                                                          │
        └────────── scripts/sync_docs_from_vitepress.py ◀── markdown ◀─────────────┘   (04:30, provision-api)
  • Editorial source of truth is the public_docs table (edited in the console at /docs/public).
  • Build source of truth is this checkout.
  • scripts/sync-docs.py writes one .md per exported slug; scripts/sync_docs_from_openapi.sh injects API examples and pricing, then rebuilds VitePress; scripts/sync_docs_from_vitepress.py (in provision-api) imports the markdown back into the database.

Branch model ​

  • main is protected (pull request required, admins included). Hand-written changes land via PR.
  • docs-sync is a rolling, machine-pushed branch. The nightly sync force-pushes the generated api//services/ changes there and resets the local main, so the deploy checkout never drifts from origin/main. A timer on the provision-api host keeps an open pull request from docs-sync to main; merging publishes the generated content.

Pitfalls ​

  • Never edit api/ or services/ by hand — the sync overwrites them. Add or change services through the doc generator / console instead.
  • A page must never be published under <category>/<slug> of another page (e.g. build-flows/build/create-dns-zone next to build/create-dns-zone); that shape duplicated build/, compare/ and integrations/, and blocked search indexing (provision-api#1245). app/public_docs_dedupe.py guards against it, and nginx 301s the legacy paths to the canonical pages.

See also ​

  • Internal record: provision-api docs/en/26-public-docs-platform.md (rendered at the console under Docs).

Last updated: