Skip to content

MkDocs Design Improvement Guide

This guide provides detailed instructions on how to achieve a modern UI with the MkDocs Material theme.

Prerequisites

This guide assumes you have completed How to Create GitHub Pages with MkDocs.

1. Latest MkDocs Material Features

1.1 Dark Mode Support

Implement automatic switching based on user system settings and manual toggle:

# mkdocs.yml
theme:
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: teal
      accent: deep orange
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: teal
      accent: deep orange
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

1.2 Enhanced Navigation Features

Achieve modern SPA-like behavior:

theme:
  features:
    # Navigation
    - navigation.instant          # Instant loading
    - navigation.instant.prefetch # Prefetch feature
    - navigation.tabs            # Tab navigation
    - navigation.tabs.sticky     # Sticky tabs
    - navigation.sections        # Section display
    - navigation.expand          # Auto-expand
    - navigation.path            # Breadcrumbs
    - navigation.top             # Back to top button
    # Search
    - search.highlight           # Search highlighting
    - search.suggest             # Search suggestions
    # Header
    - header.autohide           # Auto-hide header
    # Content
    - content.code.copy          # Code copy button
    - content.code.select        # Code selection feature
    - content.tooltips           # Tooltips

1.3 Icon and Visual Enhancements

GitHub icon and font configuration:

theme:
  icon:
    repo: fontawesome/brands/github
  font:
    text: 'Noto Sans JP'
    code: 'Roboto Mono'

2. Custom CSS Implementation

2.1 Basic Setup

Create docs/stylesheets/extra.css:

/* Japanese font configuration */
:root {
  --md-text-font: "Noto Sans JP", "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Yu Gothic UI", "Meiryo UI", sans-serif;
  --md-code-font: "SFMono-Regular", "Consolas", "Liberation Mono", "Menlo", monospace;
}

/* Load Japanese font from Google Fonts */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@300;400;500;700&display=swap');

/* Custom color variables */
:root {
  --md-accent-fg-color: #ff6f00;
  --md-accent-fg-color--transparent: #ff6f001a;
}

2.2 Navigation Improvements

/* Navigation improvements */
.md-nav__title {
  font-weight: 600;
}

.md-nav__link {
  border-radius: 0.1rem;
  transition: background-color 125ms;
}

.md-nav__link:hover {
  background-color: var(--md-accent-fg-color--transparent);
}

2.3 Content Area Improvements

/* 3-column grid layout */
.md-content ul {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 1rem;
  list-style: none;
  padding: 0;
  margin: 1rem 0;
}

.md-content ul li {
  background: var(--md-default-bg-color);
  border: 1px solid var(--md-default-fg-color--lighter);
  border-radius: 0.5rem;
  padding: 1rem;
  transition: all 0.3s ease;
  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
  min-height: 3rem;
  display: flex;
  align-items: center;
}

.md-content ul li:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 16px rgba(0,0,0,0.12);
  border-color: var(--md-accent-fg-color);
}

2.4 Responsive Design

/* Responsive design */
@media screen and (max-width: 76.1875em) {
  .md-content ul {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media screen and (max-width: 44.9375em) {
  .md-content ul {
    grid-template-columns: 1fr;
  }
}

2.5 Add Animations

/* Page transition animation */
.md-content {
  animation: fadeIn 0.3s ease-in-out;
}

@keyframes fadeIn {
  from { opacity: 0; transform: translateY(0.5rem); }
  to { opacity: 1; transform: translateY(0); }
}

/* Code block improvements */
.md-typeset pre > code {
  border-radius: 0.5rem;
}

/* Table improvements */
.md-typeset table:not([class]) {
  border-radius: 0.5rem;
  overflow: hidden;
  box-shadow: 0 0.2rem 1rem rgba(0, 0, 0, 0.05);
}

/* Search box improvements */
.md-search__input {
  border-radius: 2rem;
}

2.6 Dark Mode Adjustments

/* Dark mode adjustments */
[data-md-color-scheme="slate"] {
  --md-hue: 210;
  --md-default-bg-color: #1a1a1a;
  --md-default-fg-color: #e1e5e9;
}

3. Complete mkdocs.yml Configuration

Add CSS file to mkdocs.yml:

extra_css:
  - stylesheets/extra.css

4. Plugin Configuration

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

4.2 Markdown Extensions

markdown_extensions:
  - admonition                    # Admonitions
  - pymdownx.details             # Collapsible blocks
  - pymdownx.superfences         # Enhanced code blocks
  - pymdownx.highlight:          # Syntax highlighting
      anchor_linenums: true
  - pymdownx.inlinehilite        # Inline code
  - pymdownx.snippets            # Code snippets
  - pymdownx.tabbed:             # Tabbed content
      alternate_style: true
  - pymdownx.emoji:              # Emoji
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.keys                # Keyboard keys
  - pymdownx.mark                # Markers
  - pymdownx.tilde               # Strikethrough
  - attr_list                    # Attribute lists
  - md_in_html                   # Markdown in HTML

5. Deploy and Verify

5.1 Local Verification

# Check with development server
mkdocs serve

# Build test
mkdocs build

5.2 Deploy to GitHub Pages

# Commit changes
git add .
git commit -m "UI improvements: Implement modern design"
git push origin main

# Deploy to GitHub Pages
mkdocs gh-deploy

6. Implementation Examples

6.1 Card-style Content

!!! example "Card Example"
    <div class="grid cards" markdown>

    - :material-clock-fast:{ .lg .middle } __Fast__

        ---

        MkDocs is a fast static site generator

    - :fontawesome-brands-markdown:{ .lg .middle } __Markdown__

        ---

        Write with familiar Markdown syntax

    </div>

6.2 Tabbed Display

=== "Python"

    ``` python
    print("Hello, World!")
    ```

=== "JavaScript"

    ``` javascript
    console.log("Hello, World!");
    ```

6.3 Using Admonitions

!!! tip "Tip"
    Using this feature improves usability.

!!! warning "Warning"
    Back up your data before changing settings.

!!! info "Information"
    This feature has been added in the latest version.

7. Performance Optimization

7.1 Image Optimization

<!-- Use WebP format -->
![Image description](/MkDocs/images/image.webp){ loading=lazy }

<!-- Lazy loading -->
![Image description](/MkDocs/images/image.png){ loading=lazy width=300 }

7.2 Font Optimization

/* Font display optimization */
@font-face {
  font-family: 'Noto Sans JP';
  font-display: swap;
  src: url('...') format('woff2');
}

8. Customization Best Practices

  1. Gradual Improvement: Implement in order: basic settings → add CSS → advanced features
  2. Responsive: Design mobile-first
  3. Performance: Avoid unnecessary CSS and JavaScript
  4. Accessibility: Consider color contrast and keyboard navigation
  5. Maintainability: Group CSS logically

9. Troubleshooting

Common Issues

CSS Not Applied

# Clear cache
mkdocs build --clean

Fonts Not Displaying

# Check extra_css configuration
extra_css:
  - stylesheets/extra.css

Layout Breaks on Mobile

/* Check viewport */
@media screen and (max-width: 44.9375em) {
  /* Mobile styles */
}

📚 Related Articles & Next Steps

Once you've mastered the design basics, try further customization:

🚀 Extend Functionality

📝 Review the Basics

🛠️ Improve Technical Skills

See Design Improvements in Action

This site itself is a live example of design improvements. You can see features like the 3-column grid layout on the homepage and dark mode switching on every page.

References