docs: harden documentation integrity

Author: kevinten10

CLAUDE.md

@@ -14,8 +14,8 @@ This is the documentation website for **Capa** (Cloud Application API) - a Mecha
 
 ### Prerequisites
 
-- [Hugo](https://gohugo.io/installation/) (extended version, v0.88.1+ recommended)
-- [Node.js](https://nodejs.org/) and npm (for PostCSS/Autoprefixer)
+- [Hugo](https://gohugo.io/installation/) Extended `0.145.0`, or Docker
+- [Node.js](https://nodejs.org/) 22 and npm (for PostCSS/Autoprefixer)
 - Git submodules (for Docsy theme)
 
 ### Setup
@@ -25,30 +25,31 @@ This is the documentation website for **Capa** (Cloud Application API) - a Mecha
 git submodule update --init --recursive
 
 # Install npm dependencies
-npm install
+npm ci
+npm --prefix themes/docsy install
 ```
 
 ### Local Development
 
 ```bash
 # Run Hugo development server
-hugo server
+make dev
 
 # Run with draft content included
-hugo server -D
+./scripts/hugo.sh server -D
 
 # Run with live reload (default binds to localhost:1313)
-hugo server --bind 0.0.0.0
+make dev-all
 ```
 
 ### Build
 
 ```bash
 # Build the site (output goes to the ignored docs/ directory)
-hugo --gc
+make build
 
 # Build for production
-HUGO_ENV="production" hugo --gc
+make check
 ```
 
 The Makefile and npm scripts automatically use the pinned official Hugo
@@ -103,24 +104,25 @@ content/
 ### Key Configuration Details
 
 - **Base URL**: `https://capa.rxcloud.group/`
-- **GitHub repo links**: Point to `https://github.com/capa-cloud/capa`
-- **Search**: Uses Google Custom Search Engine (gcs_engine_id)
+- **Documentation source links**: Point to `https://github.com/capa-cloud/capa.io` on `master`
+- **Related product repository**: `https://github.com/capa-cloud/capa`
+- **Search**: Uses Docsy's offline Lunr index
 - **Syntax highlighting**: Uses Chroma with "tango" style
 - **Markdown engine**: Goldmark with unsafe HTML enabled
 
 ### Static Assets
 
 - **Images**: `content/images/` or page bundles
-- **Logo**: Configure in `assets/icons/logo.svg` (navbar_logo is currently false)
+- **Logo**: Configure in `assets/icons/logo.svg` (`navbar_logo` is enabled)
 - **Featured background**: `content/zh/featured-background.jpg`
 
 ### Deployment
 
 The site is deployed to GitHub Pages via GitHub Actions (`.github/workflows/deploy.yml`):
 
 1. Push to `master` triggers the workflow
-2. Hugo builds the site with `--gc --minify --destination docs`
-3. `peaceiris/actions-gh-pages@v3` deploys to the `gh-pages` branch
+2. Hugo builds the site with `--gc --minify --cleanDestinationDir --destination docs`
+3. `peaceiris/actions-gh-pages@v4` deploys to the `gh-pages` branch
 4. Custom domain: `capa.rxcloud.group` (configured via `static/CNAME`)
 
 ## Common Tasks

CONTRIBUTING.md

@@ -1,28 +1,48 @@
-# How to Contribute
+# Contributing to Capa Documentation
 
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
+Thank you for improving the Capa website and documentation. Contributions are reviewed through GitHub pull requests in [capa-cloud/capa.io](https://github.com/capa-cloud/capa.io).
 
-## Contributor License Agreement
+## Set up the site
 
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
+```bash
+git clone --recurse-submodules https://github.com/capa-cloud/capa.io.git
+cd capa.io
+npm ci
+npm --prefix themes/docsy install
+make dev
+```
 
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
+Hugo Extended `0.145.0` is preferred. If it is not installed, `scripts/hugo.sh` uses the pinned Docker image.
 
-## Code reviews
+## Make a documentation change
 
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+1. Create a branch from `master`.
+2. Edit the appropriate file under `content/zh/` or `content/en/`.
+3. Add the corresponding translation when the same workflow is available in both languages.
+4. Put unfinished pages behind `draft: true`; never publish Docsy template content.
+5. Use repository-relative links for files in this repository and canonical HTTPS links for external resources.
+6. Run `make check` before opening a pull request.
 
-## Community Guidelines
+For website code or build changes, also run:
 
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
+```bash
+npm test
+make build
+```
+
+## Pull request checklist
+
+- The page explains what the reader can accomplish and includes prerequisites where needed.
+- Commands and dependency versions match the source repositories.
+- All links and images resolve.
+- Chinese and English navigation remain usable.
+- Examples contain no credentials, private endpoints, customer data, or personal identifiers.
+- Generated `docs/`, `public/`, and `resources/` files are not committed.
+
+## Reporting problems
+
+Use [GitHub Issues](https://github.com/capa-cloud/capa.io/issues) for broken pages, incorrect examples, translation gaps, and build failures. Security-sensitive reports should not include secrets or exploit data in a public issue.
+
+## License
+
+By contributing, you agree that your contribution is licensed under the repository's [Apache License 2.0](LICENSE).

Makefile

@@ -39,10 +39,12 @@ deploy: check
 
 # Check for broken links
 link-check:
-	hugo server &
-	sleep 3
-	npx linkinator http://localhost:1313 --recurse --timeout 10000 || true
-	pkill -f "hugo server"
+	@./scripts/hugo.sh server --bind 127.0.0.1 --port 1313 >/tmp/capa-hugo.log 2>&1 & \
+	pid=$$!; \
+	trap 'kill $$pid 2>/dev/null || true' EXIT; \
+	sleep 3; \
+	npx --yes linkinator http://localhost:1313 --recurse --timeout 10000 \
+	  --skip '^https?://(?!(localhost|127\\.0\\.0\\.1):1313)'
 
 # Show help
 help:
@@ -54,6 +56,6 @@ help:
 	@echo "  make build      - Build production site (outputs to ignored docs/)"
 	@echo "  make check      - Validate the production site without writing output"
 	@echo "  make clean      - Remove build artifacts"
-	@echo "  make deploy     - Build and deploy to GitHub Pages"
-	@echo "  make link-check - Check for broken links"
+	@echo "  make deploy     - Validate and push master; CI builds and deploys Pages"
+	@echo "  make link-check - Crawl the local site and fail on broken links"
 	@echo "  make help       - Show this help message"