# squidfunk/mkdocs-material architecture

> Architecture diagram of the GitHub repository squidfunk/mkdocs-material, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/squidfunk/mkdocs-material
- Repository: https://github.com/squidfunk/mkdocs-material

## Overview

Material for MkDocs is a MkDocs theme and plugin suite for turning Markdown documentation into a searchable static site. The main workflow is authoring Markdown and having MkDocs render it; the repository also supplies search, blog, project, tags, social-card, privacy, offline, optimization, and other extensions. The tree contains parallel `src` and `material` packages; nodes retain key source-index modules from both. Relationships are limited to README and source-index references or visible calls; unsampled plugin wiring is not inferred.

Main entry points: [`material/plugins/search/plugin.py`](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/search/plugin.py) (Search index), [`material/utilities/filter/__init__.py`](https://github.com/squidfunk/mkdocs-material/blob/master/material/utilities/filter/__init__.py) (File filtering), [`material/plugins/blog/readtime/parser.py`](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/blog/readtime/parser.py) (Read-time parser), [`material/plugins/projects/builder/watcher/handler.py`](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/projects/builder/watcher/handler.py) (Project watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Theme and authoring"]
  node_theme["Material theme<br/>[__init__.py]"]
end

subgraph group_content["Content features"]
  node_markdown["Blog Markdown structure<br/>[markdown.py]"]
  node_blog["Blog plugin<br/>[plugin.py]"]
  node_readtime["Read-time parser<br/>[parser.py]"]
  node_projects["Projects plugin<br/>[plugin.py]"]
  node_projectwatch["Project watcher<br/>[handler.py]"]
  node_tags["Tags plugin<br/>[plugin.py]"]
end

subgraph group_enhance["Site enhancements"]
  node_search["Search index<br/>[plugin.py]"]
  node_info["Info plugin<br/>[plugin.py]"]
  node_social["Social cards<br/>[plugin.py]"]
  node_meta["Metadata plugin<br/>[plugin.py]"]
  node_privacy["Privacy parser<br/>[parser.py]"]
  node_offline["Offline plugin<br/>[plugin.py]"]
  node_optimize["Optimization plugin<br/>[plugin.py]"]
  node_typeset["Typesetting plugin<br/>[plugin.py]"]
  node_filter["File filtering<br/>[__init__.py]"]
  node_preview["Link previews<br/>[preview.py]"]
  node_emoji["Emoji extension<br/>[emoji.py]"]
end

subgraph group_sources["Mirrored source modules"]
  node_srcsearch["Search source<br/>[plugin.py]"]
  node_srcsocial["Social-card source<br/>[plugin.py]"]
  node_srcinfo["Info source<br/>[plugin.py]"]
  node_srcfilter["Filter source<br/>[config.py]"]
end

node_author(("Documentation author"))
node_mkdocs["MkDocs renderer"]

node_author -->|"authors Markdown"| node_mkdocs
node_mkdocs -->|"uses theme"| node_theme
node_mkdocs -->|"loads plugin"| node_search
node_projectwatch -->|"schedules build"| node_projects
node_preview -->|"filters links"| node_filter
node_readtime -->|"imports void tags"| node_search
node_info -.->|"mirrored implementation"| node_srcinfo
node_search -.->|"mirrored implementation"| node_srcsearch
node_social -.->|"mirrored implementation"| node_srcsocial
node_filter -.->|"mirrored implementation"| node_srcfilter

click node_theme "https://github.com/squidfunk/mkdocs-material/blob/master/material/templates/__init__.py"
click node_markdown "https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/blog/structure/markdown.py"
click node_blog "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/blog/plugin.py"
click node_readtime "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/blog/readtime/parser.py"
click node_projects "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/projects/plugin.py"
click node_projectwatch "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/projects/builder/watcher/handler.py"
click node_tags "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/tags/plugin.py"
click node_search "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/search/plugin.py"
click node_info "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/info/plugin.py"
click node_social "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/social/plugin.py"
click node_meta "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/meta/plugin.py"
click node_privacy "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/privacy/parser.py"
click node_offline "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/offline/plugin.py"
click node_optimize "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/optimize/plugin.py"
click node_typeset "https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/typeset/plugin.py"
click node_filter "https://github.com/squidfunk/mkdocs-material/blob/master/material/utilities/filter/__init__.py"
click node_preview "https://github.com/squidfunk/mkdocs-material/blob/master/material/extensions/preview.py"
click node_emoji "https://github.com/squidfunk/mkdocs-material/blob/master/material/extensions/emoji.py"
click node_srcsearch "https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/search/plugin.py"
click node_srcsocial "https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/social/plugin.py"
click node_srcinfo "https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/info/plugin.py"
click node_srcfilter "https://github.com/squidfunk/mkdocs-material/blob/master/src/utilities/filter/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_theme toneBlue
class node_markdown,node_blog,node_readtime,node_projects,node_projectwatch,node_tags toneAmber
class node_search,node_info,node_social,node_meta,node_privacy,node_offline,node_optimize,node_typeset,node_filter,node_preview,node_emoji toneMint
class node_srcsearch,node_srcsocial,node_srcinfo,node_srcfilter toneRose
class node_author,node_mkdocs toneIndigo
```

## Components

### Theme and authoring

- [Material theme](https://github.com/squidfunk/mkdocs-material/blob/master/material/templates/__init__.py): `material/templates/__init__.py`

### Content features

- [Blog Markdown structure](https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/blog/structure/markdown.py): `src/plugins/blog/structure/markdown.py`
- [Blog plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/blog/plugin.py): `material/plugins/blog/plugin.py`
- [Read-time parser](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/blog/readtime/parser.py): `material/plugins/blog/readtime/parser.py`
- [Projects plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/projects/plugin.py): `material/plugins/projects/plugin.py`
- [Project watcher](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/projects/builder/watcher/handler.py): `material/plugins/projects/builder/watcher/handler.py`
- [Tags plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/tags/plugin.py): `material/plugins/tags/plugin.py`

### Site enhancements

- [Search index](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/search/plugin.py): `material/plugins/search/plugin.py`
- [Info plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/info/plugin.py): `material/plugins/info/plugin.py`
- [Social cards](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/social/plugin.py): `material/plugins/social/plugin.py`
- [Metadata plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/meta/plugin.py): `material/plugins/meta/plugin.py`
- [Privacy parser](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/privacy/parser.py): `material/plugins/privacy/parser.py`
- [Offline plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/offline/plugin.py): `material/plugins/offline/plugin.py`
- [Optimization plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/optimize/plugin.py): `material/plugins/optimize/plugin.py`
- [Typesetting plugin](https://github.com/squidfunk/mkdocs-material/blob/master/material/plugins/typeset/plugin.py): `material/plugins/typeset/plugin.py`
- [File filtering](https://github.com/squidfunk/mkdocs-material/blob/master/material/utilities/filter/__init__.py): `material/utilities/filter/__init__.py`
- [Link previews](https://github.com/squidfunk/mkdocs-material/blob/master/material/extensions/preview.py): `material/extensions/preview.py`
- [Emoji extension](https://github.com/squidfunk/mkdocs-material/blob/master/material/extensions/emoji.py): `material/extensions/emoji.py`

### Mirrored source modules

- [Search source](https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/search/plugin.py): `src/plugins/search/plugin.py`
- [Social-card source](https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/social/plugin.py): `src/plugins/social/plugin.py`
- [Info source](https://github.com/squidfunk/mkdocs-material/blob/master/src/plugins/info/plugin.py): `src/plugins/info/plugin.py`
- [Filter source](https://github.com/squidfunk/mkdocs-material/blob/master/src/utilities/filter/config.py): `src/utilities/filter/config.py`

### Other components

- **Documentation author**
- **MkDocs renderer**

## Connections

- Documentation author → MkDocs renderer: authors Markdown (evidence: `README.md`)
- MkDocs renderer → Material theme: uses theme
- MkDocs renderer → Search index: loads plugin
- Project watcher → Projects plugin: schedules build (evidence: `material/plugins/projects/builder/watcher/handler.py`)
- Link previews → File filtering: filters links (evidence: `material/extensions/preview.py`)
- Read-time parser → Search index: imports void tags (evidence: `material/plugins/blog/readtime/parser.py`)
- Info plugin → Info source: mirrored implementation
- Search index → Search source: mirrored implementation
- Social cards → Social-card source: mirrored implementation
- File filtering → Filter source: mirrored implementation
