Skip to content
Configuration
Void
Github.com

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
Option Values Description
scheme "slate", "default" Color scheme (slate = dark, default = light)
primary "black", "white" Primary background tone
accent "red" Accent color (Nothing Red)
toggle.name string Label for the toggle button

void.glass

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

Value Blur Saturation Background opacity Effect
"light" 10px 1.0 5% Subtle blur, high transparency
"medium" 20px 1.2 8% Balanced blur and opacity (default)
"heavy" 30px 1.4 12% Strong blur, lower transparency 
void:
  glass: heavy

void.dot_matrix

Enables or disables the dot matrix background pattern behind content.

void:
  dot_matrix: true

Warning

Disabling dot_matrix removes the background texture. The theme still works, but loses a signature visual element.

void.border

Controls the border style on glass panels.

Value Description
"thin" 1px semi-transparent borders (default)
"thick" 2px borders
"none" No borders on glass panels 
void:
  border: thin

void.animation

Controls entrance and hover animations.

Value Description
"normal" Enable animations (default)
"none" Disable all animations 
void:
  animation: normal

Note

Animations are automatically disabled when the user has prefers-reduced-motion: reduce set in their OS.

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.

Tip

The fonts are loaded from Google Fonts automatically. You can self-host by overriding the CSS and providing your own @font-face rules.

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.

Key Default Description
enabled true Master switch for the whole social-cards/JSON-LD surface
jsonld true Emit per-page Article JSON-LD structured data
cards true Auto-generate per-page OG card images (__auto__ mode) 
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

Tip

A page.meta.image in a page's front matter overrides the auto-generated card for that page. If no card exists for a page (e.g. 404 pages), the OG block falls back to a summary Twitter card.

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).

Key Default Description
enabled true Master switch for the metadata bar
show_last_updated true Show the "Last updated" date row
show_edit_on_github true Show the "Edit this page" link
last_updated_label "Last updated" Label before the date
edit_label "Edit this page" Link text
date_source "auto" auto (git first, then front matter), git, or front_matter
branch "main" Repository branch used for the edit link
source_dir "docs" Source folder used for the edit link 
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.

Key Default Description
enabled true Master switch for the feedback widget
show true Render the widget under the article
title "Was this page helpful?" Widget heading
positive "Yes — thanks!" "Yes" button label
negative "No — open an issue" "No" button label
github_labels ["feedback"] GitHub issue labels applied to each opened issue 
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.

Key Default Description
enabled false Master switch — hidden by default; set true to opt in
show true Render the bar
text "" Announcement text; empty falls back to extra.void_announce
dismissable true Show the × dismiss button (false pins the card)
position "bottom" Floating placement: top, right, bottom, left, or center (popup + backdrop) 
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

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.

Key Default Description
enabled true Master switch for the banner
show true Render the banner
render "auto" When to show: auto (only with a configured integration), always, or never
position "bottom" Floating placement: top, right, bottom, left, or center (popup + backdrop)
message "This site stores nothing about you unless you enable integrations." Banner text
accept_label "Accept" Accept button label
decline_label "Decline" Decline button label
privacy_policy "" Optional privacy policy path; rendered when set 
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.

Key Default Description
enabled false Master switch — comments are hidden by default; set true to opt in
provider "giscus" Provider (only giscus today)
repo "" GitHub owner/repo; required to enable
repo_id "" giscus repo ID from the setup page
category "" Discussion category (must be an "Announcements"-type)
category_id "" giscus category ID
mapping "pathname" pathname, url, title, og:title, or specific
term "" Term used with the specific mapping
language "" giscus language code (falls back to giscus default)
theme.light / theme.dark "light" / "dark" giscus themes for each palette 
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

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.

Generated reference

The canonical reference below is emitted from the plugin's own source tables (_VOID_TOKEN_MAP, _void_defaults, and the _VOID_DEFAULT_* dicts) by tools/emit_config_reference.py. Regenerate it any time the plugin changes so docs and config can never drift:

python tools/emit_config_reference.py

defaults:
  animation: normal
  border: thin
  dot_matrix: true
  glass: medium
  highlight: true
  notes: true
sections:
  action_cluster:
    actions:
    - badge: none
      enabled: true
      icon: help
      id: keyboard_help
      label: Keyboard shortcuts
      shortcut: '?'
    - badge: none
      enabled: true
      icon: notes
      id: notes
      label: Open notes panel
      shortcut: Ctrl+Shift+N
    - badge: time
      enabled: true
      icon: timer
      id: timer
      label: Focus timer
      shortcut: Alt+Shift+T
    - badge: none
      enabled: true
      icon: reading
      id: reading_mode
      label: Reading mode
      shortcut: Alt+Shift+R
    behavior:
      animation: normal
      close_on_escape: true
      close_on_outside: true
      close_on_select: true
      focus_trap: true
      min_actions: 2
      tooltips: true
    enabled: true
    main:
      glass: true
      icon: plus
      icon_transform: true
      size: 44px
    offset:
      bottom: 16px
      left: 16px
    position: bottom-left
    replaces_notes_button: true
  ai_reader:
    auto_title: true
    description: ''
    enabled: true
    exclude: []
    llms: true
    llms_full: true
    markup: true
    overwrite: false
    sitemap: true
    url_style: sidecar
    watermark:
      enabled: true
      footer: true
      header: true
      include_generated: true
      include_site: true
      include_url: true
      include_version: true
      text: Generated by Void for AI agents.
  announcement_bar:
    dismissable: true
    enabled: false
    position: bottom
    show: true
    text: ''
  assets (cdn | local | bundle):
    inline_critical_css: false
    mode: cdn
    timeout: 20
    vendor_dir: assets/vendor
  breadcrumbs:
    show: true
  comments:
    category: ''
    category_id: ''
    enabled: false
    language: ''
    mapping: pathname
    provider: giscus
    repo: ''
    repo_id: ''
    term: ''
    theme:
      dark: dark
      light: light
  components (visible surfaces):
    admonitions:
      show: true
    announcement_bar:
      show: true
    code:
      show_copy_button: true
    content:
      show: true
      show_back_to_top: true
      show_progress_bar: true
    cookie_consent:
      show: true
    feedback:
      show: true
    footer:
      copyright_text: ''
      show: true
      show_copyright: true
      show_meta: true
      show_prev_next: true
    giscus:
      show: true
    header:
      show: true
      show_logo: true
      show_page_title: true
      show_palette_toggle: true
      show_repo_link: true
      show_search: true
      show_site_name: true
    highlighting:
      cdn_css_url: ''
      cdn_url: ''
      show: true
      theme_dark: github-dark
      theme_light: github
    keyboard_help:
      show: true
    math:
      cdn_css_url: ''
      cdn_url: ''
      show: true
    mermaid:
      cdn_url: ''
      show: true
    notes:
      show: true
    prefetch:
      exclude: []
      external: false
      show: true
    repo_popover:
      fields:
      - description
      - owner_bio
      - author
      - followers
      - public_repos
      - location
      - stars
      - watchers
      - forks
      - open_issues
      - language
      - license
      - default_branch
      - commits
      - tags
      - latest_commit
      - commit_msg
      - created
      - updated
      - pushed
      show: true
    search:
      placeholder: Search...
      shortcut_key: /
      show: true
    sidebar:
      show: true
    tags:
      show: true
    toast:
      show: true
    toc:
      show: true
      show_level_h2: true
      show_level_h3: true
      show_level_h4: true
      title: On this page
  content:
    admonitions:
      enabled: true
      types:
        danger:
          color: ''
          icon: ''
        info:
          color: ''
          icon: ''
        note:
          color: ''
          icon: ''
        success:
          color: ''
          icon: ''
        tip:
          color: ''
          icon: ''
        warning:
          color: ''
          icon: ''
    back_to_top_label: Back to top
    back_to_top_threshold: 500
    code:
      annotate: true
      copied_label: ''
      copy_label: ''
      highlight_lines: true
      line_number_color: ''
      line_number_start: 1
      show_copy_button: true
      show_line_numbers: false
    glass: false
    max_width: ''
    padding: ''
    progress_bar_color: ''
    show_back_to_top: true
    show_progress_bar: true
    tables:
      bordered: false
      responsive: true
      striped: false
    task_lists:
      custom_checkbox: true
      enabled: true
      persist_state: true
    typography:
      anchor_symbol: ''
      heading_anchor: true
      image_behavior: normal
      image_lightbox: true
      link_behavior: smooth
      video_behavior: responsive
  cookie_consent:
    accept_label: Accept
    decline_label: Decline
    enabled: true
    message: This site stores nothing about you unless you enable integrations.
    position: bottom
    privacy_policy: ''
    render: auto
    show: true
  feedback:
    enabled: true
    github_labels:
    - feedback
    negative: "No \u2014 open an issue"
    positive: "Yes \u2014 thanks!"
    show: true
    title: Was this page helpful?
  i18n:
    a11y:
      breadcrumb: Breadcrumb
      skipToContent: Skip to content
    clipboard:
      copied: Copied to clipboard
      copy: Copy to clipboard
      copyLink: Copy link
      copyLinkFailed: "Copy link failed \u2014 clipboard unavailable"
      linkCopied: Link copied
    comments:
      title: Comments
    footer:
      next: Next
      poweredBy: Powered by Void
      previous: Previous
    help:
      title: Keyboard shortcuts
    navigation:
      label: Navigation
    notes:
      add: + Add note
      cancel: Cancel
      close: Close notes
      colorPrefix: 'Color '
      delete: Delete
      empty: No notes yet.
      exportJson: Export .json
      exportMd: Export .md
      notes: Notes
      placeholder: "Write a note\u2026"
      save: Save
      saveChanges: Save changes
    repo:
      author: Author
      commitMsg: Last commit msg
      commits: Commits
      created: Created
      defaultBranch: Default branch
      followers: Followers
      forks: Forks
      language: Language
      latestCommit: Latest commit
      latestTag: 'latest '
      license: License
      licenseNone: None
      loadError: Unable to load repo data
      location: Location
      noPublicData: No public data
      openIssues: Open issues
      publicRepos: Public repos
      pushed: Last pushed
      stars: Stars
      status: Status
      tags: Tags
      updated: Last updated
      watchers: Watchers
    search:
      loadError: Search index could not be loaded.
      loading: Loading search...
      noResults: No results found
      placeholder: Search
      results: Results
      startTyping: Start typing to search...
      suggestions: Search suggestions
    timer:
      bar: Bar
      bottom: Bottom
      cancel: Cancel
      chime: Chime on completion
      close: Close
      complete: Focus session complete
      controls: Timer controls
      digits: Digits
      focus: Focus
      readingChip: Reading-mode chip
      reset: Reset timer
      restart: Restart timer
      ring: Ring
      sessionLength: Session length (minutes)
      settings: Focus timer settings
      start: Start timer
      startSession: Start session
      stop: Stop timer
      title: Focus Timer
      toastNotify: Toast on completion
      tocPosition: TOC timer position
      tocStyle: TOC timer style
      top: Top
    toc:
      backToTop: Back to top
      title: On this page
    zoom:
      close: Close preview
      copyImage: Copy image
      downloadImage: Download image
      next: Next image
      preview: Image preview
      previous: Previous image
      zoomIn: Zoom in
      zoomOut: Zoom out
  keyboard (shortcuts):
    custom: []
    enabled: true
    shortcuts:
      close:
        enabled: true
        key: Escape
        label: Close active overlay
      help:
        enabled: true
        key: '?'
        label: Show keyboard shortcuts
      search:
        enabled: true
        key: /
        label: Open search
      search_down:
        enabled: true
        key: ArrowDown
        label: Navigate search results down
      search_open:
        enabled: true
        key: Enter
        label: Open selected result
      search_up:
        enabled: true
        key: ArrowUp
        label: Navigate search results up
      tab_left:
        enabled: true
        key: ArrowLeft
        label: Switch to previous tab
      tab_right:
        enabled: true
        key: ArrowRight
        label: Switch to next tab
      toggle_notes:
        enabled: true
        key: Ctrl+Shift+N
        label: Toggle notes panel
      toggle_reading_mode:
        enabled: true
        key: Alt+Shift+R
        label: Toggle reading mode
        persisted: true
      toggle_repo_popover:
        enabled: true
        key: Ctrl+Shift+G
        label: Toggle repo popover
      toggle_scheme:
        enabled: true
        key: Ctrl+Shift+L
        label: Toggle color scheme
      toggle_sidebar:
        enabled: true
        key: Ctrl+Shift+B
        label: Toggle sidebar
        persisted: true
      toggle_toc:
        enabled: true
        key: Ctrl+Shift+T
        label: Toggle table of contents
        persisted: true
  meta:
    branch: main
    date_source: auto
    edit_label: Edit this page
    enabled: true
    last_updated_label: Last updated
    show_edit_on_github: true
    show_last_updated: true
    source_dir: docs
  pwa:
    background_color: '#111114'
    display: standalone
    icons: true
    manifest: true
    start_url: ''
    theme_color: ''
  reading_mode:
    enabled: true
    notes:
      open_on_enter: false
      show: true
    persisted: true
    sections:
      footer: true
      header: true
      progress: true
      sidebar: true
      toc: true
    shortcut_key: Alt+Shift+R
    typography:
      font_size: 1.125rem
      line_height: '1.75'
      measure: 100%
  social_cards:
    cards: true
    enabled: true
    jsonld: true
  timer:
    badge_in_cluster: true
    colors:
      progress: '#8a5a33'
    default_minutes: 25
    display_format: mm:ss
    document_title: false
    enabled: true
    notifications:
      enabled: true
      sound: true
      toast: true
    persist: true
    reading:
      show: true
    settings_popup: true
    start_with_reading: false
    toc:
      position: bottom
      show: true
      style: ring
tokens:
  border_radius:
    large: --void-radius-lg
    medium: --void-radius-md
    small: --void-radius-sm
  colors:
    background: --void-ink
    border: --void-glass-border
    overlay: --void-overlay-color
    primary: --void-accent
    primary_dark: --void-accent-strong
    primary_light: --void-accent-glow
    surface: --void-glass-bg
    surface_light: --void-glass-bg-strong
    text: --void-text-primary
    text_secondary: --void-text-secondary
  shadows:
    large: --void-shadow-lg
    medium: --void-shadow-md
    small: --void-shadow-sm
  spacing:
    content_max_width: --void-content-max-width
    content_padding: --void-content-padding
    header_height: --void-header-height
    section_gap: --void-section-gap
    sidebar_width: --void-sidebar-width
    toc_width: --void-toc-width
  transitions:
    duration: --void-transition-duration
    easing: --void-transition-easing
  typography:
    font_family: --void-font-body
    font_family_display: --void-font-display
    font_family_mono: --void-font-mono
    font_size_base: --void-font-size-base
    font_size_lg: --void-font-size-lg
    font_size_sm: --void-font-size-sm
    heading_letter_spacing: --void-heading-letter-spacing
    heading_weight: --void-heading-weight
    line_height: --void-line-height

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