mkdocs-pixel-lab 0.1.3

A retro-inspired theme for MkDocs, with pixel borders, bold colors, and arcade-style shadows.
Built for modern documentation with responsive navigation, search, and rich Markdown components.

Preview

Desktop	Mobile

Quick start

python -m pip install mkdocs-pixel-lab

Use it in mkdocs.yml:

theme:
  name: pixel-lab

The snippets below show settings to merge into your existing mkdocs.yml.

Everyday features

Responsive navigation

Primary navigation tabs and the contextual section sidebar follow MkDocs' nav: tree. Narrow browser windows use a menu drawer with the same links, whether viewed on a phone or desktop. The current page and section are marked automatically.

Search

The toolbar search opens a compact panel backed by MkDocs' search index. Enable the standard plugin:

plugins:
  - search

Heading links and keyboard access

Section headings (H2–H6) show a permalink icon after the title. H1 page titles keep their IDs without an icon.

Choose chain (the default filled chain icon), link (the original link icon), or hash (the # icon) with theme.permalink_icon. All three use heading-relative sizing.

The URL fragment follows the current section as you scroll, without adding browser-history entries. Enable visible heading permalinks with:

theme:
  name: pixel-lab
  permalink_icon: chain # default; or link, hash
  permalink_fill_color: "var(--accent)" # light accent by default; transparent disables it
markdown_extensions:
  - toc:
      permalink: true

The chain's colored body uses theme.permalink_fill_color (the light accent by default); its openings remain transparent. The black outline stays visible, while the shadow appears in the dark accent only on hover or keyboard focus. The original link and hash icons keep their light-accent coloring and dark-accent hover; the chain's fill setting does not affect them.

A skip-to-content link, visible focus styles, and labeled navigation regions support keyboard use. Escape closes the search panel or open navigation drawer and returns focus to its toolbar button.

Media, tables, and nested shadows

Images and videos scale to the available content width. Wide tables scroll inside a fixed bordered frame, keeping its pixel shadow in place. When cards, alerts, tables, media, or code are nested inside an elevated component, inner shadows are removed automatically so only the outer component is elevated.

Bundled fonts

Inter and IBM Plex Mono are served with the theme. No Google Fonts request or external font service is required.

Rich Markdown content

Code blocks

Syntax-highlighted code blocks include a one-click copy button with success and failure feedback. Enable Pymdown's fenced-code and highlighting extensions:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.highlight

Code and inline-code colors follow the theme palette; long blocks scroll horizontally.

Pygments is installed with the theme, so syntax coloring works in clean build environments. Emphasize individual lines with hl_lines:

```{ .python hl_lines="2" }
import math
print(math.pi)
```

GitHub Alerts

Enable GitHub-style Markdown alerts explicitly when a site uses them:

markdown_extensions:
  - mkdocs_pixel_lab.github_alerts

The extension supports NOTE, TIP, IMPORTANT, WARNING, and CAUTION:

> [!TIP]
>
> Use semantic callouts for important guidance.

Content tabs and collapsible notes

Admonitions, expandable details, and content tabs use the same pixel borders and palette as the rest of the theme. Enable the corresponding extensions:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true

Content tabs are separate from the primary navigation tabs below the toolbar.

Each content tab automatically chooses its layout: a single code block or table fills the panel flush, while prose, multiple blocks, and mixed content retain the padded layout. Code keeps its internal padding, tables keep their cell padding and horizontal scrolling, and the tab container owns the outer border and shadow. Nested tabs are evaluated independently.

To force a layout, wrap a tab group in .tabs-padded or .tabs-flush and enable md_in_html in markdown_extensions:

<div class="tabs-padded" markdown="1">

=== "Python"

    ```python
    print("Keep the surrounding inset")
    ```

=== "Shell"

    ```bash
    echo "This tab is padded too"
    ```

</div>

Use .tabs-flush instead to remove the surrounding inset. The closest layout wrapper wins for nested groups. Layout detection runs in the theme's script; with JavaScript disabled, tabs retain the padded presentation.

Page metadata

Define browser/search titles and descriptions using standard Markdown front matter. Visible headings and explicitly configured navigation labels stay unchanged:

---
title: Detect and Annotate with Supervision
description: Load predictions and annotate images with boxes, labels, and masks.
---

# Detect and Annotate

The theme honors these fields without another plugin. To also generate defaults for pages without metadata, enable the build-time plugin bundled with Pixel Lab (no additional package is needed):

plugins:
  - search
  - pixel-lab/metadata

Titles use title → first H1 → MkDocs page title → site name. The site name is appended once. Descriptions use description → first introductory paragraph → site_description, and the tag is omitted if none is available. Blank or non-text front-matter fields are ignored by the plugin.

Generated excerpts retain plain text, including inline code and link text, but skip code blocks, tables, alerts, lists, images, and navigation. They are shortened at a word boundary to at most 160 characters, including an ellipsis; explicit descriptions are not shortened. Extraction runs during the build, so metadata is in the HTML without JavaScript. It does not edit Markdown files or replace MkDocs' canonical URLs. Google may choose a different search title or snippet. This plugin does not use Git or change sitemap modification dates.

Sitemap modification dates

The optional pixel-lab/git-lastmod plugin sets sitemap lastmod to the date of each Markdown source file's last committed Git change, rather than the build date. MkDocs continues to generate sitemap.xml and sitemap.xml.gz using your site_url; no separate sitemap generator is required.

Enable this separately bundled plugin in mkdocs.yml (no additional package is needed):

plugins:
  - search
  - pixel-lab/git-lastmod

It is independent of pixel-lab/metadata: enable either plugin or both. Without pixel-lab/git-lastmod, the theme preserves MkDocs' default sitemap dates and does not run Git commands.

Git must be installed and the documentation repository must have complete history. For GitHub Actions documentation builds, use:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

An unrelated commit or rebuild does not change a page's date. Dates use the last commit's committer date; local uncommitted edits and front-matter display dates do not override Git history. Untracked or generated pages, files outside the documentation repository, missing Git history, and shallow clones omit lastmod instead of falling back to today's date. Renamed files use their Git history. Dates are cached within each build and refreshed on the next rebuild.

Robots.txt

Enable the optional pixel-lab/robots plugin to generate a public-crawling default at robots.txt in the built site:

site_url: https://example.com/
plugins:
  - search
  - pixel-lab/robots

The generated file allows crawling and points to MkDocs' sitemap:

User-agent: *
Allow: /

Sitemap: https://example.com/sitemap.xml

The sitemap URL comes from site_url, including any deployment path. If site_url is not set, the sitemap directive is omitted. This plugin is independent of metadata and Git dates and does not require Git or another package. Without it, the theme does not generate robots.txt.

To customize crawl rules, add your own docs/robots.txt; an existing file always takes priority and is copied unchanged. The published file is static: page additions and edits do not require changing it. Update it when crawl rules or the domain/sitemap location changes; the generated default follows site_url automatically on rebuild.

Crawlers only consult robots.txt at the domain root. For sites hosted under a path such as example.com/project/, the generated project file must be published or incorporated at example.com/robots.txt by the hosting owner. Robots rules are not access control and do not guarantee removal from search results; protect private content through authentication.

Customize your site

Palette

Every theme color is configured from the single theme: block in mkdocs.yml. The default palette preserves Pixel Lab’s original appearance; override only the tokens your site needs:

theme:
  name: pixel-lab

  # Brand
  header_background: "#8315F9"
  accent_color: "#8315F9"
  accent_dark_color: "#5E0AAE"
  accent_foreground_color: "#FFFFFF"

  # Neutrals used by every component
  background_color: "#f4f1df"
  surface_color: "#fffdf2"
  surface_alt_color: "#e8e4cf"
  text_color: "#182018"
  muted_text_color: "#5f665d"
  border_color: "#101410"
  shadow_color: "#101410"

header_background accepts any CSS background value, including a linear gradient. All other options accept any valid CSS color, including rgba() and CSS variables.

This separation lets a site change its border and shadow independently without having to maintain CSS overrides or edit the theme.

The analytics acceptance button uses header_background and accent_foreground_color, matching the header background and site title without separate color settings.

Favicon

Pixel Lab includes a default favicon. Override it for a site-specific mark:

theme:
  name: pixel-lab
  favicon: assets/favicon.svg

The custom path is relative to your documentation directory. SVG and PNG favicons are supported.

Footer and branding

The site title includes a decorative pixel TM badge. Its circle and letter fill follow the title's text color; the glyph's outer and inner borders use the light and dark theme accents. Add a short footer message with theme.footer_text; the built-in Pixel Lab and Trained-by-Humans attribution remains below any related-site links:

theme:
  name: pixel-lab
  footer_text: Build something useful

Site navigation

Choose either inline links beside the site title or a dropdown beside Search, with an independent footer lane. All reuse extra.site_navigation; the dropdown shows every item, followed by the optional catalog link, without lane size limits.

extra:
  site_navigation:
    header_mode: dropdown # dropdown | inline | none
    show_footer: true
    dropdown_label: Packages # defaults to Sites
    header_size: 4 # includes the catalog link
    footer_size: 7 # includes the catalog link
    footer_label: Packages
    items:
      - title: Core
        url: https://ml-pipes.com/
        icon: assets/core.svg
      - title: Supervision
        url: https://supervision.ml-pipes.com/
        active: true
        icon: assets/supervision.svg
        icon_hover: assets/supervision.svg#icon-hover
      - title: Vision
        url: https://github.com/trained-by-humans/ml-pipes/tree/main/packages/vision
    catalog:
      title: All Packages →
      url: https://ml-pipes.com/PACKAGES/

Omit site_navigation to render no related-site navigation. When configured, header_mode selects one toolbar presentation: dropdown (the default), inline, or none. Use it in place of the previous show_header / show_dropdown flags; the two toolbar presentations never render together. show_footer independently controls the footer lane and defaults to true.

Inline header and footer lanes require a catalog link. The inline header renders up to header_size links and the footer up to footer_size; each capacity includes the catalog link. These sizes do not limit the dropdown. On narrow screens, the inline header hides and the footer links stack vertically.

Set each item's optional icon to an SVG/PNG path relative to the documentation directory or an absolute URL. Missing icons use a themed pixel fallback; icons appear only in the dropdown. The catalog can also specify an icon. The dropdown works without a catalog and marks the configured active item. Use Tab or arrow keys to navigate, and Escape to close it. Clicking outside also closes it. On small screens, the header buttons use icons while keeping accessible labels.

Optionally set icon_hover to an animated image URL. It replaces the resting icon on pointer hover or keyboard focus, restarts on each entry, and restores the static icon on exit or when the dropdown closes. Reduced-motion users retain the static icon. Hover images are fetched once and replayed from cached data; use a same-origin asset or an external URL that allows CORS. An SVG can use a fragment such as #icon-hover to activate its own :target animation, letting the same file supply both static and animated artwork. Hover-enabled icons have a 24 × 44 px image slot, including the row's vertical spacing. Add that breathing room inside both SVG canvases so the animation stays within the viewBox without shrinking the resting artwork. Missing or failed hover images leave the resting icon unchanged. Without icon_hover, icons stay static in a 24 × 24 px slot.

Analytics and privacy

Google Analytics 4

Analytics is off by default. Configure a GA4 Measurement ID (G-…, not a Firebase API key or Google Tag Manager ID) and your privacy-notice URL to enable the built-in opt-in prompt:

site_url: https://ml-pipes.com/
theme:
  name: pixel-lab
extra:
  analytics:
    provider: google
    measurement_id: G-XXXXXXXXXX
    privacy_policy: https://ml-pipes.com/privacy/

The prompt appears automatically on the first HTTPS visit matching site_url. Allow analytics loads the Google tag; Decline does not. Choices can be changed through Analytics settings in the footer. Withdrawal disables collection, attempts to clear the site's GA cookies, and reloads the page. Set enabled: false under analytics to turn the integration off. Google is currently the only supported analytics provider.

Privacy links

extra.analytics.privacy_policy is required: a missing, empty, or whitespace-only URL keeps analytics off. The same link appears in the consent prompt and footer, alongside Analytics settings when tracking is enabled. Retaining the URL with enabled: false keeps the policy link visible. Relative URLs such as privacy/ work from nested pages.

Publish a notice customized to your operator and data practices; Pixel Lab does not supply a universal privacy policy. Related sites may link to one shared notice that explicitly covers them.

Consent across sites

By default, consent is stored per documentation site URL and Measurement ID, including separate project paths on the same GitHub Pages hostname. To share acceptance and rejection across a custom domain and its subdomains, configure the same consent_domain and Measurement ID on every participating site:

extra:
  analytics:
    provider: google
    measurement_id: G-XXXXXXXXXX
    consent_domain: ml-pipes.com
    privacy_policy: https://ml-pipes.com/privacy/

Both acceptance and rejection are shared through a consent-only cookie scoped to that domain, with Secure, SameSite=Lax, Path=/, and a 180-day lifetime. The prompt identifies the shared domain. Use this only for sites you control under the same privacy policy, not public suffixes or shared hosting domains such as github.io. Other open sites synchronize changes on focus and periodically. Only consent is shared; GA cookies remain hostname-specific.

Unrelated or malformed domains disable analytics, and browsers reject public-suffix cookies. No parent domain is inferred automatically. Changing the consent scope requires a new choice; previous site-only choices are not silently promoted to domain-wide permission.