Configuration¶

Void is configured through the theme key in your mkdocs.yml.

Basic setup¶

site_name: My Docs
theme:
  name: void

Full configuration¶

site_name: My Docs
theme:
  name: void
  favicon: assets/images/favicon.svg
  language: en
  direction: ltr
  palette:
    - scheme: slate
      primary: black
      accent: red
      toggle:
        name: Switch to light mode
    - scheme: default
      primary: white
      accent: red
      toggle:
        name: Switch to dark mode
  font:
    text: Space Grotesk
    code: Space Mono
  features:
    - navigation.sections
    - navigation.top
    - navigation.footer
    - content.code.copy
    - search.suggest
    - search.highlight
  void:
    glass: medium
    dot_matrix: true
    animation: normal
    border: thin
    content:
      typography:
        image_lightbox: true  # click-to-zoom image preview in the article (default true; set false to disable)

plugins:
  - search
  - void

Options reference¶

palette¶

Controls the color scheme and toggle behavior. Uses MkDocs' standard palette system.

palette:
  - scheme: slate       # dark mode
    primary: black
    accent: red
    toggle:
      name: Switch to light mode
  - scheme: default     # light mode
    primary: white
    accent: red
    toggle:
      name: Switch to dark mode

void.glass¶

Sets the global glass intensity. This controls backdrop-filter blur and transparency on panels, cards, and navigation.

void:
  glass: heavy

void.dot_matrix¶

Enables or disables the dot matrix background pattern behind content.

void:
  dot_matrix: true

void.border¶

Controls the border style on glass panels.

void:
  border: thin

void.animation¶

Controls entrance and hover animations.

void:
  animation: normal

font¶

Override the default typefaces. The resolved families drive the Google Fonts <link> and the --void-font-body / --void-font-mono tokens, so the font stack updates automatically.

font:
  text: Space Grotesk
  code: Space Mono

If you also set theme.void.typography.font_family / font_family_mono, the theme.font values take precedence.

features¶

Recognized as a Material-compatible passthrough: Void ships every feature below enabled by default, so the list does not gate any behavior. Omit it or list these flags freely — the rendered site is identical:

• navigation.sections — Section-grouped sidebar navigation
• navigation.top — Back-to-top button and reading progress bar
• navigation.footer — Previous/next navigation in the footer
• content.code.copy — Copy button on code blocks
• search.suggest — As-you-type search suggestions
• search.highlight — Highlight matched terms in search results

features:
  - navigation.sections
  - navigation.top
  - content.code.copy

To change any single behavior, use the corresponding theme.void.* switch instead.

void.social_cards¶

Share + indexing surface. When on (default), every page emits an Article JSON-LD block in <head>, and — when extra.void_og_image is set to the literal value "__auto__" — a per-page OG card image is generated at build time and published as the page's og:image.

void:
  social_cards:
    enabled: true   # master on/off
    jsonld: true    # Article JSON-LD in <head>
    cards: true     # auto og:image cards when extra.void_og_image = __auto__

Set enabled: false to strip the whole surface; keep enabled but flip jsonld or cards to disable one half independently. Card rendering needs Pillow for PNG files — install it with pip install mkdocs-void[social-cards] — and falls back to a crisp standalone SVG when Pillow is absent.

extra:
  void_og_image: __auto__   # generate per-page social cards at build time

void.meta¶

Freshness + "edit the source" bar. A small metadata row under the content: a "Last updated" date and an "Edit this page" link. The date is picked from page.meta.git_revision_date_localized (set by the mkdocs-git-revision-date-localized plugin; install the PyPI package mkdocs-git-revision-date-localized-plugin) and falls back to the page's date: front matter when the plugin is not installed — or is omitted entirely when neither exists (never breaks).

theme:
  name: void
  void:
    meta:
      enabled: true                # master on/off
      show_last_updated: true
      show_edit_on_github: true
      date_source: auto            # auto | git | front_matter
      branch: main
      source_dir: docs

The edit link is built as {repo_url}/blob/{branch}/{source_dir}/{page.file.src_uri} and only renders when config.repo_url is set. A page can override either row per-page via front matter:

---
void:
  meta:
    show_last_updated: false      # hide the date on this page
---

void.feedback¶

"Was this page helpful?" widget. Renders under the article and opens a prefilled GitHub issue (positive/negative) in a new tab — a plain issue link, no analytics. Only appears when config.repo_url is set.

theme:
  void:
    feedback:
      enabled: true
      github_labels: [feedback]

void.announcement_bar¶

Announcement bar: a floating card pinned near an edge. Off by default — it renders only when enabled: true and a non-empty text are set. The text comes from announcement_bar.text (wins) or the legacy extra.void_announce string. Dismissal persists in localStorage keyed by the text, so changing the announcement re-shows it. position picks where the card floats (top/right/bottom/left); center opens it as a popup with a dimmed backdrop that also dismisses on click.

theme:
  void:
    announcement_bar:
      enabled: true    # opt-in — hidden by default
      text: New in v0.2 — glass components are here!
      position: top    # top | right | bottom | left | center

void.cookie_consent¶

Consent banner. Privacy-first: Void never tracks readers, so the banner is rendered only when the build detects a configured integration (theme.analytics.gtag or giscus comments enabled with repo + repo_id) — unless you opt in to always showing it with render: always (for demo sites). The banner itself stores just an accept/decline flag in localStorage; "Accept" unlocks delayed integrations like giscus.

theme:
  void:
    cookie_consent:
      message: We only store your explicit choices.
      privacy_policy: /privacy/
      render: always          # demo sites: force-show without an integration
      position: bottom        # top | right | bottom | left | center

void.comments¶

Opt-in comments via giscus (the only supported provider). Comments are hidden by default — nothing renders unless you set enabled: true. Even then, nothing loads until both repo and repo_id are configured; when a consent-serving integration is present, the giscus script is deferred until the reader clicks "Accept". The giscus theme follows the active palette.

Use an Announcements-type category: in it only maintainers and the giscus bot can start discussions, so visitors can comment but never create threads. With mapping: pathname (default), each page maps to a discussion whose title equals that page's pathname without the leading slash — e.g. this repo's home page (/mkdocs-void/) maps to a discussion titled mkdocs-void/. Grab the exact repo_id / category_id on the giscus setup page.

theme:
  void:
    comments:
      enabled: true          # opt-in — comments are hidden by default
      repo: "user/mkdocs-docs"
      repo_id: "R_kgxxxx"
      category: "Announcements"    # Announcements-type so only you/giscus post
      category_id: "DIC_xxxx"
      mapping: pathname            # each page maps to a discussion named by pathname

site_url & link rebasing¶

Set site_url to your deployed address (e.g. https://user.github.io/project). Navigation, TOC, and content links are always emitted relative, so they work unchanged on any origin. Absolute URLs are only produced where they are required (canonical, og:url, share) and MkDocs itself rewrites them to the live server URL during mkdocs serve.

On top of that, the plugin captures the production site_url before the dev server overrides it and hands it to the theme as config.site_url. When you preview on localhost:{port} and the page contains a link that was baked or hardcoded with the main site URL (e.g. [x](https://user.github.io/project/guide/)), the theme re-targets that link to localhost:{port}/guide/ at runtime, so a click never leaves the preview. External links, relative links, and the deployed origin itself are never touched.

Options reference index¶

Every theme.void.* key is documented per-key — Default, CSS variable, a purpose, and a copyable example — in the generated reference pages below. They are emitted from the plugin's own source tables (_VOID_TOKEN_MAP, _void_defaults, and the _VOID_DEFAULT_* dicts) by tools/emit_config_reference.py, so they can never drift from shipped code (CI re-checks them on every build):

Every option at a glance:

• Kitchen sink — a copy-paste mkdocs.yml block with every theme.void.* key set to its shipped default.

Regenerate the reference any time the plugin changes:

python tools/emit_config_reference.py

extra.void_showcase¶

Footer credit: an opt-in one-line "Powered by Void" badge in the site footer. Off by default — set extra.void_showcase: true to show it. The badge is a self-contained inline SVG (a dot-matrix mark echoing the NothingOS canvas) that links back to the project, so enabling it adds no third-party image or CDN request. extra.void_showcase_url overrides the default link target; the label text follows theme.void.i18n.footer_powered_by.

extra:
  void_showcase: true                 # Opt-in footer credit + badge
  void_showcase_url: "https://github.com/rkriad585/mkdocs-void"   # Optional

Plugin configuration¶

Void ships with an optional MkDocs plugin that sets theme defaults. See the Plugin documentation for details.

Adding custom CSS¶

Add custom stylesheets via extra_css:

extra_css:
  - stylesheets/custom.css

Place the file at docs/stylesheets/custom.css.

Override any design token:

:root {
  --void-accent: #818cf8;
  --void-canvas: #050510;
}

Adding custom JavaScript¶

Add custom scripts via extra_javascript:

extra_javascript:
  - javascripts/custom.js