Build and Utility Scripts
Relevant source files
The following files were used as context for generating this wiki page:
Build and Utility Scripts automate the maintenance, content organization, and deployment workflows of the HXLoLi project. These scripts manage the conversion of physical directory structures into Docusaurus navigation elements, track content metrics, and orchestrate Git operations.
Sidebar Generation Logic
The project uses automated scripts to generate sidebar configurations for both standard documentation and AI-specific documentation. This ensures that the navigation menu matches the file system without manual updates.
Recursive Directory Scanning
The generateAiDocsSidebar.js and generateSidebar.js scripts scan the ai-docs/ and docs/ directories respectively. The core logic resides in a recursive scanDocs function that identifies directories and Markdown files while ignoring hidden files starting with a dot.
Sources: scripts/generateAiDocsSidebar.js:12-42, scripts/generateAiDocsSidebar.js:46-55
Label and ID Processing
To create clean navigation labels, the scripts strip numeric prefixes from folder and file names using a regular expression. For example, a folder named 001-Introduction is displayed as Introduction.
Sources: scripts/generateAiDocsSidebar.js:18-20
Metadata and Icon Integration
The scripts look for a tag.json file within each folder to extract custom icons and tags. If no custom icon is found, the system assigns a default AI folder or document icon.
Sources: scripts/generateAiDocsSidebar.js:14-16, scripts/generateAiDocsSidebar.js:22-38
The diagram shows the recursive flow of scanning the document directories and transforming file system metadata into sidebar items.
Sources: scripts/generateAiDocsSidebar.js:46-103
Deployment Orchestration
The push.sh script acts as the primary orchestrator for preparing the project for deployment and committing changes to the repository.
Pre-deployment Cleanup
The script checks for a sibling directory ../HXLoLi-imouto. If present, it runs a cleanup command to remove private plain text files that might have remained from local development.
Sources: push.sh:8-12
Automated Build Steps
The deployment process follows a specific sequence of actions:
- Sidebar Update: Executes both
generateSidebar.jsandgenerateAiDocsSidebar.jsto refresh navigation. - Statistics Generation: Runs
count-md-words.tsusingts-nodeto generate word count statistics for thedocs/blogandai-docssections. - Git Operations: Adds all changes, commits with a user-provided message (or a default message if empty), and pushes to the origin repository.
Sources: push.sh:15-32
| Action | Command/File | Purpose |
|---|---|---|
| Cleanup | npm run clean:private | Removes sensitive or temporary local files. |
| Sidebar | node ./scripts/generateSidebar.js | Generates standard documentation sidebar. |
| AI Sidebar | node ./scripts/generateAiDocsSidebar.js | Generates AI documentation sidebar. |
| Stats | npx ts-node ./scripts/count-md-words.ts | Calculates Markdown word counts for reports. |
| Git Push | git push origin | Uploads committed changes to GitHub. |
Sources: push.sh:15-33
Docusaurus Integration
The build system integrates these scripts through the docusaurus.config.ts file, which defines how the generated assets are used in the final site build.
Sidebar Loading
Docusaurus is configured to load the AI-specific sidebar from the sidebarsAiDocs.ts file generated by the utility scripts. This plugin instance is separate from the standard documentation plugin.
Sources: docusaurus.config.ts:294-297, docusaurus.config.ts:316-320
PPT Asset Management
A custom plugin called pptHtmlAssetsPlugin handles HTML files intended for use in slides (PPT). It uses a glob pattern (**/*.html) to find HTML files in the docs, ai-docs, and blog directories and copies them to the build output while maintaining a mapping to their corresponding Markdown routes.
Sources: docusaurus.config.ts:221-252
The sequence diagram illustrates the automated workflow triggered by the deployment script.
Sources: push.sh:15-32
Content Metrics
The project tracks Markdown word counts to monitor the growth of the knowledge base. The count-md-words.ts utility specifically differentiates between standard documentation/blog content and the AI documentation repository.
Sources: scripts/count-md-words.ts:1-20, push.sh:22-31
Summary
The build and utility scripts provide a robust automation layer for the HXLoLi project. By automating navigation generation and deployment preparation, they ensure technical consistency and reduce manual configuration errors during the site's lifecycle.