System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
HXLoLi is a technical knowledge base and software repository built on the Docusaurus framework. It integrates AI-driven documentation, automated sidebar generation, and a customized frontend layout to support technical notes, blog posts, and interactive anime/music modules. The system architecture prioritizes high-performance static asset delivery, modular AI skill sets, and strict code quality standards for both human and machine-readable content.
Sources: README.md:10-25, docusaurus.config.ts:1-10
1. Core Framework and Deployment Architecture
The system utilizes Docusaurus v3.7 as the primary static site generator. The configuration supports dual deployment targets: GitHub Pages and Cloudflare Workers.
1.1 Deployment Logic
The architecture handles base URLs dynamically to accommodate different hosting environments.
- GitHub Pages: Deploys to
/HXLoLibase path. - Cloudflare Workers: Deploys to a custom domain (e.g.,
km.woa.qzz.io) using a root base path.
Sources: docusaurus.config.ts:13-20, docusaurus.config.ts:250-255
1.2 Resource Management
The system enforces strict rules for static assets, particularly .drawio.svg files. The configuration disables URL loader inlining (limit set to 0) to prevent the loss of draw.io editor shells in metadata-rich SVG files.
Sources: docusaurus.config.ts:38-50
The diagram shows the content transformation flow from source markdown to deployment-specific static assets.
2. AI Documentation and Sidebar Pipeline
The project implements a specialized pipeline for AI-focused documentation located in the ai-docs/ directory. This is distinct from the standard docs/ folder.
2.1 Automated Sidebar Generation
A custom Node.js script, generateAiDocsSidebar.js, scans the ai-docs/ directory to build a structural sidebar.
- Icon Mapping: Folders and documents receive specific icons defined in
default-icons/ai-folder.svgandai-doc.svg. - Prefix Stripping: The script removes numerical prefixes (e.g.,
001-) from labels to maintain clean UI navigation while preserving filesystem ordering. - Tag Integration: It reads
tag.jsonwithin folders to inject custom metadata and icons into the sidebar items.
Sources: scripts/generateAiDocsSidebar.js:14-35, scripts/generateAiDocsSidebar.js:52-70
2.2 Content Stratification
Documentation is categorized into specific technical tiers, mirroring the Agent Skill hierarchy:
- L1 (Metadata): Name and description for quick triggers.
- L2 (Body): Main content limited to approximately 5,000 tokens for context efficiency.
- L3 (References): Supporting scripts, schemas, and long-form assets stored in
references/orscripts/.
Sources: ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:85-110
3. Frontend Architecture and Theme Customization
The frontend leverages React components to provide specialized layouts for different content types.
3.1 Conditional Layout Logic
The DocItemLayout component detects the page type via route matching. Pages under /knowledge-base activate the ai-kb-page CSS class and display an AIDocHeader.
- InlineEditor: Provides a direct link to the source file in VS Code for local development.
- MitemitePanel: A specialized panel for "answer cards" within the AI knowledge base.
Sources: src/theme/DocItem/Layout/index.tsx:61-75, src/theme/DocItem/Layout/index.tsx:82-95
3.2 Sidecar HTML Integration
The system allows .html files (such as PPT presentations) to reside alongside markdown files. A custom Webpack plugin, pptHtmlAssetsPlugin, copies these assets to the corresponding build route, enabling #ppt iframe embeds.
Sources: docusaurus.config.ts:160-190, ai-docs/002-程序语言/003-Web前端/001-react-bits分门别类学习/index.md:15-20
4. Engineering Standards and Quality Gateways
The project defines strict architectural boundaries to maintain long-term stability and AI readability.
4.1 Directory and File Constraints
- File Length: Logic-heavy files (e.g., TypeScript/Python) are capped at 300 lines. Frontend UI files are capped at 500 lines.
- Directory Scale: A single directory should not exceed 6 files to prevent responsibility blurring.
- Imports: The system enforces "Directed Acyclic Graph" (DAG) dependencies. Cross-module imports must only target public interfaces, prohibiting direct access to
impl/directories.
Sources: blog/2026/10/07/01-AI代码质量.md:65-85, blog/2026/10/07/01-AI代码质量.md:144-156
4.2 Architecture Summary Table
| Component | Responsibility | Constraints |
|---|---|---|
| Docusaurus Config | Core routing and plugin management | trailingSlash: false, onBrokenLinks: warn |
| scripts/generateDocs | Sidebar automation for ai-docs | Strips numeric prefixes, maps SVG icons |
| DocItemLayout | Frontend UI context switching | Injects AIDocHeader for knowledge base paths |
| Code Quality Hooks | Linting and custom AST rules | No local imports, 120 char line limit |
| Agent Skills | AI-readable instruction sets | 3-tier context budgeting (L1-L3) |
Sources: docusaurus.config.ts:250-300, blog/2026/10/07/01-AI代码质量.md:160-170, ai-docs/003-AI/005-Skill/002-Agent-Skill编写最佳实践/index.md:130-145
5. Implementation Patterns
5.1 Asset Copying Logic
The getPptHtmlCopyPatterns function maps physical directory structures to virtual routes to ensure presentations are accessible via clean URLs.
// docusaurus.config.ts:133-145
function getDocsMarkdownRoute(rootDir: string, markdownFile: string, routeBasePath: string): string {
const path = require('path') as typeof import('path');
const relativeFile = toPosixPath(path.relative(rootDir, markdownFile));
const sourceDirName = path.posix.dirname(relativeFile);
const fileName = path.posix.basename(relativeFile, path.posix.extname(relativeFile));
const baseId = stripNumberPrefix(fileName);
const dirSlug = sourceDirName === '.' ? '' : stripPathNumberPrefixes(sourceDirName);
// ... returns formatted route
}
Sources: docusaurus.config.ts:133-156
5.2 Mermaid Diagram Architecture
The system utilizes @docusaurus/theme-mermaid but implements custom rendering to support complex block combinations.
Sources: docusaurus.config.ts:408-412
HXLoLi's architecture successfully bridges static documentation with dynamic AI agent requirements. By using directory-based automation and strict engineering gates, the system ensures that content remains both human-navigable and machine-processable.