Docusaurus Theme Customization
Relevant source files
The following files were used as context for generating this wiki page:
Docusaurus Theme Customization in the HXLoLi project encompasses the visual styling, component overrides (swizzling), and structural enhancements applied to the standard Docusaurus classic preset. The system integrates custom CSS variables, Tailwind CSS, and specialized React components to distinguish between standard documentation, blog posts, and the AI-driven Knowledge Base.
The customization architecture relies on Docusaurus "swizzling" to wrap core layout components, allowing for conditional rendering of metadata headers, interactive developer tools, and relationship diagrams depending on the document type.
Sources: docusaurus.config.ts:394-444, src/theme/DocItem/Layout/index.tsx:1-50
Global Visual Configuration
The project defines its primary visual identity through a set of CSS variables and configuration parameters that override the Docusaurus defaults.
Theme Colors and Styling
The global theme color is set to a pink/magenta hue (#ff88ff), applied as the primary interactive color across the site. The dark mode specifically targets a background color of #121212.
Sources: src/css/custom.css:11-23
| Variable | Value | Description |
|---|---|---|
--ifm-color-primary | #ff88ff | Main branding and interactive color |
--ifm-background-color | #121212 | Background for dark mode |
prism.theme | oneDark | Code block theme for syntax highlighting |
Sources: src/css/custom.css:12, docusaurus.config.ts:517
Tailwind CSS Integration
The project incorporates Tailwind CSS as a utility-first framework. It is configured as a PostCSS plugin within docusaurus.config.ts and injected into the global style sheet.
Sources: docusaurus.config.ts:251-267, src/css/custom.css:6-10
Component Swizzling and Layouts
HXLoLi overrides core Docusaurus layout components to inject custom logic and UI elements.
DocRoot Layout Customization
The DocRootLayout component is swizzled to detect if a user is navigating the Knowledge Base. When the pathname includes /knowledge-base, the component injects the ai-kb-page class directly into the <html> element, enabling scoped CSS targeting for sidebars and navigation.
Sources: src/theme/DocRoot/Layout/index.tsx:21-36
DocItem Layout Architecture
The DocItemLayout provides a container for individual documents. It includes logic to differentiate between AI-generated knowledge and standard notes.
The DocItemLayout manages the conditional rendering of the AI metadata header and developer panels based on the route.
Sources: src/theme/DocItem/Layout/index.tsx:69-120
AI Knowledge Base Enhancements
Specialized components support the "AI-first" philosophy of the knowledge base, providing metadata that is typically absent in standard Docusaurus sites.
AIDocHeader Component
The AIDocHeader displays specific metadata extracted from the document's Frontmatter. It uses framer-motion for entrance animations and react-icons for metadata labeling.
Sources: src/components/AIDocHeader/index.tsx:1-12
Extracted Frontmatter Fields:
created_at: The date the document was generated.model: The specific AI model used for generation.skill: References to internal agent skills used for content creation.tags: Categorical labels for Chinese pinyin indexing.
Sources: src/components/AIDocHeader/index.tsx:42-53
Specialized Content Rendering
The project uses rehype-katex for mathematical formulas and remark-github-alerts for GitHub-style callouts within Markdown content.
Sources: docusaurus.config.ts:3-5, docusaurus.config.ts:377-387
Navigation and Search Customization
Customization extends to navigation elements to provide a denser information experience.
Navbar and Footer
The navbar is configured to be hidden on scroll and includes custom items such as:
- Knowledge Base: A specific link to the
ai-docsplugin instance. - Custom Components:
custom-cdnSelectorandcustom-musicPlayer. - Relationship Graph: Links to the global
docs-graph.
Sources: docusaurus.config.ts:446-512
Search Functionality
The theme integrates @easyops-cn/docusaurus-search-local with multi-language support (English and Chinese). It specifically excludes protected content (marked with data-hx-protected) from the search index.
Sources: docusaurus.config.ts:544-558
Markdown Styling Overrides
The src/css/custom.css file contains specific overrides for Markdown rendering to ensure consistency with the GitHub visual style and fix specific Docusaurus rendering bugs.
Image and Table Alignment
Images within the documentation are centered by default and scale slightly (1.02x) on hover. Tables are explicitly set to display: table with automatic margins to ensure horizontal centering.
Sources: src/css/custom.css:57-73
Heading and Link Fixes
Headings (h1-h3) use GitHub-inspired border-bottom styles and font sizes. A critical fix is applied to strikethrough links (~~[text](https://github.com/HengXin666/HXLoLi/blob/f0480816b074928b73b485265916eebd71bfc20e/url)~~), where text-decoration-line: line-through !important is enforced to prevent link styles from overriding the deletion line.
Sources: src/css/custom.css:26-42, src/css/custom.css:100-117
Summary of Configuration Plugins
The theme is further extended through several custom internal plugins defined in docusaurus.config.ts.
| Plugin | Purpose |
|---|---|
ppt-html-assets | Publishes HTML resources in Markdown directories to page routes for PPT iframes. |
docs-links-graph | Generates relationship data between notes for the graph view. |
tag-index-plugin | Builds a Pinyin-based index for Knowledge Base tags. |
note-references-plugin | Extracts and injects "Cited By" and "References" data into documents. |
Sources: docusaurus.config.ts:281-351