Skip to content

Conversation

@httpdss
Copy link
Owner

@httpdss httpdss commented Aug 2, 2025

🎨 Customization Overview

This PR implements comprehensive MkDocs theme customization to match the existing website's look and feel, including Google Tag Manager integration as requested in issue #80.

✨ Changes Made

  1. Theme Override Structure

    • Created overrides/ directory with custom theme templates
    • Added overrides/main.html for base template with GTM integration
    • Added overrides/stylesheets/extra.css for comprehensive styling
  2. Google Tag Manager Integration

    • Added GTM script tag with ID GTM-M4X52F2D in the <head> section
    • Included no-script fallback for users with JavaScript disabled
    • Proper placement following GTM best practices
  3. Styling Alignment

    • Colors: Matched the website's custom CSS properties from site/css/main.css
    • Typography: Integrated Inter font family and Fira Code for monospace
    • Dark Mode: Set as default with proper color variables
    • Layout: Consistent styling for navigation, headers, content areas
    • Code Blocks: Custom styling with proper syntax highlighting
    • UI Elements: Styled tables, admonitions, buttons, and forms
  4. Configuration Updates

    • Updated mkdocs.yml with custom directory and extra CSS
    • Set dark mode as default with media queries
    • Configured proper Material theme palette
    • Added theme customization features

🎯 Key Features

  • Consistent Branding: Documentation now visually matches the main site
  • Analytics Integration: GTM provides tracking capabilities
  • Responsive Design: Proper mobile and desktop styling
  • Accessibility: Maintained accessibility standards
  • Custom Scrollbars: Styled to match the overall theme
  • Enhanced Code Display: Better code block styling with proper fonts

🔗 Implementation Details

  • Uses MkDocs Material theme's customization capabilities
  • CSS custom properties for maintainable styling
  • Proper color scheme variables for both light and dark modes
  • Responsive breakpoints matching the main site
  • Custom scrollbar styling for better UX

🚀 Testing

The implementation follows MkDocs Material theme best practices and should integrate seamlessly with the existing documentation workflow.

Closes #80

…Tag Manager

- Add theme overrides with custom directory structure
- Implement Google Tag Manager integration (GTM-M4X52F2D)
- Match styling from site/css/main.css with custom color scheme
- Set dark mode as default with proper color variables
- Add Inter font family and Fira Code for code blocks
- Style navigation, headers, code blocks, and UI elements consistently
- Include responsive design and custom scrollbar styling
- Configure proper CSS custom properties for Material theme

Fixes #80
@codecov-commenter
Copy link

codecov-commenter commented Aug 2, 2025

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.74%. Comparing base (ef12e07) to head (b41208f).
⚠️ Report is 1 commits behind head on main.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #82   +/-   ##
=======================================
  Coverage   68.74%   68.74%           
=======================================
  Files          23       23           
  Lines        1331     1331           
  Branches      181      181           
=======================================
  Hits          915      915           
  Misses        374      374           
  Partials       42       42           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@httpdss httpdss added enhancement New feature or request minor labels Aug 2, 2025
@httpdss httpdss merged commit 2c13082 into main Aug 2, 2025
3 checks passed
@httpdss httpdss deleted the feature/customize-mkdocs-theme-gtm branch August 2, 2025 16:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

🎨 Customize MkDocs Theme to Match Site Appearance and Include Google Tag Manager

3 participants