<!-- Generated by Void for AI agents. -->
<!-- Site: Void Documentation -->
<!-- URL: https://rkriad585.github.io/mkdocs-void/getting-started/model-project.md -->
<!-- Generated: 2026-09-20T05:09:32Z -->
<!-- Version: 0.3.0 -->

# 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

```tree
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](../deployment.md)) |
| `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](../getting-started/configuration.md)).

## The two config surfaces and how they merge

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

1. **`theme.void`** — the "front door" under the standard `theme:` block.
2. **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:

```text
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.

```yaml
# 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
```

```text
# requirements.txt
mkdocs
mkdocs-void
```

## Run it

```bash
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](../deployment.md) for GitHub Pages, any static host, and Docker.

## Next steps

- [Configuration](configuration.md) — the complete, generated reference for
  every key in both surfaces.
- [Void Plugin](../plugins/void.md) — how `search` + `void` work together and
  the plugin-block specifics.

---

[Back to README](../index.md)

<!-- End of markdown mirror. -->