Metadata-Version: 2.4
Name: mkdocs-gitlab-theme
Version: 0.0.3
Summary: A GitLab-styled theme for MkDocs
Home-page: https://gitlab.com/gitlab-org/mkdocs-gitlab-theme
Author: GitLab
Author-email: GitLab <support@gitlab.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/gitlab-org/mkdocs-gitlab-theme
Project-URL: Documentation, https://gitlab.com/gitlab-org/mkdocs-gitlab-theme
Project-URL: Repository, https://gitlab.com/gitlab-org/mkdocs-gitlab-theme.git
Project-URL: Issues, https://gitlab.com/gitlab-org/mkdocs-gitlab-theme/-/issues
Keywords: mkdocs,theme,gitlab,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.0
Dynamic: license-file

# 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:

```bash
pip install mkdocs-gitlab-theme
```

## Usage

Update your `mkdocs.yml` to use the GitLab theme:

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

## Configuration

### Basic Configuration

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

### With Navigation

```yaml
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

```yaml
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`:

```yaml
extra_css:
  - stylesheets/custom.css
```

### Custom JavaScript

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

```yaml
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`:

```yaml
theme:
  name: gitlab
  custom_dir: overrides
```

## Markdown Extensions

The theme works with common MkDocs markdown extensions:

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

## Admonitions

Use admonitions for highlighted content:

```markdown
!!! 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
