Advanced MkDocs Configuration¶

This page demonstrates actual advanced configurations implemented on this site. Each feature is actively used here, so you can see them in action.

Implementation Status on This Site¶

Feature	Status	Where to See
Git Revision Date	✅ Implemented	Bottom of each page
HTML/CSS/JS Minification	✅ Implemented	Page source code
Multi-language Support	✅ Implemented	Language selector in header
Code Copy Button	✅ Implemented	Code blocks on this page
Custom 404 Page	✅ Implemented	Try visiting /not-exist
robots.txt	✅ Implemented	/robots.txt
Smooth Scrolling	✅ Implemented	Click any anchor link
Progress Bar	✅ Implemented	Scroll this page
Keyboard Shortcuts	✅ Implemented	Press `/` for search
Lazy Image Loading	⏳ Planned	-
PWA Support	⏳ Planned	-

1. Plugin Configuration¶

Search Plugin (Japanese Support)¶

Already implemented on this site. Try searching in Japanese!

plugins:
  - search:
      lang: ja
      separator: '[\s\-\.\u3000\u3001\u3002]+' # Japanese character separators

The separator setting enables proper Japanese word segmentation, allowing searches for partial words.

Git Revision Date Plugin¶

Check the bottom of this page to see the last update time!

plugins:
  - git-revision-date-localized:
      type: datetime
      timezone: Asia/Tokyo
      locale: ja
      fallback_to_build_date: true

Settings explanation: - type: datetime: Shows date and time - timezone: Asia/Tokyo: Japan time zone - locale: ja: Japanese format - fallback_to_build_date: Uses build date when Git info unavailable

HTML/CSS/JS Minification¶

This site's HTML is minified. Check the page source!

plugins:
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true
        remove_empty_space: true
      cache_safe: true

2. Theme Customization¶

Material Theme Extensions¶

All features below are active on this site:

theme:
  name: material
  features:
    # Navigation enhancements
    - navigation.instant        # Instant loading
    - navigation.tracking       # URL tracking
    - navigation.tabs          # Tab navigation
    - navigation.tabs.sticky   # Sticky tabs
    - navigation.sections      # Section expansion
    - navigation.expand        # Auto-expand sections
    - navigation.path          # Breadcrumb navigation
    - navigation.top          # Back to top button

    # Search enhancements
    - search.highlight        # Highlight search terms
    - search.suggest         # Search suggestions
    - search.share          # Share search

    # Content features
    - content.code.copy     # Code copy button
    - content.tabs.link     # Linked content tabs

    # UI improvements
    - header.autohide       # Auto-hide header
    - toc.integrate        # Integrated TOC

Custom Colors¶

The teal color scheme you see:

theme:
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: teal
      accent: deep orange
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: teal
      accent: deep orange
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

3. Markdown Extensions¶

Code Highlighting¶

Try copying this code block - there's a copy button!

def hello_world():
    """Advanced code highlighting example"""
    message = "Hello, World!"
    print(f"Message: {message}")
    return message

# Syntax highlighting for various languages
if __name__ == "__main__":
    hello_world()

Configuration:

markdown_extensions:
  - codehilite:
      guess_lang: false
      linenums: true
  - pymdownx.superfences
  - pymdownx.inlinehilite

Admonitions¶

This is a Note

Various admonition types are available on this site.

Warning Example

Important information is displayed like this.

Pro Tip

Useful tips and tricks here.

Danger Zone

Critical warnings appear like this.

Tabs¶

=== "Python"

print("Hello from Python!")

=== "JavaScript"

console.log("Hello from JavaScript!");

=== "Bash"

echo "Hello from Bash!"

Task Lists¶

4. Custom JavaScript¶

Features implemented with custom JS:

Progress Bar¶

// docs/javascripts/extra.js
// Scroll to see the progress bar at the top!
document.addEventListener('DOMContentLoaded', function() {
    // Create progress bar
    const progressBar = document.createElement('div');
    progressBar.style.cssText = `
        position: fixed;
        top: 0;
        left: 0;
        width: 0%;
        height: 3px;
        background: linear-gradient(to right, #00bcd4, #009688);
        z-index: 9999;
        transition: width 0.2s ease;
    `;
    document.body.appendChild(progressBar);

    // Update on scroll
    window.addEventListener('scroll', function() {
        const windowHeight = document.documentElement.scrollHeight - document.documentElement.clientHeight;
        const scrolled = (window.scrollY / windowHeight) * 100;
        progressBar.style.width = scrolled + '%';
    });
});

Code Copy Enhancement¶

Already working on all code blocks!

// Enhanced copy button with feedback
document.querySelectorAll('.md-clipboard').forEach(button => {
    button.addEventListener('click', function() {
        // Visual feedback
        const icon = this.querySelector('.md-clipboard__message');
        icon.style.opacity = '1';
        setTimeout(() => {
            icon.style.opacity = '0';
        }, 2000);
    });
});

Smooth Scrolling¶

Click any heading link to experience smooth scrolling:

// Smooth scroll for anchor links
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
    anchor.addEventListener('click', function(e) {
        e.preventDefault();
        const target = document.querySelector(this.getAttribute('href'));
        if (target) {
            target.scrollIntoView({
                behavior: 'smooth',
                block: 'start'
            });
        }
    });
});

5. SEO Optimization¶

Meta Tags¶

Implemented in theme customization:

extra:
  meta:
    - name: description
      content: "Technical documentation with MkDocs advanced features"
    - name: keywords
      content: "MkDocs, documentation, GitHub Pages, Material theme"
    - name: author
      content: "Your Name"

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

robots.txt¶

Check our robots.txt:

User-agent: *
Allow: /
Disallow: /drafts/
Sitemap: https://aiedoc.github.io/note/sitemap.xml

Custom 404 Page¶

Try it: Non-existent page

# docs/404.md
# 404 - Page Not Found

The page you're looking for doesn't exist.

**Helpful links:**
- [Homepage](/)
- [Documentation](/docs/)
- [Search](/search/)

6. Performance Optimization¶

Lazy Loading Setup¶

markdown_extensions:
  - attr_list
  - md_in_html

Then in Markdown:

![Image description](image.jpg){: loading=lazy }

Prefetch Configuration¶

Already active - hover over any link!

theme:
  features:
    - navigation.instant
    - navigation.instant.prefetch

7. GitHub Actions Automation¶

Our deploy workflow:

name: Deploy MkDocs
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: pip install mkdocs-minify-plugin
      - run: pip install mkdocs-git-revision-date-localized-plugin
      - run: mkdocs gh-deploy --force

8. Multi-language Configuration¶

Language switcher in the header!

plugins:
  - i18n:
      default_language: ja
      languages:
        ja: 日本語
        en: English
      nav_translations:
        en:
          ホーム: Home
          ガイド: Guide
          リファレンス: Reference

Summary¶

All features demonstrated on this page are actively implemented on this site. You can verify each feature by:

Git revision dates - Check page footers
Minification - View page source
Search - Press / key
Code copying - Click copy buttons on code blocks
Smooth scrolling - Click any anchor link
Progress bar - Scroll this page
Dark mode - Toggle in header
Multi-language - Language selector in header

These configurations transform a basic MkDocs site into a professional, feature-rich documentation platform!