Blog and AI Docs System
Relevant source files
The following files were used as context for generating this wiki page:
The Blog and AI Docs System manages two distinct content streams within the HXLoLi project. The system integrates a standard Docusaurus blog for human-authored posts and a specialized "AI Docs" knowledge base for AI-assisted or generated technical documentation. The AI Docs system includes custom metadata tracking, automated sidebar generation, and specialized UI components for managing AI-specific attributes such as model versions and skill injections.
Sources: docusaurus.config.ts:340-410, README.md:1-20
System Architecture
The project utilizes Docusaurus as the core engine, configured with multiple instances of the content-docs plugin to separate standard notes from the AI knowledge base.
The diagram shows the logical separation of content sources and the automation script used for the AI Docs sidebar.
Sources: docusaurus.config.ts:333-410, scripts/generateAiDocsSidebar.js:12-20
Content Separation
The system distinguishes content via directory structure and Docusaurus plugin IDs:
- Blog: Located in
blog/, managed by the default Docusaurus blog plugin. Sources: docusaurus.config.ts:375-400 - Standard Notes: Located in
docs/, serves as general personal notes. Sources: docusaurus.config.ts:348-374 - AI Knowledge Base: Located in
ai-docs/, uses the plugin IDai-docsand a custom route base path/knowledge-base. Sources: docusaurus.config.ts:413-435
AI Docs Metadata and UI
AI Docs pages feature a specialized header (AIDocHeader) that displays metadata derived from Markdown frontmatter.
AIDocHeader Components
The AIDocHeader component renders technical details about the AI generation process:
- Creation Date: The
created_atfield from frontmatter. - AI Model: The specific model used (e.g.,
DeepSeek-V4-Flash). - Skills: Links to specific AI skills (stored in
.agents/skills/) used to generate the content. - Tags: Thematic labels for indexing.
Sources: src/components/AIDocHeader/index.tsx:32-60, ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md:1-10
Metadata Configuration Table
| Frontmatter Key | Type | Description |
|---|---|---|
hxid | string | Unique identifier for the document. |
title | string | Document title. |
created_at | string (ISO) | Original creation date. |
model | string | AI model responsible for the content. |
skill | string[] | Array of skill IDs injected into the AI context. |
tags | string[] | Topic categories for the document. |
Sources: ai-docs/003-AI/004-记忆/003-obsidian-second-brain/index.md:1-9, src/components/AIDocHeader/index.tsx:45-55
Sidebar Automation
The AI Docs system uses scripts/generateAiDocsSidebar.js to automatically build the navigation structure based on the filesystem.
Generation Logic
- Prefix Stripping: The script removes numerical prefixes (e.g.,
001-) from directory and file names to create clean labels. - Icon Mapping: It assigns icons based on folder content or specific
tag.jsonconfigurations. Folders default toai-folder.svgand documents toai-doc.svg. - Category Linking: If a directory contains an
index.mdorindex.mdxfile, the script treats the category as a clickable link.
Sources: scripts/generateAiDocsSidebar.js:23-40, scripts/generateAiDocsSidebar.js:46-95
Automated Data Flow
The sequence diagram illustrates how filesystem changes are reflected in the site's navigation without manual sidebar editing.
Sources: scripts/generateAiDocsSidebar.js:42-105
Layout and Routing
The DocItemLayout component differentiates between standard notes and AI Docs using the browser's location path.
Routing Logic
If the location pathname includes /knowledge-base, the layout activates "AI Knowledge Base" mode (isAIDocs). This triggers specific behaviors:
- Header Injection: The
AIDocHeaderis prepended to the article. - MitemitePanel: A specialized panel for specific documents is displayed.
- Styling: The CSS class
ai-kb-pageis applied to the root row for AI-specific theme overrides.
Sources: src/theme/DocItem/Layout/index.tsx:55-75, src/theme/DocItem/Layout/index.tsx:82-90
Blog Specifications
The blog system follows strict standards for technical quality and AI context.
Quality Standards
The project defines "Error" and "Warning" levels for blog and documentation content:
- Errors: Clear issues detected by linting tools or AST analysis (e.g., missing return types).
- Warnings: Content requires manual review, such as the introduction of new third-party libraries.
- Formatting: Mandatory 120-character line length and 4-space indentation.
Sources: blog/2026/10/07/01-AI代码质量.md:30-50, blog/2026/10/07/01-AI代码质量.md:120-135
Documentation Taxonomy
The project organizes documents into specific directories within docs/:
tutorials/: Procedural guides.reference/: Current system state and API contracts.architecture/: High-level design.decisions/: Rationale for design choices.archive/: Deprecated content.
Sources: blog/2026/10/07/01-AI代码质量.md:190-210
The Blog and AI Docs system ensures that large volumes of technical information remain navigable through automated sidebar generation and consistent metadata tagging. The integration of AIDocHeader and specialized routing allows the HXLoLi site to maintain a clear distinction between personal blog posts and a structured AI-managed knowledge base.