mkdocs-gitlab-theme 1.0.0

A professional GitLab-styled dark mode theme for MkDocs

GitLab MkDocs Theme

A professional, GitLab-styled dark mode theme for MkDocs with a modern design inspired by GitLab's documentation site.

Features

• Dark Mode Design: Professional dark color scheme with excellent contrast
• Responsive Layout: Works seamlessly on desktop, tablet, and mobile devices
• Collapsible Sidebar: Mobile-friendly navigation with hamburger menu
• Table of Contents: Right sidebar showing page sections for easy navigation
• Professional Styling:
  • Code blocks with syntax highlighting
  • Styled tables with hover effects
  • Admonitions (note, warning, danger, success)
  • Blockquotes and typography
  • Smooth transitions and animations
• Splash Page: Hero section template for homepage
• Search Ready: Compatible with MkDocs search plugin

Installation

Install the theme using pip:

pip install mkdocs-gitlab-theme

Usage

Update your mkdocs.yml to use the GitLab theme:

theme:
  name: gitlab
  logo: assets/logo.svg
  favicon: assets/favicon.ico

Configuration

Basic Configuration

theme:
  name: gitlab
  logo: assets/logo.svg
  favicon: assets/favicon.ico

With Navigation

theme:
  name: gitlab
  logo: assets/logo.svg
  favicon: assets/favicon.ico

nav:
  - Home: index.md
  - Getting Started:
    - Overview: getting-started/overview.md
    - Installation: getting-started/installation.md
  - Documentation:
    - Guide: docs/guide.md
    - API: docs/api.md

With Search

theme:
  name: gitlab

plugins:
  - search:
      lang: en

Color Palette

The theme uses a professional dark mode color scheme:

• Primary Text: #c7d2fe (Light Indigo)
• Accent: #818cf8 (Indigo)
• Background: #0f172a (Dark Slate)
• Secondary Background: #1e293b
• Border: #475569

Customization

Custom CSS

Create a docs/stylesheets/custom.css file and add it to your mkdocs.yml:

extra_css:
  - stylesheets/custom.css

Custom JavaScript

Create a docs/javascripts/custom.js file and add it to your mkdocs.yml:

extra_javascript:
  - javascripts/custom.js

Override Templates

To override theme templates, create an overrides directory:

docs/
├── index.md
├── overrides/
│   └── main.html
└── stylesheets/
    └── custom.css

Then update your mkdocs.yml:

theme:
  name: gitlab
  custom_dir: overrides

Markdown Extensions

The theme works with common MkDocs markdown extensions:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.emoji
  - admonition
  - codehilite
  - toc:
      permalink: true

Admonitions

Use admonitions for highlighted content:

!!! note
    This is a note admonition.

!!! warning
    This is a warning admonition.

!!! danger
    This is a danger admonition.

!!! success
    This is a success admonition.

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please visit: https://gitlab.com/gitlab-org/mkdocs-gitlab-theme/-/issues

Changelog

Version 1.0.0

• Initial release
• Dark mode design
• Responsive layout
• Mobile-friendly navigation
• Professional styling
• Search compatibility