Skip to content

Configuration Guide

Learn how to customize U.WIKI to match your needs.

Configuration File

All configuration is done in mkdocs.yml. This file controls:

  • Site metadata
  • Theme settings
  • Navigation structure
  • Plugin configuration
  • Markdown extensions

Basic Configuration

Site Information

site_name: U.WIKI
site_description: Your wiki description
site_author: Your Name
site_url: https://your-domain.com

Repository Settings

repo_name: yourusername/U.WIKI
repo_url: https://github.com/yourusername/U.WIKI
edit_uri: edit/main/docs/

Theme Configuration

Color Schemes

Change the primary and accent colors:

theme:
  palette:
    primary: indigo
    accent: indigo

Available colors: - red, pink, purple, deep-purple - indigo, blue, light-blue, cyan - teal, green, light-green, lime - yellow, amber, orange, deep-orange - brown, grey, blue-grey

Dark Mode

Enable automatic dark mode:

theme:
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Fonts

Customize fonts:

theme:
  font:
    text: Roboto        # Main text font
    code: Roboto Mono   # Code block font

Simple Navigation

nav:
  - Home: index.md
  - About: about.md
  - Contact: contact.md

Nested Navigation

nav:
  - Home: index.md
  - User Guide:
    - Getting Started: guide/getting-started.md
    - Advanced Usage: guide/advanced.md
  - API Reference:
    - Overview: api/overview.md
    - Endpoints: api/endpoints.md

Features

Enable/Disable Features

theme:
  features:
    - navigation.instant      # Instant loading
    - navigation.tracking     # Anchor tracking
    - navigation.tabs         # Tab navigation
    - navigation.sections     # Collapsible sections
    - navigation.expand       # Auto-expand sections
    - navigation.top          # Back to top button
    - search.suggest          # Search suggestions
    - search.highlight        # Highlight search terms
    - content.code.copy       # Copy button on code blocks

Plugins

Search Plugin

plugins:
  - search:
      lang: en
      separator: '[\s\-\.]+'

Tags Plugin

plugins:
  - tags:
      tags_file: tags.md

Markdown Extensions

Enable Extensions

markdown_extensions:
  - admonition           # Note/warning boxes
  - codehilite          # Code syntax highlighting
  - toc:                # Table of contents
      permalink: true
  - pymdownx.superfences # Advanced code blocks
  - pymdownx.details    # Collapsible sections
  - pymdownx.tabbed     # Content tabs

Advanced Configuration

Custom CSS

Add custom CSS:

  1. Create docs/assets/stylesheets/custom.css
  2. Add to configuration:
extra_css:
  - assets/stylesheets/custom.css

Custom JavaScript

Add custom JavaScript:

extra_javascript:
  - assets/javascripts/custom.js

Analytics

Add Google Analytics:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Add social media links:

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/yourusername
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/yourusername

Environment-Specific Config

Use environment variables:

site_name: !ENV [SITE_NAME, "U.WIKI"]
site_url: !ENV SITE_URL

Validation

Validate your configuration:

mkdocs build --strict

This will catch any configuration errors.

Example Configurations

Minimal Config

site_name: My Wiki
theme:
  name: material

See our mkdocs.yml for a complete example.

Next Steps