Setup & Installation
Relevant source files
The following files were used as context for generating this wiki page:
HXLoLi is a personal blog and technical documentation project built using the Docusaurus static site generator. It integrates features such as anime tracking, a global music player, and AI-driven documentation assets.
The setup process involves configuring a Node.js environment, managing dependencies via npm, and utilizing shell scripts to automate local development and deployment workflows.
Sources: README.md:1-20, docusaurus.config.ts:326-335
Prerequisites
Before installing the project, you must ensure your environment meets specific software version requirements. HXLoLi specifically requires Docusaurus version 3.7.0 and warns against using higher versions to maintain compatibility with custom plugins and components.
Environment Requirements
| Requirement | Version | Notes |
|---|---|---|
| Docusaurus | 3.7.0 | Higher versions are not supported |
| Node.js | 18 | Recommended runtime |
| npm | 10.7.0 | Local development environment standard |
| React | ^19.2.3 | UI Framework |
| TypeScript | ~5.6.2 | Language standard |
Sources: README.md:92-106
Local Installation
The installation process follows standard npm procedures coupled with specialized shell scripts for execution.
Installation Steps
- Clone the Repository: Obtain the source code from the GitHub repository.
- Install Dependencies: Execute
npm ito install all necessary packages defined inpackage.json. - Launch the Development Server: Run the
./run.shscript to start the Docusaurus development server. - Access the Site: Open a web browser and navigate to
http://localhost:3000/HXLoLi/.
Sources: README.md:108-116, run.sh:1-2
Execution Logic
The run.sh script provides a direct entry point for local previewing.
#!/bin/bash
npm run start
Sources: run.sh:1-2
The following diagram illustrates the local setup and execution flow:
This diagram shows the sequential steps required to move from a fresh clone to a running local instance.
Deployment & Updates
HXLoLi uses a specialized push.sh script to handle pre-commit tasks, metadata generation, and repository synchronization. This ensures that sidebars and word count statistics are updated before any code is pushed to the remote server.
The Push Workflow
When you run ./push.sh "commit message", the system performs the following actions:
- Private File Cleanup: Removes temporary private files if a private directory exists.
- Sidebar Generation: Executes Node.js scripts to scan directories and rebuild sidebars for standard docs and AI docs.
- Word Count Calculation: Runs a TypeScript utility to count words in Markdown files for the project's statistics.
- Git Operations: Stages changes, commits with the provided message, and pushes to the
originrepository.
Sources: push.sh:1-32
Push Script Logic
# scripts/generateSidebar.js and scripts/generateAiDocsSidebar.js are executed first
node ./scripts/generateSidebar.js
node ./scripts/generateAiDocsSidebar.js
# Git synchronization
git add .
git commit -m "$commit_message"
git push origin
Sources: push.sh:12-32
The sequence of events during a push is visualized below:
This sequence diagram details how the script orchestrates metadata generation before interacting with the version control system.
Configuration & Deployment Targets
The project configuration in docusaurus.config.ts dynamically adjusts the baseUrl and url based on the environment variable DEPLOY_TARGET. This allows the same codebase to be deployed to different hosting providers with different path requirements.
Deployment Configuration Table
| Target | Variable (DEPLOY_TARGET) | Base URL | URL |
|---|---|---|---|
| Cloudflare Workers | cloudflare | "" | https://km.woa.qzz.io |
| GitHub Pages | (Default) | "/HXLoLi" | https://HengXin666.github.io |
Sources: docusaurus.config.ts:14-20
Build Constraints
The configuration includes a "guardrail" to prevent improper builds. It requires the WEBPACK_URL_LOADER_LIMIT environment variable to be set to "0". This prevents small .drawio.svg files from being inlined as data URIs, which would cause them to lose their interactive editor shell.
Sources: docusaurus.config.ts:25-45
Summary
Setting up HXLoLi requires a specific Node.js and Docusaurus environment. The project relies on automated shell scripts (run.sh, push.sh) to manage the complexity of sidebar generation and environment-specific configurations. By strictly following the prerequisite versioning and using the provided scripts, you ensure the integrity of the documentation features and interactive components.
Sources: README.md:92-116, push.sh:1-10, docusaurus.config.ts:14-45