### Start Development Watcher
Source: https://squidfunk.github.io/mkdocs-material/customization
Start the build watcher and the MkDocs live preview server.
```bash
npm start
```
```bash
mkdocs serve --watch-theme
```
--------------------------------
### Define site structure
Source: https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site
Example directory structure for a multi-project site setup.
```text
.
└── /
├── subsite-a/
├── subsite-b/
└── subsite-c/
```
--------------------------------
### Install Dependencies from Requirements File
Source: https://squidfunk.github.io/mkdocs-material/getting-started
Install all project dependencies, including MkDocs and Material for MkDocs, from a requirements.txt lockfile.
```bash
pip install -r requirements.txt
```
--------------------------------
### Start the live preview server
Source: https://squidfunk.github.io/mkdocs-material/creating-your-site
Launch the local development server with live reloading enabled.
```bash
mkdocs serve --livereload
```
--------------------------------
### Setup Virtual Environment
Source: https://squidfunk.github.io/mkdocs-material/customization
Create and activate a Python virtual environment.
```bash
python -m venv venv
source venv/bin/activate
```
--------------------------------
### Install Node.js Dependencies
Source: https://squidfunk.github.io/mkdocs-material/customization
Install Node.js and project dependencies.
```bash
nodeenv -p -n lts
npm install
```
--------------------------------
### Install glightbox Plugin
Source: https://squidfunk.github.io/mkdocs-material/reference/images
Install the glightbox plugin using pip to add image zoom functionality to your documentation.
```bash
pip install mkdocs-glightbox
```
--------------------------------
### Start the preview server with Docker
Source: https://squidfunk.github.io/mkdocs-material/creating-your-site
Run the development server inside a Docker container, mapping port 8000.
```bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```
```bash
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
```
--------------------------------
### Install Material for MkDocs from Local Clone
Source: https://squidfunk.github.io/mkdocs-material/getting-started
Install Material for MkDocs in editable mode from a local clone of the repository, along with its dependencies.
```bash
pip install -e mkdocs-material
```
--------------------------------
### Install the RSS plugin
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog
Install the required RSS plugin via pip.
```bash
pip install mkdocs-rss-plugin
```
--------------------------------
### Create a blog post with front matter
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog
Example of a blog post file with draft status, date, and categories.
```markdown
---
draft: true
date: 2024-01-31
categories:
- Hello
- World
---
# Hello world!
...
```
--------------------------------
### Show Installed Version
Source: https://squidfunk.github.io/mkdocs-material/upgrade
Check the currently installed version of Material for MkDocs using this command.
```bash
pip show mkdocs-material
```
--------------------------------
### Install Latest Material for MkDocs with pip
Source: https://squidfunk.github.io/mkdocs-material/getting-started
Install the latest stable version of Material for MkDocs using pip. It's recommended to use a virtual environment.
```bash
pip install mkdocs-material
```
--------------------------------
### Install latest release with pip
Source: https://squidfunk.github.io/mkdocs-material/insiders
Installs the latest release of Material for MkDocs Insiders using pip. Ensure the GH_TOKEN environment variable is set.
```bash
pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
```
--------------------------------
### Define meta file structure
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog
Example directory structure for using .meta.yml to set default front matter.
```text
.
├─ docs/
│ └─ blog/
│ ├─ posts/
│ ├─ .meta.yml
│ └─ index.md
└─ mkdocs.yml
```
--------------------------------
### Card Grid - List Syntax (Complex Example)
Source: https://squidfunk.github.io/mkdocs-material/reference/grids
A more advanced list syntax example for card grids, including icons, titles, descriptions, and links. Note the use of '.lg .middle' for icon sizing and alignment, and '---' for a visual separator.
```html
- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
---
Install [`mkdocs-material`](#) with [`pip`](#) and get up
and running in minutes
[:octicons-arrow-right-24: Getting started](#)
- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
---
Focus on your content and generate a responsive and searchable static site
[:octicons-arrow-right-24: Reference](#)
- :material-format-font:{ .lg .middle } __Made to measure__
---
Change the colors, fonts, language, icons, logo and more with a few lines
[:octicons-arrow-right-24: Customization](#)
- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
---
Material for MkDocs is licensed under MIT and available on [GitHub]
[:octicons-arrow-right-24: License](#)
```
--------------------------------
### Install MkDocs RSS Plugin
Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage
Install the MkDocs RSS Plugin using pip. This is a prerequisite for enabling RSS feed functionality.
```bash
$ pip install mkdocs-rss-plugin
```
--------------------------------
### Install Python Dependencies
Source: https://squidfunk.github.io/mkdocs-material/customization
Install required Python packages for development.
```bash
pip install -e ".[git, recommended, imaging]"
pip install nodeenv
```
--------------------------------
### Basic Blog Plugin Configuration
Source: https://squidfunk.github.io/mkdocs-material/plugins/blog
Add this to your mkdocs.yml to enable the blog plugin. It's built-in and requires no separate installation.
```yaml
plugins:
- blog
```
--------------------------------
### Install Insiders from local git repository
Source: https://squidfunk.github.io/mkdocs-material/insiders/upgrade
After checking out the desired version, change back to the parent directory and use pip to install the Insiders version in editable mode.
```bash
cd ..
pip install -e mkdocs-material
```
--------------------------------
### Example JSON with Annotations
Source: https://squidfunk.github.io/mkdocs-material/reference/code-blocks
Demonstrates usage of annotations within a JSON string.
```json
{
"key": "value
}
```
--------------------------------
### Install specific release with pip
Source: https://squidfunk.github.io/mkdocs-material/insiders
Installs a specific older release of Material for MkDocs Insiders using pip. Ensure the GH_TOKEN environment variable is set.
```bash
pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
```
--------------------------------
### Build Project with CI Environment Variable
Source: https://squidfunk.github.io/mkdocs-material/plugins/group
Example command to build the project when the CI environment variable is set, enabling the group plugin and its associated plugins.
```bash
CI=true mkdocs build
```
--------------------------------
### Example .meta.yml for Authors
Source: https://squidfunk.github.io/mkdocs-material/plugins/meta
This snippet demonstrates how to assign authors to blog posts within a folder, ensuring correct annotation.
```yaml
authors:
- squidfunk
```
--------------------------------
### Blog Post Structure and Content
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog
Example of how to structure a blog post file and its front matter for use with the blog plugin.
```APIDOC
## Usage: Writing Your First Post
### Description
Demonstrates the structure of a blog post file, including front matter and content, and how to create excerpts.
### Method
File Creation
### Endpoint
n/a
### Parameters
N/A
### Request Example
#### File: `docs/blog/posts/hello-world.md`
```markdown
---
draft: true
date: 2024-01-31
categories:
- Hello
- World
---
# Hello world!
This is the introduction to my first blog post. It will be displayed in lists and indexes.
This is the content that will only appear after the "more" separator or on the post's dedicated page.
```
--------------------------------
### Install Specific Major Version with pip
Source: https://squidfunk.github.io/mkdocs-material/getting-started
Install a specific major version of Material for MkDocs, like 9.x, to ensure compatibility and avoid breaking changes.
```bash
pip install mkdocs-material=="9.*"
```
--------------------------------
### Example Reproduction Archive Output
Source: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction
This output shows the structure of the .zip file created by the 'info' plugin, including essential files for a bug report.
```text
INFO - Started archive creation for bug report
INFO - Archive successfully created:
example/.dependencies.json 859.0 B
example/.versions.log 83.0 B
example/docs/index.md 282.0 B
example/mkdocs.yml 56.0 B
example.zip 1.8 kB
```
--------------------------------
### Enable Optimize Plugin
Source: https://squidfunk.github.io/mkdocs-material/plugins/optimize
Add this to your mkdocs.yml to enable the optimize plugin. It's built-in and requires no separate installation.
```yaml
plugins:
- optimize
```
--------------------------------
### Markdown Example
Source: https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller
An example Markdown file demonstrating various formatting elements like headings, bold, italic, links, code blocks, numbered lists, and bullet points.
```markdown
# Example
## Text
It's very easy to make some words **bold** and other words *italic*
with Markdown. You can even add [links](#), or even `code`:
```
if (isAwesome) {
return true
}
```
## Lists
Sometimes you want numbered lists:
1. One
2. Two
3. Three
Sometimes you want bullet points:
* Start a line with a star
* Profit!
```
--------------------------------
### Fully Qualified URL Example
Source: https://squidfunk.github.io/mkdocs-material/plugins/privacy
Always use fully qualified URLs for assets to be detected and processed by the plugin.
```javascript
const url ="https://example.com/script.js"
```
--------------------------------
### Enable Typeset Plugin
Source: https://squidfunk.github.io/mkdocs-material/plugins/typeset
Add this configuration to your mkdocs.yml to enable the built-in typeset plugin. It requires no additional installation.
```yaml
plugins:
- typeset
```
--------------------------------
### Configure Section Index Page
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation
Example of how to structure the `nav` in `mkdocs.yml` to include an index page for a section.
```yaml
nav:
- Section:
- section/index.md
- Page 1: section/page-1.md
...
- Page n: section/page-n.md
```
--------------------------------
### Example .meta.yml for Tags
Source: https://squidfunk.github.io/mkdocs-material/plugins/meta
This snippet shows how to add a tag to all pages within a specific folder and its subfolders using a .meta.yml file.
```yaml
tags:
- Example
```
--------------------------------
### Example of a search preview
Source: https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller
A sample representation of a search preview showing text context around search terms.
```text
… channels, e.g., or which can be configured via mkdocs.yml …
```
--------------------------------
### View downloaded assets structure
Source: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy
Example directory structure showing how the privacy plugin organizes downloaded external resources.
```text
.
└─ assets/external/
├─ unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
├─ fonts.googleapis.com/css
└─ fonts.gstatic.com/s/
├─ roboto/v29/
│ ├─ KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2
│ ├─ KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2
│ ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2
│ ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
│ ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
│ ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
│ ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2
│ ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2
│ ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
│ ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2
│ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmWUlfBBc4.woff2
│ ├─ KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
│ ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2
│ ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2
│ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2
│ ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2
│ ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2
│ ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2
│ ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2
│ └─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2
└─ robotomono/v13/
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2
├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2
```
--------------------------------
### Enable Projects Plugin
Source: https://squidfunk.github.io/mkdocs-material/plugins/projects
Add this configuration to your mkdocs.yml to enable the Projects plugin. The plugin is built-in and requires no separate installation.
```yaml
plugins:
- projects
```
--------------------------------
### Complete GitHub Actions workflow for documentation deployment
Source: https://squidfunk.github.io/mkdocs-material/blog/2023/09/22/using-git-sparse-checkout-for-faster-documentation-builds
A full GitHub Actions workflow that checks out the repository with sparse checkout, sets up Python, installs dependencies, and deploys documentation using MkDocs. Ensure `fetch-depth: 0` is used with sparse checkout.
```yaml
name: documentation
on:
push:
branches:
- master
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
sparse-checkout: |
docs
includes
- uses: actions/setup-python@v4
with:
python-version: 3.x
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
```
--------------------------------
### Example .meta.yml for Social Card Layout
Source: https://squidfunk.github.io/mkdocs-material/plugins/meta
Use this snippet to customize the social card layout for pages within a folder.
```yaml
social:
cards_layout: default/variant
```
--------------------------------
### Initialize a project with Docker
Source: https://squidfunk.github.io/mkdocs-material/creating-your-site
Bootstrap a new project using the Material for MkDocs Docker image.
```bash
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
```
```bash
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
```
--------------------------------
### Enable Tags Plugin
Source: https://squidfunk.github.io/mkdocs-material/plugins/tags
Enable the tags plugin by adding it to your mkdocs.yml configuration. This is the basic setup required to start using tags.
```yaml
plugins:
- tags
```
--------------------------------
### Set detailed pagination format
Source: https://squidfunk.github.io/mkdocs-material/plugins/blog
Customize the pagination markup with links to the first, previous, next, and last pages. This example includes all available link placeholders.
```yaml
plugins:
- blog:
pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
```
--------------------------------
### Dynamic URL Example (Not Detected)
Source: https://squidfunk.github.io/mkdocs-material/plugins/privacy
Dynamically created URLs within scripts are not detected by the plugin as it does not execute scripts. Use fully qualified URLs instead.
```javascript
const host = "https://example.com"
const path = `${host}/script.js`
```
--------------------------------
### Initialize a new MkDocs project
Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed
Use the mkdocs executable to bootstrap a new project directory.
```bash
mkdocs new .
```
--------------------------------
### Minimal Markdown Configuration
Source: https://squidfunk.github.io/mkdocs-material/setup/extensions
A basic configuration for using Material for MkDocs with essential Markdown extensions. Start here and add features as needed.
```yaml
markdown_extensions:
# Python Markdown
- toc:
permalink: true
# Python Markdown Extensions
- pymdownx.highlight
- pymdownx.superfences
```
--------------------------------
### Configure Icons in Social Cards
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards
Examples of using the icon property to add and tint icons within social card layers.
```yaml
size: { width: 1200, height: 630 }
layers:
- background:
color: "#4051b5"
- size: { width: 144, height: 144 }
offset: { x: 992, y: 64 }
icon:
value: material/cat
color: white
```
```yaml
size: { width: 1200, height: 630 }
layers:
- background:
color: "#4051b5"
- size: { width: 2400, height: 2400 }
offset: { x: -1024, y: 64 }
icon:
value: material/circle
color: "#5c6bc0"
- size: { width: 1800, height: 1800 }
offset: { x: 512, y: -1024 }
icon:
value: material/circle
color: "#3949ab"
```
--------------------------------
### Set site_url for instant navigation
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation
The `site_url` setting must be set when using instant navigation, as it relies on `sitemap.xml`. Example provided.
```yaml
site_url: https://example.com
```
--------------------------------
### Set up the blog index page
Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed
Replace the default content in docs/index.md to initialize the blog index.
```markdown
# Blog
```
--------------------------------
### Python Project Configuration Transformation Function
Source: https://squidfunk.github.io/mkdocs-material/plugins/projects
Example Python function to transform project configuration, inheriting settings like `use_directory_urls` from the top-level configuration.
```python
from mkdocs.config.defaults import MkDocsConfig
# Transform project configuration
def transform(project: MkDocsConfig, config: MkDocsConfig):
project.use_directory_urls = config.use_directory_urls
```
--------------------------------
### Build blog output
Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/basic
Command to build the site and verify the exclusion of draft posts.
```bash
$ mkdocs build
$ ls site/blog
site/blog
├── 2023
│ └── 12
│ └── 31
│ └── happy-new-years-eve
│ └── index.html
...
```
--------------------------------
### Build static site with MkDocs
Source: https://squidfunk.github.io/mkdocs-material/creating-your-site
Use this command to build a static site from your Markdown files when not using Docker.
```bash
mkdocs build
```
--------------------------------
### Bootstrap New MkDocs Project
Source: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction
Create a new, empty MkDocs project to serve as the basis for your reproduction.
```bash
mkdocs new .
```
--------------------------------
### Build static site with MkDocs in Docker (Unix/Powershell)
Source: https://squidfunk.github.io/mkdocs-material/creating-your-site
Run this command to build your static site if you are using Material for MkDocs within Docker on Unix-like systems or Powershell.
```bash
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
```
--------------------------------
### View project file structure
Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed
The default file structure generated after running the initialization command.
```text
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```
--------------------------------
### Add Line Numbers to Code Block
Source: https://squidfunk.github.io/mkdocs-material/reference/code-blocks
Use the `linenums` option to add line numbers, specifying a starting number if needed. Line numbering starts at 1 by default.
```python
``` py linenums="1"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
```
--------------------------------
### Search Index JSON Example
Source: https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller
An example of a search index JSON structure, including configuration and document entries. Each document entry contains its location, title, and stripped text content.
```json
{
"config": {
"indexing": "full",
"lang": [
"en"
],
"min_search_length": 3,
"prebuild_index": false,
"separator": "[\\s\\-]+"
},
"docs": [
{
"location": "page/",
"title": "Example",
"text": "Example Text It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
},
{
"location": "page/#example",
"title": "Example",
"text": ""
},
{
"location": "page/#text",
"title": "Text",
"text": "It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true }"
},
{
"location": "page/#lists",
"title": "Lists",
"text": "Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
}
]
}
```
--------------------------------
### Deploy a new documentation version
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning
Use the mike CLI to deploy a specific version and update aliases.
```bash
mike deploy --push --update-aliases 0.1 latest
```
--------------------------------
### Upgrade Insiders via pip to the latest development version
Source: https://squidfunk.github.io/mkdocs-material/insiders/upgrade
Run this command to upgrade to the latest development version of Insiders when installed via pip. The `--force-reinstall` flag ensures the latest version is installed.
```bash
pip install --upgrade --force-reinstall git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
```
--------------------------------
### Clone Repository
Source: https://squidfunk.github.io/mkdocs-material/customization
Initial steps to clone the theme repository.
```bash
git clone https://github.com/squidfunk/mkdocs-material
cd mkdocs-material
```
--------------------------------
### Override Site Title
Source: https://squidfunk.github.io/mkdocs-material/customization
Example of overriding the htmltitle block in main.html.
```jinja2
{% extends "base.html" %}
{% block htmltitle %}
Lorem ipsum dolor sit amet
{% endblock %}
```
--------------------------------
### Build static site with MkDocs in Docker (Windows)
Source: https://squidfunk.github.io/mkdocs-material/creating-your-site
Use this command to build your static site if you are using Material for MkDocs within Docker on Windows.
```bash
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material build
```
--------------------------------
### Build Theme
Source: https://squidfunk.github.io/mkdocs-material/customization
Compile and minify theme assets for production.
```bash
npm run build
```
--------------------------------
### MkDocs Project Structure with Blog Plugin
Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/basic
The blog plugin automatically creates a directory structure for your blog posts. Run 'mkdocs serve' to generate these directories if they don't exist.
```bash
docs
├── blog
│ ├── index.md
│ └── posts
└── index.md
```
--------------------------------
### Example of External Script
Source: https://squidfunk.github.io/mkdocs-material/plugins/privacy
Illustrates how an external script tag is transformed after the privacy plugin processes it.
```html
```
```html
```
--------------------------------
### Language switching behavior
Source: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language
Example of how the site maintains the current page path when switching between languages.
```text
docs.example.com/en/ -> docs.example.com/de/
docs.example.com/en/foo/ -> docs.example.com/de/foo/
docs.example.com/en/bar/ -> docs.example.com/de/bar/
```
--------------------------------
### Configure Mastodon Social Link
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer
Example of configuring a Mastodon social link with its icon and URL in `mkdocs.yml`.
```yaml
extra:
social:
- icon: fontawesome/brands/mastodon
link: https://fosstodon.org/@squidfunk
```
--------------------------------
### Enable Search Plugin
Source: https://squidfunk.github.io/mkdocs-material/plugins/search
Add this configuration to your mkdocs.yml to enable the built-in search plugin. No separate installation is required.
```yaml
plugins:
- search
```
--------------------------------
### Automate deployment with GitHub Actions
Source: https://squidfunk.github.io/mkdocs-material/publishing-your-site
Create a workflow file at .github/workflows/ci.yml to automatically deploy documentation on push to master or main branches.
```yaml
name: ci
on:
push:
branches:
- master
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- uses: actions/setup-python@v5
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@v4
with:
key: mkdocs-material-${{ env.cache_id }}
path: ~/.cache
restore-keys: |
mkdocs-material-
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
```
--------------------------------
### Enable Social Plugin
Source: https://squidfunk.github.io/mkdocs-material/plugins/social
Add this to your mkdocs.yml to enable the social plugin. It's built-in and requires no separate installation.
```yaml
plugins:
- social
```
--------------------------------
### Configure a standalone blog
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog
Set up a directory structure and plugin configuration for a blog-only site.
```text
.
├─ docs/
│ ├─ posts/
│ ├─ .authors.yml
│ └─ index.md
└─ mkdocs.yml
```
```yaml
plugins:
- blog:
blog_dir: .
```
--------------------------------
### Configure mkdocs.yml for a standalone blog
Source: https://squidfunk.github.io/mkdocs-material/blog/2022/09/12/blog-support-just-landed
Update the configuration file to enable the blog plugin at the project root.
```yaml
site_name: My Blog
theme:
name: material
features:
- navigation.sections
plugins:
- blog:
blog_dir: .
- search
- tags
nav:
- index.md
```
--------------------------------
### Update requirements for Insiders migration
Source: https://squidfunk.github.io/mkdocs-material/blog/2025/11/11/insiders-now-free-for-everyone
Diff showing the transition from the Insiders repository to the community edition in installation commands.
```diff
- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders. git
+ pip install mkdocs-material
```
--------------------------------
### Set pagination format
Source: https://squidfunk.github.io/mkdocs-material/plugins/blog
Customize the pagination markup using the `pagination_format` setting. This example sets a simple format.
```yaml
plugins:
- blog:
pagination_format: "~2~"
```
--------------------------------
### Configure Blog Plugin in mkdocs.yml
Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/basic
Add the blog plugin to your mkdocs.yml file to enable blog functionality. Ensure site_name, site_description, and site_url are set.
```yaml
site_name: Blog Tutorial
site_description: an example blog set up following the tutorial
site_url: http://www.example.com
theme:
name: material
plugins:
- search
- blog
```
--------------------------------
### Enable Tabs and Instant Loading (5.x)
Source: https://squidfunk.github.io/mkdocs-material/upgrade
In version 5.x, features like tabs and instant loading are enabled by listing them under `theme.features`. This replaces the older `theme.feature` structure.
```yaml
theme:
features:
- tabs
- instant
```
--------------------------------
### Enable Info Plugin for Reproduction Packaging
Source: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction
Add the 'info' plugin to your `mkdocs.yml` to automatically create a .zip file of your reproduction.
```yaml
plugins:
- info
```
--------------------------------
### Unordered List Example
Source: https://squidfunk.github.io/mkdocs-material/reference/lists
Unordered lists are created using '-', '*', or '+' markers. Lists can be nested within each other.
```markdown
- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.
* Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
* Nam vulputate tincidunt fringilla.
* Nullam dignissim ultrices urna non auctor.
```
--------------------------------
### Configure Highlight.js and CSS
Source: https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions
Include Highlight.js library and a default stylesheet in mkdocs.yml for browser-based syntax highlighting.
```yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
- javascripts/highlight.js
extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
```
--------------------------------
### Specify Shadow Tag Prefix
Source: https://squidfunk.github.io/mkdocs-material/plugins/tags
Use `shadow_tags_prefix` to define a string that marks a tag as a shadow tag if it starts with this prefix.
```yaml
plugins:
- tags:
shadow_tags_prefix: _
```
--------------------------------
### Configure Font Directory Structure
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards
Example of the directory structure generated by the social plugin when using the Roboto font family.
```text
.cache/plugins/social/fonts
└─ Roboto/
├─ Black.ttf
├─ Black Italic.ttf
├─ Bold.ttf
├─ Bold Italic.ttf
├─ Italic.ttf
├─ Light.ttf
├─ Light Italic.ttf
├─ Medium.ttf
├─ Medium Italic.ttf
├─ Regular.ttf
├─ Thin.ttf
└─ Thin Italic.ttf
```
--------------------------------
### Search index JSON structure
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search
This is an example of the JSON structure generated for the search index, showing how included sections are represented.
```json
{
"...": "",
"docs": [
{
"location":"page/",
"text":"",
"title":"Document title"
},
{
"location":"page/#section-1",
"text":"The content of this section is included
",
"title":"Section 1"
}
]
}
```
```json
{
"...": "",
"docs": [
{
"location":"page/",
"text":"The content of this block is included
",
"title":"Document title"
}
]
}
```
--------------------------------
### Minimal mkdocs.yml configuration
Source: https://squidfunk.github.io/mkdocs-material/creating-your-site
Basic configuration required to enable the Material theme.
```yaml
site_name: My site
site_url: https://mydomain.org/mysite
theme:
name: material
```
--------------------------------
### Enable instant previews globally
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation
Globally enable instant previews for all header links by adding `navigation.instant.preview` to theme features. This alleviates the need for `data-preview` attributes. Ensure `site_url` is set.
```yaml
theme:
features:
- navigation.instant.preview
```
--------------------------------
### Enable Formatting Extensions
Source: https://squidfunk.github.io/mkdocs-material/reference/formatting
Add these lines to mkdocs.yml to enable Critic, Caret, Keys, Mark, and Tilde extensions.
```yaml
markdown_extensions:
- pymdownx.critic
- pymdownx.caret
- pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
```
--------------------------------
### Enable Privacy Plugin
Source: https://squidfunk.github.io/mkdocs-material/plugins/privacy
Basic configuration to enable the privacy plugin in your mkdocs.yml file. The plugin is built-in and requires no separate installation.
```yaml
plugins:
- privacy
```
--------------------------------
### Enable Multiple Plugin Groups
Source: https://squidfunk.github.io/mkdocs-material/insiders
Demonstrates how to enable multiple plugin groups simultaneously by setting multiple environment variables. This command enables both the CI-specific and INSIDERS-specific plugin groups.
```bash
CI=true INSIDERS=true mkdocs build
```
--------------------------------
### Conditional Giscus Integration
Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage
Example of wrapping the Giscus script in a Jinja2 conditional to restrict comments to pages with a specific metadata flag.
```jinja2
{% if page.meta.comments %}
{% endif %}
```
--------------------------------
### Create a Blog Post with Metadata
Source: https://squidfunk.github.io/mkdocs-material/tutorials/blogs/basic
Create a Markdown file for a blog post, including a header with at least a 'date' entry. Use a level one heading for the slug and '' to define the excerpt.
```markdown
---
date:
created: 2023-12-31
---
# Happy new years eve!
We hope you are all having fun and wish you all the best for the new year!
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.
```
--------------------------------
### Definition List Example
Source: https://squidfunk.github.io/mkdocs-material/reference/lists
Definition lists allow for key-value pairs. The key is on one line, followed by a colon and indented value.
```markdown
`Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis.
`Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.
```
--------------------------------
### Prepare for git upgrade
Source: https://squidfunk.github.io/mkdocs-material/insiders/upgrade
Navigate to your local Material for MkDocs repository and pull the latest changes before proceeding with a git upgrade.
```bash
cd mkdocs-material
git pull
```
--------------------------------
### Example .meta.yml for Excluding Pages from Search
Source: https://squidfunk.github.io/mkdocs-material/plugins/meta
Configure this snippet to exclude specific sections from search indexing, providing granular control.
```yaml
search:
exclude: true
```
--------------------------------
### Project Directory Structure
Source: https://squidfunk.github.io/mkdocs-material/customization
Recommended file structure for overriding theme templates.
```text
.
├─ overrides/
│ └─ main.html
└─ mkdocs.yml
```
--------------------------------
### RSS Plugin Configuration
Source: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog
Integrate the RSS plugin to provide an RSS feed for your blog posts. This requires installing the plugin and configuring it in mkdocs.yml.
```APIDOC
## Configuration: RSS Plugin
### Description
Provides a simple way to add an RSS feed to your blog or documentation. Integrates seamlessly with the built-in blog plugin.
### Method
Configuration
### Endpoint
n/a
### Parameters
#### Configuration Options
- **plugins** (list) - Required - List of plugins to enable.
- **rss** (object) - Required - Enables the RSS plugin.
- **match_path** (string) - Optional - Regular expression to specify which pages to include in the feed. Defaults to `.*`.
- **date_from_meta** (object) - Optional - Specifies which front matter property to use as the creation date. Recommended: `date`.
- **as_creation** (string) - Required - The front matter property name (e.g., `date`).
- **categories** (list) - Optional - List of front matter properties to use as categories/tags in the feed.
- **comments_path** (string) - Optional - Specifies the anchor for comments on a post.
- **enabled** (boolean) - Optional - Enables or disables the plugin. Can be controlled via environment variables.
### Request Example
```yaml
plugins:
- rss:
match_path: blog/posts/.*
date_from_meta:
as_creation: date
categories:
- categories
- tags
comments_path: "#__comments"
enabled: !ENV [CI, true]
```
### Response
N/A (Configuration applies to build process)
### Notes
- Install the plugin using: `pip install mkdocs-rss-plugin`.
- Material for MkDocs automatically adds necessary metadata for feed discoverability.
- Other RSS plugin options are not officially supported by Material for MkDocs and may cause unexpected results.
```
--------------------------------
### Enable Meta Plugin in mkdocs.yml
Source: https://squidfunk.github.io/mkdocs-material/plugins/meta
Add this configuration to your mkdocs.yml to enable the meta plugin. It is included with Material for MkDocs and requires no separate installation.
```yaml
plugins:
- meta
```
--------------------------------
### Enable Grids Configuration
Source: https://squidfunk.github.io/mkdocs-material/reference/grids
Add these lines to your mkdocs.yml to enable grid functionality. Ensure attribute lists and markdown in HTML are also enabled.
```yaml
markdown_extensions:
- attr_list
- md_in_html
```
--------------------------------
### Customize Slugification Function
Source: https://squidfunk.github.io/mkdocs-material/plugins/blog
Change the slugification function using `post_slugify`. This example shows how to apply the `pymdownx.slugs.slugify` function with specific keyword arguments.
```yaml
plugins:
- blog:
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
--------------------------------
### Ordered List Example
Source: https://squidfunk.github.io/mkdocs-material/reference/lists
Ordered lists use numbers followed by a dot. Numbers do not need to be consecutive and will be re-numbered on render. Lists can be nested.
```markdown
1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed.
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
1. Mauris dictum mi lacus
2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu
```