Custom MDX Components
Relevant source files
The following files were used as context for generating this wiki page:
Custom MDX Components in the HXLoLi project extend standard Markdown functionality by injecting specialized React components into the rendering pipeline. This architecture allows developers to use complex UI elements, such as reference boxes, presentation slides, and AI-specific metadata headers, directly within .md and .mdx files without requiring manual imports in every document.
The system utilizes Docusaurus's MDXProvider to distribute a mapping of custom tags to React components. This approach ensures that built-in Markdown elements like links and images can be wrapped or replaced with project-specific logic, such as automatic zoom for images or reference tracking for notes.
Component Registry Architecture
The central registry for all global MDX components resides in src/theme/MDXComponents/index.tsx. The project performs a "theme swizzle" on the original Docusaurus MDXComponents to add custom keys while preserving standard mappings for headings, links, and admonitions.
The diagram shows how the custom component registry wraps the original Docusaurus theme components to provide extended functionality to the MDX provider.
Sources: src/theme/MDXComponents/index.tsx:12-28
NoteReferences Component
The NoteReferences component displays relationship boxes for internal and external citations. It is registered globally to avoid MDX 3 rendering errors where remark-injected imports at the top level might be silently discarded.
Sources: src/theme/MDXComponents/index.tsx:25-26
Specialized Knowledge Base Components
The project includes specialized components designed for the "Knowledge Base" (AI-Docs) section, providing technical metadata and authorship tracking.
AIDocHeader
AIDocHeader renders a stylized, animated header for documentation generated or assisted by AI models. It retrieves metadata from the file's frontmatter, including the creation date, the specific AI model used, and associated "Skills."
| Field | Description | Source |
|---|---|---|
created_at | The timestamp when the AI generated the note. | Frontmatter |
model | The specific model name (e.g., GPT-4, DeepSeek). | Frontmatter |
skill | A list of specialized Agent Skills utilized. | Frontmatter |
tags | Keywords indexed for the knowledge base. | Frontmatter |
Sources: src/components/AIDocHeader/index.tsx:43-64
Metadata badges
The header includes interactive and static badges. Skill badges link directly to the source code of the agent skill in the GitHub repository.
Sources: src/components/AIDocHeader/index.tsx:90-119
Presentation Suite (hxdeck)
The hxdeck module provides a suite of components designed for slide-based presentations within Markdown. These components adhere to a unified theme system and allow for interactive data visualization.
hxdeck UI Components
- Bullets: Unordered lists with support for bold highlights.
- Callout: Themed boxes for tips, warnings, and informational text.
- Steps: Visual progress indicators for multi-step processes.
- Diagram: Integrated SVG diagrams (Archify) that support zoom and pan.
- Gauge / Stat: Visualization blocks for numerical metrics.
Sources: src/hxdeck/Demo.tsx:12-25, src/hxdeck/Demo.tsx:88-150
This diagram represents the hierarchical relationship between the presentation deck, individual slides, and the UI components they contain.
Sources: src/hxdeck/Demo.tsx:75-77
Global Layout Integration
Custom components are also integrated into the core document layout to handle page-level features like breadcrumbs, relationship diagrams, and license information.
DocItemLayout Functions
DocItemLayout in src/theme/DocItem/Layout/index.tsx detects if a page belongs to the knowledge base using the route path. If isAIDocs is true, it automatically injects the AIDocHeader and a MitemitePanel for developer tools.
Sources: src/theme/DocItem/Layout/index.tsx:78-83
Link and License Handling
The project wraps the standard Markdown link (<a>) with a custom MDXA component. This integration allows for:
- CC License Enforcement: The footer automatically injects a Creative Commons 4.0 BY-SA attribution with custom restrictions against specific platforms like CSDN.
- External Link Decoration: Icons are added to links pointing outside the project.
Sources: src/theme/DocItem/Layout/index.tsx:117-123, README.md:46-48
Summary of Registered Components
The following table summarizes the primary custom components registered for use within MDX files.
| Tag / Component | File Path | Usage Context |
|---|---|---|
NoteReferences | src/components/NoteReferences | Global (Reference tracking) |
AIDocHeader | src/components/AIDocHeader | Knowledge Base (Metadata) |
Diagram | src/hxdeck/diagram | Presentations (Archify SVGs) |
MDXA | src/theme/MDXComponents/A.tsx | Global (Enhanced links) |
InlineEditor | src/components/DevTools | Development (VS Code jump) |
Sources: src/theme/MDXComponents/index.tsx:26, src/theme/DocItem/Layout/index.tsx:86, src/hxdeck/Demo.tsx:16
Custom MDX Components serve as the bridge between static Markdown content and interactive React logic. By centralizing these components in the theme registry, the project maintains consistent styling and functionality across documentation, blog posts, and specialized knowledge base articles while keeping individual Markdown files clean and focused on content.