docs(webpage): add a webpage/site README covering the pnpm/uv/zensical build and deploy contract
- Dominant language
- Rust
- Stars
- 467
- Forks
- 54
- Avg merge
- 4h 25m
- Merged PRs (30d)
- 310
Description
## Summary
The marketing/download site under `webpage/site/` has no README. Its dev/build/deploy contract lives only in Makefile recipes and a deploy script, and the `pnpm` / `uv` / `zensical` prerequisites are documented nowhere in prose.
## Background
Without a README, a contributor has to reverse-engineer the build from the Makefile and `deploy_webpage.sh` to learn that the build is a static export, that the bundled manual needs `uv run zensical build` before `pnpm build`, and that the deploy force-pushes to another repo's `gh-pages`.
## Proposed Solution
Write `webpage/site/README.md` covering prerequisites, the Makefile entry points, the `docs-guard` caveat, and the deploy destination. Optionally align a title-spelling drift and refresh a stale model count in the same PR.
## Implementation Notes
- `webpage/site/` has `package.json`, `next.config.ts`, `app/`, `components/`, `dictionaries/` and no `README.md` (nor `webpage/README.md`). Confirmed absent.
- `webpage/site/package.json` scripts are only `dev` / `build` / `start` / `lint`; nothing says the build is a static export consumed from `out/`.
- `Makefile:954-967` (`webpage-dev` / `webpage-build`, the latter `docs-guard`-gated and requiring `uv run zensical build -f mkdocs.yml -d webpage/site/public/en/manual` before `pnpm build`), `:978` (`webpage-deploy`).
- `grep -rn "zensical\|pnpm\|uv run" docs/*.md README.md CONTRIBUTING.md` returns no matches.
- `scripts/deploy_webpage.sh:20-25` force-pushes `webpage/site/out` to `lablup/mlxcel-releases` `gh-pages`.
- Optional drift: deploy script fallback title uses `mlxcel - High-Performance...` while the site layouts use `mlxcel | High-Performance...`; both say "60+ LLM and VLM models" while `ALL_MODEL_TYPES` (`src/models/mod.rs:641`) now has 173 entries.
## Acceptance Criteria
- [ ] `webpage/site/README.md` documents prerequisites, build entry points, and deploy destination.
- [ ] (Optional) title-spelling drift and the stale "60+" count are addressed or split into a follow-up.
---
## Original Suggestion
### Title: docs(webpage): add a webpage/site README covering the pnpm/uv/zensical build and deploy contract
The marketing/download site under `webpage/site/` has no README: its dev/build/deploy contract lives only in Makefile recipes and a deploy script, and the `pnpm`/`uv`/`zensical` prerequisites are documented nowhere in prose.
## Evidence
- `webpage/site/` has `package.json`, `next.config.ts`, `app/`, `components/`, `dictionaries/` … and no `README.md` (nor `webpage/README.md`)
- `webpage/site/package.json:5-10` — scripts are only `dev`/`build`/`start`/`lint`; nothing says the build is a static export consumed from `out/`
- `Makefile:954-967` — `webpage-dev` / `webpage-build` (the latter `docs-guard`-gated and requiring `uv run zensical build -f mkdocs.yml -d webpage/site/public/en/manual` before `pnpm build`), `:978` `webpage-deploy`
- `grep -rn "zensical\|pnpm\|uv run" docs/*.md README.md CONTRIBUTING.md` → no matches
- `scripts/deploy_webpage.sh:20-25` — force-pushes `webpage/site/out` to `lablup/mlxcel-releases` `gh-pages`; nothing outside the script says where the site lands
Existing drift worth fixing in the same PR: the deploy script's fallback title uses `mlxcel - High-Performance…` (`scripts/deploy_webpage.sh:37,44,54`) while the site layouts use `mlxcel | High-Performance…` (`webpage/site/app/(root)/layout.tsx:16,44,58`, `app/[lang]/layout.tsx:20,48,62`); and both say "60+ LLM and VLM models" while `ALL_MODEL_TYPES` (`src/models/mod.rs:641`) now has 173 entries.
## Suggested fix
Write `webpage/site/README.md`: prerequisites (Node/pnpm, `uv`+`zensical` for the bundled manual), the three Makefile entry points, the `docs-guard` caveat (manual sources live in a separate tree — `docs/README.md:47-62`), and the deploy target repo/branch. Optionally align the title spelling and refresh the model count.
## Acceptance criteria
- [ ] `webpage/site/README.md` documents prerequisites, build entry points, and deploy destination
- [ ] (Optional) title-spelling drift and the stale "60+" count are addressed or split into a follow-up
Contributor guide
Research direction
Read Makefile:954-967 and :978, then scripts/deploy_webpage.sh:20-25 to confirm the site prerequisites, build sequence, docs-guard caveat, output directory, and deploy destination. Add webpage/site/README.md covering those items; done means the acceptance criteria are documented, with optional title and model-count drift handled separately or explicitly included.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 86/100