# 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.