onixbyte/onixbyte.com
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: pin toolchain and add type checking

Browse Source 
- Pin TypeScript as a direct dependency. It was only present transitively
  via typescript-eslint, so nothing enforced tsconfig.json and nine
  latent type errors had gone unnoticed.
- Add `pnpm typecheck` (`tsc --noEmit`) and document it.
- Add .npmrc with engine-strict, so the declared Node and pnpm ranges
  are actually enforced.
- Ignore doc_build/ in ESLint. It was unignored and reported 1650 errors
  from build output, which made lint unusable as a gate.
- Refresh README, CLAUDE.md, AGENTS.md and CONTRIBUTING.md to match the
  current structure, build targets and navigation rules.
This commit is contained in:
zihluwang committed 2026-09-25 14:48:25 +08:00
1 parent 38b94ba964
commit 29f7411da5
8 files changed
+490 -143
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+120 -17
View File
@@ -1,47 +1,150 @@
# OnixByte Homepage
The official OnixByte site — a central hub for technical blogs, project documentation, and development standards.
The official OnixByte site — the company front door, alongside the technical
blog, product documentation and development standards.
## Tech Stack
A static documentation site built with [Rspress](https://rspress.dev/), supporting bilingual content (`en-gb` / `zh-hans`). All pages are authored in Markdown / MDX.
A static site built with [Rspress](https://rspress.rs/), supporting bilingual
content (`en-gb` / `zh-hans`). All pages are authored in Markdown / MDX.
## URLs
| Domain | Recommended For |
|--------------------------------------------------|--------------------------------|
| [onixbyte.cn](https://onixbyte.cn) | Users in China mainland |
| [onixbyte.com](https://onixbyte.com) | Users outside China mainland |
| Domain | Recommended For |
| ------------------------------------ | ---------------------------- |
| [onixbyte.cn](https://onixbyte.cn) | Users in China mainland |
| [onixbyte.com](https://onixbyte.com) | Users outside China mainland |
Traffic from mainland China is redirected from `.com` to `.cn` at the edge; see
`vercel.json`. Local full-text search is built into Rspress v2 and needs no
plugin — an index is emitted per locale at build time.
## Requirements
- Node.js 24.x (see `engines` in `package.json`)
- pnpm 12.x — the package manager is pinned via the `packageManager` field
## Local Development
```bash
pnpm install
pnpm dev # Start dev server with HMR
pnpm build # Production build, outputs to dist/
pnpm build # Production build for .com, outputs to doc_build/
pnpm build:com # Explicit .com build (same as `build`)
pnpm build:cn # Production build for .cn
pnpm preview # Preview the production build locally
pnpm lint # ESLint
pnpm typecheck # TypeScript, no emit
pnpm format # Prettier — format all files
```
## Build Targets
The site is published on two domains, and the two builds are not
interchangeable. `pnpm build:cn` runs `rspress build --config
rspress.cn.config.ts`, which differs from the default in three ways:
| | `build:com` | `build:cn` |
| ------------------------------- | ----------------- | -------------- |
| Canonical, `hreflang`, `og:url` | `onixbyte.com` | `onixbyte.cn` |
| `sitemap.xml`, `robots.txt` | `onixbyte.com` | `onixbyte.cn` |
| Social links | GitHub, Douyin, X | GitHub, Douyin |
X is omitted from the `.cn` build because it is not reachable from mainland
China. Which links count as domestic is a single list in `rspress.config.ts`
(`SOCIAL_LINKS`) — move an entry between the two arrays to change a build.
Rspress ships preset icons for Weibo, Bilibili, Zhihu, Juejin, QQ and WeChat,
but not for Douyin, and its preset registry cannot be extended from userland.
Douyin's artwork is therefore supplied as inline SVG in
`theme/lib/social-icons.ts`; see that file for the markup shape it must match.
`robots.txt` is written at build time by a small plugin rather than committed
under `docs/public/`, because a single static file would carry the wrong origin
for one of the two targets.
**Both targets write to `doc_build/`.** Build and deploy them one at a time; a
second build overwrites the first. To preview the `.cn` variant in dev, run
`rspress dev --config rspress.cn.config.ts`.
## Directory Structure
```
docs/
├── public/ # Static assets (logos, icons, etc.)
├── en-gb/ # English content
│ ├── blogs/ # Technical blog posts
│ ├── projects/ # Project documentation
│ └── notifications/ # Announcements
└── zh-hans/ # Simplified Chinese content
├── blogs/
├── projects/
└── notifications/
├── public/ # Static assets served from the site root
│ └── onixbyte-*.svg
├── en-gb/ # English content (default locale, no URL prefix)
│ ├── _nav.json # Top navigation; labels are i18n keys
│ ├── index.md # Marketing homepage
│ ├── blogs/ # Technical articles ("Insights")
│ ├── products/ # Products we run ourselves
│ ├── services/ # Custom engineering services
│ ├── opensource-projects/ # Open-source project documentation
│ ├── notifications/ # Company announcements ("News")
│ └── legal/ # Privacy policy and terms
└── zh-hans/ # Simplified Chinese content (mirrors en-gb exactly)
theme/ # Custom Rspress theme
├── index.tsx # Layout overrides and slot wiring
├── index.css # Brand colours and section styling
├── lib/
│ ├── site.ts # Shared site constants
│ └── social-icons.ts # Inline SVG for social links with no preset icon
└── components/
├── Author.tsx # Byline, rendered from `author` frontmatter
├── Tags.tsx # Tag list, rendered from `tags` frontmatter
├── Kbd.tsx # Keyboard-shortcut primitive for MDX
├── SiteFooter.tsx # Site-wide footer, injected via the Layout slot
├── HomeSections.tsx # Renders `frontmatter.sections`
└── sections/ # The individual marketing band components
```
### Navigation and sidebars
Navigation and sidebar structure are driven by JSON files next to the content,
not by the theme:
- `_nav.json` controls the top navigation. Its `text` values are keys resolved
through `i18n.json`, which is why the two locale files are identical.
- `_meta.json` controls sidebar grouping and ordering within a directory.
Pages omitted from one are dropped from the sidebar, so keep it complete.
Do not add a `_meta.json` at the root of a locale directory — presence of both
`_nav.json` and `_meta.json` at that level switches Rspress to a single flat
sidebar and discards all the per-section ones.
### Marketing sections
The homepage, `/products/` and `/services/` render optional bands declared in
frontmatter under a `sections` key. Each band renders only when it has content,
so an unfilled page degrades to its heading and intro rather than looking
broken. Supported types are `advantages`, `contentGrid`, `techStack`, `cases`
and `cta`; see `theme/components/sections/types.ts` for their shapes.
`theme/components/sections/placeholder.ts` exposes a `SHOW_COPY_PLACEHOLDERS`
flag that renders a labelled outline for empty bands while copy is being
written. It must be `false` in anything released.
## Deployment
Pushing to the `main` branch triggers a GitHub Actions workflow that builds the site and deploys it to GitHub Pages.
Two targets, each built separately:
- **`onixbyte.com`** — built with `pnpm build:com`, deployed to Vercel from
`doc_build/`.
- **`onixbyte.cn`** — built with `pnpm build:cn`, rsynced from `doc_build/` to
the server behind that domain.
There is currently no CI automation in this repository; both are run by hand.
Since the two builds share the `doc_build/` output directory, run the build for
a target immediately before deploying it.
The server behind `onixbyte.cn` needs a `try_files` rule resolving extensionless
paths (`{path} {path}.html {path}/index.html`) — the sitemap and canonical URLs
are extensionless, and without it every one of them 404s on that host.
Redirects for the retired `/projects/` paths live in `vercel.json`. The `.cn`
host needs the equivalent rule in its own web server config, which is not
tracked in this repository.
## Licence