144 lines
5.2 KiB
Markdown
144 lines
5.2 KiB
Markdown
# MkDocs Customization & Features Overview
|
|
|
|
BNKops has been building our own features, widgets, and css styles for MKdocs material theme.
|
|
|
|
This document explains the custom styling, repository widgets, and key features enabled in this MkDocs site.
|
|
|
|
For more info on how to build your site see [Site Build](../build/site.md)
|
|
|
|
---
|
|
|
|
## Using the Repository Widget in Documentation
|
|
|
|
You can embed repository widgets directly in your Markdown documentation to display live repository stats and metadata.
|
|
To do this, add a `div` with the appropriate class and `data-repo` attribute for the repository you want to display.
|
|
|
|
**Example (for a Gitea repository):**
|
|
```html
|
|
<div class="gitea-widget" data-repo="admin/changemaker.lite"></div>
|
|
```
|
|
|
|
This will render a styled card with information about the `admin/changemaker.lite` repository:
|
|
|
|
<div class="gitea-widget" data-repo="admin/changemaker.lite"></div>
|
|
|
|
**Options:**
|
|
You can control the widget display with additional data attributes:
|
|
- `data-show-description="false"` — Hide the description
|
|
- `data-show-language="false"` — Hide the language
|
|
- `data-show-last-update="false"` — Hide the last update date
|
|
|
|
**Example with options:**
|
|
```html
|
|
<div class="gitea-widget" data-repo="admin/changemaker.lite" data-show-description="false"></div>
|
|
```
|
|
|
|
For GitHub repositories, use the `github-widget` class:
|
|
```html
|
|
<div class="github-widget" data-repo="lyqht/mini-qr"></div>
|
|
```
|
|
|
|
---
|
|
|
|
## Custom CSS Styling (`stylesheets/extra.css`)
|
|
|
|
The `extra.css` file provides extensive custom styling for the site, including:
|
|
|
|
- **Login and Git Code Buttons**:
|
|
Custom styles for `.login-button` and `.git-code-button` to create visually distinct, modern buttons with hover effects.
|
|
|
|
- **Code Block Improvements**:
|
|
Forces code blocks to wrap text (`white-space: pre-wrap`) and ensures inline code and tables with code display correctly on all devices.
|
|
|
|
- **GitHub Widget Styles**:
|
|
Styles for `.github-widget` and its subcomponents, including:
|
|
- Card-like container with gradient backgrounds and subtle box-shadows.
|
|
- Header with icon, repo link, and stats (stars, forks, issues).
|
|
- Description area with accent border.
|
|
- Footer with language, last update, and license info.
|
|
- Loading and error states with spinners and error messages.
|
|
- Responsive grid layout for multiple widgets.
|
|
- Compact variant for smaller displays.
|
|
- Dark mode adjustments.
|
|
|
|
- **Gitea Widget Styles**:
|
|
Similar to GitHub widget, but with Gitea branding (green accents).
|
|
Includes `.gitea-widget`, `.gitea-widget-container`, and related classes for header, stats, description, footer, loading, and error states.
|
|
|
|
- **Responsive Design**:
|
|
Media queries ensure widgets and tables look good on mobile devices.
|
|
|
|
---
|
|
|
|
## Repository Widgets
|
|
|
|
### Data Generation (`hooks/repo_widget_hook.py`)
|
|
|
|
- **Purpose**:
|
|
During the MkDocs build, this hook fetches metadata for a list of GitHub and Gitea repositories and writes JSON files to `docs/assets/repo-data/`.
|
|
- **How it works**:
|
|
- Runs before build (unless in `serve` mode).
|
|
- Fetches repo data (stars, forks, issues, language, etc.) via GitHub/Gitea APIs.
|
|
- Outputs a JSON file per repo (e.g., `lyqht-mini-qr.json`).
|
|
- Used by frontend widgets for fast, client-side rendering.
|
|
|
|
### GitHub Widget (`javascripts/github-widget.js`)
|
|
|
|
- **Purpose**:
|
|
Renders a card for each GitHub repository using the pre-generated JSON data.
|
|
- **Features**:
|
|
- Displays repo name, link, stars, forks, open issues, language, last update, and license.
|
|
- Shows loading spinner while fetching data.
|
|
- Handles errors gracefully.
|
|
- Supports dynamic content (re-initializes on DOM changes).
|
|
- Language color coding for popular languages.
|
|
|
|
### Gitea Widget (`javascripts/gitea-widget.js`)
|
|
|
|
- **Purpose**:
|
|
Renders a card for each Gitea repository using the pre-generated JSON data.
|
|
- **Features**:
|
|
- Similar to GitHub widget, but styled for Gitea.
|
|
- Shows repo name, link, stars, forks, open issues, language, last update.
|
|
- Loading and error states.
|
|
- Language color coding.
|
|
|
|
---
|
|
|
|
## MkDocs Features (`mkdocs.yml`)
|
|
|
|
Key features and plugins enabled:
|
|
|
|
- **Material Theme**:
|
|
Modern, responsive UI with dark/light mode toggle, custom fonts, and accent colors.
|
|
|
|
- **Navigation Enhancements**:
|
|
- Tabs, sticky navigation, instant loading, breadcrumbs, and sectioned navigation.
|
|
- Table of contents with permalinks.
|
|
|
|
- **Content Features**:
|
|
- Code annotation, copy buttons, tooltips, and improved code highlighting.
|
|
- Admonitions, tabbed content, task lists, and emoji support.
|
|
|
|
- **Plugins**:
|
|
- **Search**: Advanced search with custom tokenization.
|
|
- **Social**: OpenGraph/social card generation.
|
|
- **Blog**: Blogging support with archives and categories.
|
|
- **Tags**: Tagging for content organization.
|
|
|
|
- **Custom Hooks**:
|
|
- `repo_widget_hook.py` for repository widget data.
|
|
|
|
- **Extra CSS/JS**:
|
|
- Custom styles and scripts for widgets and homepage.
|
|
|
|
- **Extra Configuration**:
|
|
- Social links, copyright.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
This MkDocs site is highly customized for developer documentation, with visually rich repository widgets, improved code and table rendering, and a modern, responsive UI.
|
|
All repository stats are fetched at build time for performance and reliability.
|