Get started¶

Pixel Lab is a theme for MkDocs, not a separate site generator. You need Python 3.10 or newer. Installing the theme also installs MkDocs, Pymdown Extensions, and Pygments.

Install¶

Use a virtual environment for your documentation project:

python -m venv .venv

source .venv/bin/activate

.venv\Scripts\Activate.ps1

Then install Pixel Lab:

python -m pip install mkdocs-pixel-lab

Enable the theme¶

For a new site, run mkdocs new . in an empty project directory. For an existing site, keep your current files and navigation.

Merge this into your site's mkdocs.yml:

site_name: My documentation
theme:
  name: pixel-lab

Enable rich Markdown¶

Enable the extensions your pages use:

markdown_extensions:
  - admonition
  - mkdocs_pixel_lab.github_alerts
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight
  - pymdownx.tabbed:
      alternate_style: true
  - md_in_html

Each component guide lists its required extensions and Markdown syntax.

Preview and build¶

mkdocs serve

Open http://127.0.0.1:8000/. MkDocs rebuilds the preview as you edit.

Before publishing, validate your site:

mkdocs build --strict

For hosting options, follow MkDocs deployment documentation.

Next steps¶

• Set up your theme: appearance and site-wide behavior.
• Explore components: live examples and Markdown.
• Check compatibility: requirements and limitations.
• Troubleshoot a problem: configuration and rendering fixes.

Preview this documentation from a checkout¶

To preview or contribute to this website, follow the contributor guide.