 |
VOOZH | about |
|
VOOZH | about |
This document describes the architecture of the friendsofhyperf/components documentation website, which is built using VitePress and serves four locales (Simplified Chinese, Traditional Chinese Hong Kong, Traditional Chinese Taiwan, and English). The documentation covers the configuration system, multi-locale organization, content structure, and deployment workflow.
For information about the CI/CD pipeline that builds and deploys the documentation, see CI/CD Pipeline. For information about the overall monorepo structure, see Monorepo Architecture and Component Registry.
The documentation site is built on VitePress, a Vue.js-powered static site generator optimized for technical documentation. VitePress provides built-in features including Markdown rendering, Vue component support, theming, search, and internationalization.
The main configuration file docs/.vitepress/config.mts1-179 defines the site-wide settings:
| Configuration Key | Purpose | Value |
|---|---|---|
title | Site title | "Hyperf Fans" |
description | SEO description | "🚀 The most popular components for Hyperf." |
ignoreDeadLinks | Allow broken links during build | true |
sitemap.hostname | Sitemap generation | https://docs.hdj.me |
The configuration includes analytics integration via script tags in the head section docs/.vitepress/config.mts26-51:
hm.baidu.com) for Chinese market trackingclarity.ms) for user behavior analysisThe site uses the markdown-it-task-lists plugin docs/.vitepress/config.mts19-106 to enable GitHub-style task list rendering in Markdown files:
Sources: docs/.vitepress/config.mts1-179
The documentation site supports four locales with independent navigation, sidebar, and content hierarchies:
Diagram: Multi-Locale Configuration Structure
Each locale is defined in the locales object docs/.vitepress/config.mts52-100 with the following structure:
| Locale Key | Label | Language Code | Link Pattern |
|---|---|---|---|
root | "简体中文" | zh | / (default) |
zh-hk | "繁體中文（港）" | zh-hk | /zh-hk/index |
zh-tw | "繁體中文（臺）" | zh-tw | /zh-tw/index |
en | "English" | en | /en/index |
Each locale imports three separate modules:
Each locale receives its own themeConfig object docs/.vitepress/config.mts63-98 containing:
The root locale (Simplified Chinese) uses a different configuration pattern docs/.vitepress/config.mts110-177 where theme settings are defined at the top level rather than nested under themeConfig in the locale definition.
Sources: docs/.vitepress/config.mts52-100 docs/.vitepress/src/en/config.ts1-5 docs/.vitepress/src/en/nav.ts1-14
The navigation system uses VitePress's DefaultTheme.NavItem[] type. The English navigation docs/.vitepress/src/en/nav.ts3-12 demonstrates the structure:
Diagram: English Navigation Hierarchy
Navigation items support two types:
text and link propertiesitems array containing nested links, used for external resourcesWhile the sidebar configuration files are not provided in the file listing, the configuration imports show they follow a modular pattern:
cnSidebar from ./src/zh-cn/sidebars docs/.vitepress/config.mts9hkSidebar from ./src/zh-hk/sidebars docs/.vitepress/config.mts13twSidebar from ./src/zh-tw/sidebars docs/.vitepress/config.mts17enSidebar from ./src/en/sidebars docs/.vitepress/config.mts5The sidebar configuration uses VitePress's hierarchical structure to organize component documentation by category, mirroring the component catalog structure described in Component Catalog.
Sources: docs/.vitepress/src/en/nav.ts1-14 docs/.vitepress/config.mts1-179
The documentation site implements local search using VitePress's built-in search provider docs/.vitepress/config.mts128-166:
Diagram: Search System Architecture
The search system is configured with locale-specific translations docs/.vitepress/config.mts131-164:
| Locale | Button Text | No Results Text | Select Text | Navigate Text |
|---|---|---|---|---|
zh | "搜索文档" | "无法找到相关结果" | "选择" | "切换" |
en | "Search documents" | "No relevant results found" | "Select" | "Switch" |
The search index is generated at build time by parsing all Markdown files in the documentation directory. The local provider eliminates the need for external search services and provides instant search results without network latency.
Sources: docs/.vitepress/config.mts128-166
The default theme is customized with Chinese translations for UI elements docs/.vitepress/config.mts111-127:
| Feature | Configuration Key | Chinese Value | Purpose |
|---|---|---|---|
| Outline Label | outline.label | "页面导航" | Right sidebar heading |
| Outline Levels | outline.level | [2, 4] | Show H2-H4 headings |
| Edit Link Text | editLink.text | "在Github上编辑此页面" | GitHub edit button |
| Edit Link Pattern | editLink.pattern | github.com/.../docs/:path | Edit URL template |
| Last Updated | lastUpdated.text | "最后更新于" | Git timestamp label |
| Next Page | docFooter.next | "下一页" | Footer navigation |
| Previous Page | docFooter.prev | "上一页" | Footer navigation |
| Sidebar Menu | sidebarMenuLabel | "菜单" | Mobile menu label |
| Return to Top | returnToTopLabel | "回到顶部" | Scroll button |
The edit link pattern docs/.vitepress/config.mts116 enables direct editing:
https://github.com/friendsofhyperf/components/edit/main/docs/:path
The :path placeholder is automatically replaced with the relative path of the current page, allowing readers to contribute corrections directly via GitHub's web editor.
Sources: docs/.vitepress/config.mts110-127
The root home page docs/index.md1-50 uses VitePress's home page layout with the following structure:
Diagram: Home Page Content Structure
The home page showcases 10 featured components docs/index.md17-47 with title, description, and link. Each feature block is rendered as a card in the features grid. The hero section provides two primary calls-to-action:
Sources: docs/index.md1-50
The VitePress build process generates static HTML files from Markdown sources. The configuration enables several build-time optimizations:
sitemap.xml for SEO docs/.vitepress/config.mts107-109ignoreDeadLinks: true docs/.vitepress/config.mts25 to allow external links without validationBased on the context from CI/CD Pipeline, the documentation site is deployed through the release.yaml GitHub Actions workflow. The deployment process:
vitepress build docshttps://docs.hdj.meDiagram: Documentation Directory Structure
The docs/.vitepress/ directory docs/.vitepress/config.mts1 contains all VitePress configuration and theme customizations, while locale-specific content lives in top-level directories (en/, zh-cn/, etc.). Configuration modules are organized under .vitepress/src/<locale>/ for modularity.
Sources: docs/.vitepress/config.mts1-179 docs/index.md1-50
The documentation site integrates two analytics platforms via inline scripts in the HTML head docs/.vitepress/config.mts26-51:
Integrated via Baidu's hm.js script docs/.vitepress/config.mts31-38 Tracks:
The tracking ID df278fe462855b3046c941a8adc19064 is hardcoded in the configuration.
Integrated via Clarity's tracking script docs/.vitepress/config.mts43-49 Provides:
The project ID pgqv4ftymf is embedded in the script initialization.
Both scripts load asynchronously to minimize impact on page load performance.
Sources: docs/.vitepress/config.mts26-51
The documentation architecture follows a modular configuration pattern where each locale's settings are split into separate TypeScript files:
Diagram: Configuration Module Assembly Pattern
The main configuration docs/.vitepress/config.mts3-17 imports locale-specific modules:
These modules are then spread into locale definitions docs/.vitepress/config.mts86-99:
This pattern enables:
Sources: docs/.vitepress/config.mts1-179 docs/.vitepress/src/en/config.ts1-5 docs/.vitepress/src/en/nav.ts1-14
The friendsofhyperf/components documentation site architecture demonstrates a well-organized VitePress implementation with:
| Aspect | Implementation |
|---|---|
| Static Site Generator | VitePress with Vue.js |
| Localization | 4 locales with independent navigation/sidebar |
| Configuration | Modular TypeScript files per locale |
| Search | Local provider with build-time indexing |
| Analytics | Baidu Analytics + Microsoft Clarity |
| Deployment | GitHub Actions via release.yaml |
| Hosting | https://docs.hdj.me |
| Content Format | Markdown with YAML frontmatter |
The modular configuration system and comprehensive locale support make the documentation easily maintainable and scalable as the component library grows. The local search provider and analytics integration provide excellent user experience and usage insights.
Refresh this wiki