Model Project¶

A real Void website is a small, boring set of files that produces a distinctive site. This page is the annotated, copy-pasteable layout of a typical project — where each file lives, where assets go, and how the two configuration surfaces (theme.void and the - void: plugin block) merge.

The layout¶

my-docs/
├── mkdocs.yml                  # the whole look & behavior lives here
├── requirements.txt            # mkdocs + mkdocs-void (and friends)
├── docs/                       # your content; markdown becomes the site
│   ├── index.md                # home page
│   ├── guide/
│   │   ├── index.md
│   │   └── installation.md
│   ├── assets/
│   │   ├── images/             # referenced from markdown (logos, screenshots)
│   │   │   ├── logo-dark.svg
│   │   │   └── logo-light.svg
│   │   ├── stylesheets/        # optional extra CSS (theme.void.custom_css)
│   │   └── javascripts/        # optional extra JS (theme.void.custom_js)
│   └── about.md
├── .github/
│   └── workflows/
│       └── pages.yml           # build + deploy to GitHub Pages
├── site/                       # build output, gitignored (mkdocs build)
└── .gitignore

File-by-file¶

File	Role
`mkdocs.yml`	Aggregates everything: `theme.name: void`, the `theme.void.` settings, the `plugins:` block, and `extra.` brand fields
`requirements.txt`	Pins `mkdocs` and `mkdocs-void` so builds are reproducible; third-party recipes add more here
`docs/**`	Your content. Every `.md` becomes a page; a `nav:` block in `mkdocs.yml` (or the default of walking the tree) turns it into navigation
`docs/assets/`	Non-page files: images you reference from markdown, plus any custom CSS/JS you wire in via `theme.void.custom_css` / `custom_js`
`.github/workflows/pages.yml`	Optional but standard — build `site/` and deploy to GitHub Pages (see Deployment)
`site/`	Generated by `mkdocs build`; always gitignored

Where assets live¶

Assets are plain files inside docs/, referenced by markdown or by config:

Images in content — a screenshot sits at docs/assets/images/search.png and is referenced as ![Search](assets/images/search.png).
Logo — theme.logo sets the default; for the dark-aware logo swap set extra.void_logo_dark and extra.void_logo_light (the theme picks the right one per active scheme).
Favicon — extra.void_favicon_dark / extra.void_favicon_light, falling back to theme.favicon.
Social card — extra.void_og_image pins the social preview image; the theme also auto-generates cards and structured data per page (see Configuration).

The two config surfaces and how they merge¶

Void exposes the same settings from two places, and every key is valid in both:

theme.void — the "front door" under the standard theme: block.
the - void: plugin block — inline options in plugins:, useful for per-deploy overrides and for tools that generate mkdocs.yml.

At build time the bundled plugin resolves the effective config in one pass:

built-in defaults (_void_defaults, component defaults)
        ↓  (any key still missing)
theme.void  ←  wherever you set it
        ↓  (deep-merge; the plugin block wins on conflicts)
- void: plugin options
        ↓  (validated as one unit — a bad value fails loudly)
rendered site

Concretely: the plugin sets sane defaults for anything you leave out, deep-merges your theme.void over them, then deep-merges anything written inline in the - void: block on top — so an inline option always wins — and finally validates the combined result as a single configuration. Options are never dropped; whatever you do not set keeps its default.

# mkdocs.yml — a typical, fully working project
site_name: My Docs
site_url: https://user.github.io/my-docs/
repo_url: https://github.com/user/my-docs

theme:
  name: void
  logo: assets/images/logo-dark.svg
  palette:
    scheme: slate
  font:                        # Space Grotesk for text, Space Mono for code
    text: Space Grotesk
    code: Space Mono
  void:
    glass: medium              # light | medium | heavy
    dot_matrix: true           # NothingOS texture overlay
    animation: normal          # normal | reduced | none
    border: thin
    highlight: true
    notes: true                # notes panel
    notes_ttl: 7               # days before a note expires
    components:
      notes:
        show: true             # component toggle (all ON by default)
    action_cluster:
      position: bottom-right   # bottom-left | bottom-right
    timer:
      default_minutes: 25
    announcement_bar:
      text: "v0.3.0 is live"
      position: top
      pinned: false

plugins:
  - search
  - void                      # every key from theme.void is valid here too

extra:
  void_site_tagline: Beauty in broken glass
  void_showcase: true         # "Powered by Void" credit + badge
  # dark-aware branding
  void_logo_dark: assets/images/logo-dark.svg
  void_logo_light: assets/images/logo-light.svg

# requirements.txt
mkdocs
mkdocs-void

Run it¶

pip install -r requirements.txt
mkdocs serve                   # live preview at http://127.0.0.1:8000

Stage a build with mkdocs build (writes site/) and deploy it anywhere — see Deployment for GitHub Pages, any static host, and Docker.

Next steps¶

Configuration — the complete, generated reference for every key in both surfaces.
Void Plugin — how search + void work together and the plugin-block specifics.

Back to README