Material for MkDocs Feature Showcase¶

Kitchen sink documentation — Every feature, pattern, and capability of the Material theme ecosystem. Use this as reference for what's possible, copy/paste examples, or generate new documentation.

Last Updated: 2026-03-22 | Theme: Material 9.7.1

Theme Features Overview¶

This site uses Material for MkDocs 9.7.1 with all major features enabled. Below is the complete reference.

Navigation Features¶

# Automatic with Material
- Pages load without full refresh
- URL updates smoothly
- Preserves scroll position
- Prefetches linked pages on hover

Typography & Colors¶

Headings¶

Heading 1 — Page title¶

Heading 2 — Major section¶

Heading 3 — Subsection¶

Heading 4 — Sub-subsection¶

Heading 5 — Minor heading¶

Heading 6 — Smallest heading¶

Text Formatting¶

This is bold text and this is italic text. You can also use bold italic.

Strikethrough text is supported. Inline code looks like this with syntax highlighting.

Superscript: H²O Subscript: H₂O

Lists¶

Unordered lists:

• Item 1
• Item 2
• Nested item 2a
• Nested item 2b
• Item 3

Ordered lists:

1. First step
2. Second step
3. Sub-step 2.1
4. Sub-step 2.2
5. Third step

Definition lists:

Term

Definition of the term goes here. Can be multiple lines.

Another term

Explanation of another term.

Task lists:

• Completed task
• Incomplete task
• Another completed task

Code Blocks & Syntax Highlighting¶

Basic Code Block¶

# Install dependencies
source venv/bin/activate
pip install -r requirements.txt

# Run server
mkdocs serve

Python with Annotations¶

import requests  # (1)!

def fetch_api(url: str) -> dict:  # (2)!
    """Fetch data from API."""
    response = requests.get(url)
    return response.json()  # (3)!

data = fetch_api("https://api.example.com/data")  # (4)!

1. Import the requests library
2. Type hints for clarity
3. Return parsed JSON
4. Call the function

Code with Line Numbers¶

Enable globally in mkdocs.yml with linenums: true, or per-block with linenums="1":

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# mkdocs.yml — Material theme config
site_name: Documentation
theme:
  name: material
  features:
    - navigation.instant.loading
    - search.suggest
plugins:
  - search
  - minify

Multiple Languages Tabbed¶

curl -X GET https://api.example.com/users

import requests
response = requests.get("https://api.example.com/users")
users = response.json()

const response = await fetch("https://api.example.com/users");
const users = await response.json();

resp, err := http.Get("https://api.example.com/users")
defer resp.Body.Close()
data := json.NewDecoder(resp.Body)

Inline Code¶

Use backticks for inline code. For highlighting within text: python, bash, yaml.

Admonitions¶

Admonitions draw attention to important information. Eleven types available:

Collapsible Admonitions¶

Tables¶

Table with alignment:

Data Table from Markdown¶

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |

Icons & Emojis¶

FontAwesome Icons¶

Solid icons:

Brand icons:

Regular icons:

Icon Collections¶

Links & References¶

Internal Links¶

• Go to index
• Cloud & DevOps section
• GitHub API documentation

External Links¶

• Material for MkDocs Documentation
• MkDocs Official Docs
• Python

Automatic Link Detection¶

Visit https://github.com/cosckoya/cosckoya.github.io or check out https://squidfunk.github.io/mkdocs-material/ for more.

Anchor Links (Footnotes)¶

This text has a footnote¹.

Another footnote reference² in the text.

Images¶

Basic Image¶

Image with Caption¶

This is a caption below the image.

Image Alignment¶

Left aligned:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. The image floats to the left with text wrapping around it.

Right aligned:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. The image floats to the right with text wrapping around it.

Centered (default):

:fontawesome-solid-square-up: Abbreviations¶

The HTML specification is maintained by the W3C.

Hover over "HTML" or "W3C" to see the abbreviation tooltip.

Horizontal Rules¶

Text before rule.

Text after rule. Use horizontal rules to separate major sections visually.

Code Snippets & Includes¶

Code snippets can be included from external files or inline highlighted sections.

Inline Snippet Example¶

# This is inline code - copy/paste ready
def hello_world():
    print("Hello, World!")

if __name__ == "__main__":
    hello_world()

Mermaid Diagrams¶

Diagrams are rendered via pymdownx.superfences with mermaid support:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process A]
    B -->|No| D[Process B]
    C --> E[End]
    D --> E

Class Diagram¶

classDiagram
    class User {
        +name: str
        +email: str
        +login()
        +logout()
    }
    class Admin {
        +permissions: list
        +approve()
    }
    User <|-- Admin

Sequence Diagram¶

sequenceDiagram
    participant User
    participant Browser
    participant Server
    User->>Browser: Click link
    Browser->>Server: HTTP GET /api/data
    Server-->>Browser: JSON response
    Browser-->>User: Render page

Tabs & Panels¶

Tabbed content with persistent state across pages:

pip install mkdocs-material
mkdocs new my-site
cd my-site

site_name: My Site
theme:
  name: material

mkdocs gh-deploy

Multiple Platform Tabs¶

Tab group 1 — By OS:

sudo apt-get install python3-pip
pip install mkdocs-material

brew install python3
pip install mkdocs-material

python -m pip install mkdocs-material
mkdocs serve

Tab group 2 — By package manager:

pip install mkdocs-material

conda install mkdocs-material

poetry add mkdocs-material

Advanced Lists¶

Nested Lists with Mixed Content¶

• Feature 1: Description here
• Sub-feature 1a
  • Detail 1a1
  • Detail 1a2
• Sub-feature 1b
• Feature 2: Another description
• With code example:

  mkdocs serve
  

• And some text

Lists with Admonitions¶

• First item !!! note "Note about item" This is a note about the first item
• Second item
• Third item with warning !!! warning "Be careful" Do not skip this step

Comments & Annotations¶

Comments can be added using HTML comments (they won't be rendered):

Code can have inline annotations as shown in the "Code with Annotations" section above.

Keyboard Input¶

Press Ctrl+Alt+Del to reboot.

Use Cmd+S on Mac to save.

Text Decorations¶

Strikethrough text shows what was removed.

Underlined text for emphasis.

Italic for emphasis

Bold for strong emphasis

Bold italic for maximum emphasis

Mark/Highlight¶

This is highlighted text using mark extension.

Content Actions¶

Pages can have action buttons (edit/view source):

These are controlled by:

features:
  - content.action.edit
  - content.action.view

Buttons appear in the header (if configured).

Blockquotes¶

This is a simple blockquote. It can span multiple lines. — Author Name

This is a longer blockquote with more content.

It has multiple paragraphs and can include other elements.

• Lists
• Even lists!

And formatting.

Math & Formulas¶

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true
extra_javascript:
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

Inline math syntax: $E = mc^2$

Block math syntax:

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

$$
\begin{align}
a &= b + c \\
d &= e + f \\
g &= h + i
\end{align}
$$

Material Plugins in Action¶

Search¶

Search is built-in via search plugin. Try the search box (top right on desktop).

• Powered by client-side indexing
• Supports stemming (running → run)
• Highlights matches
• Shares search results via URL

Tags¶

Pages can be tagged for organization:

Minify¶

HTML, CSS, and JavaScript are minified for smaller file size and faster loading.

Same Directory¶

The same-dir plugin allows static files (CSS, JS, images) to live alongside markdown in the same directory structure.

Section Index¶

With section-index plugin, sections with index.md files become clickable navigation items.

Literate Navigation¶

Navigation is defined in SUMMARY.md files (literate navigation) for readability and maintainability.

:fontawesome-solid-browser: Responsive Design¶

This page is fully responsive. Try resizing your browser:

• Desktop: Full navigation sidebar
• Tablet: Collapsible navigation
• Mobile: Navigation drawer

Mobile Menu¶

On mobile/tablet, click the hamburger menu (three lines) to toggle the navigation sidebar.

Breakpoints¶

Material uses these breakpoints:

• Small (< 768px): Mobile
• Medium (768-1216px): Tablet
• Large (> 1216px): Desktop

Dark & Light Mode¶

Toggle between dark (Maleficent theme) and light (Deep Purple + Teal) modes using the button in the top right.

Color schemes are defined in mkdocs.yml:

palette:
  - scheme: slate
    primary: purple
    accent: lime
  - scheme: default
    primary: deep purple
    accent: teal

Configuration Reference¶

Key Theme Options¶

theme:
  name: material
  logo: path/to/logo.png
  favicon: path/to/favicon.png
  language: en
  direction: ltr  # or rtl for right-to-left
  palette:        # Color schemes
  features:       # Feature toggles
  icon:           # Icon configuration

Essential Features¶

Complete feature list as configured on this site:

features:
  # Navigation
  - navigation.sections          # Expandable/collapsible sections
  - navigation.expand            # Expand all sections by default
  - navigation.breadcrumbs       # Breadcrumb trail
  - navigation.instant.loading   # SPA-like navigation (no full reload)
  - navigation.instant.prefetch  # Prefetch pages on hover
  - navigation.instant.progress  # Loading progress indicator
  - navigation.tracking          # URL fragment updates on scroll
  - navigation.top               # Back to top button
  - navigation.indexes           # Section index pages (index.md per section)
  - navigation.footer            # Previous/next page navigation
  - navigation.path              # Show full path in navigation

  # Search
  - search.suggest               # Search auto-complete
  - search.highlight             # Highlight matches in page
  - search.share                 # Share search results via URL

  # Content
  - content.code.copy            # Copy button on code blocks
  - content.code.select          # Text selection on code blocks
  - content.code.annotate        # Inline code annotations (# (1)!)
  - content.tabs.link            # Persistent tab state across pages
  - content.tooltips             # Abbreviation tooltips
  - content.footnote.tooltips    # Footnotes as inline tooltip popovers
  - content.action.edit          # "Edit this page" button
  - content.action.view          # "View source" button

  # TOC
  - toc.follow                   # Highlight current section while scrolling

  # Header
  - header.autohide              # Auto-hide header on scroll down
  - announce.dismiss             # Dismissible announcement bar

Common Patterns¶

"Real Talk" Pattern¶

Pro Tips & Gotchas Pattern¶

Three-Tab Quick Hits Pattern¶

command --flag argument

command pattern example

Performance Tips¶

1. Use Instant Loading¶

Already enabled. Pages load without full refresh.

2. Minify Assets¶

Enabled via minify plugin. HTML, CSS, JS are compressed.

3. Lazy Load Images¶

Use markdown image syntax with proper alt text:

![Description](image.png){ alt="Detailed description" }

4. Organize Navigation¶

Use SUMMARY.md for clean, maintainable navigation structure.

5. Optimize Images¶

• Compress images before adding to docs
• Use WebP format when possible
• Set width/height attributes

6. Cache-Friendly URLs¶

Material generates static URLs that leverage browser caching.

Accessibility (WCAG 2.1 AA)¶

This site aims for WCAG 2.1 AA compliance:

• Color contrast: 4.5:1 minimum for text
• Keyboard navigation: Fully functional
• Screen reader support: Semantic HTML
• Focus indicators: Visible on all interactive elements
• Alt text: All images have descriptions

Keyboard Shortcuts¶

• S or /: Focus search (Material default)
• Esc: Close modals / exit search
• Tab: Navigate elements
• Enter: Activate buttons / confirm

File Organization¶

docs/
├── SUMMARY.md               # Main navigation (literate-nav)
├── index.md                 # Homepage
├── showcase.md              # This file (feature reference)
├── toolbox/                 # CLI tools: asdf, kitty, neovim, tmux, zsh
│   └── SUMMARY.md
├── os/                      # Operating systems: linux, macos, windows
│   └── SUMMARY.md
├── containers/              # Docker (+ Compose), Kubernetes
│   ├── SUMMARY.md
│   └── tools/               # helm, krew, kubectx, dive, popeye
│       └── SUMMARY.md
├── databases/               # Database tooling
│   ├── SUMMARY.md
│   └── tools/               # dbcli, oracledb-cli
│       └── SUMMARY.md
├── cloud/                   # Cloud & DevOps (AWS + merged tools)
│   ├── SUMMARY.md
│   ├── aws.cloud.md
│   └── tools/               # terraform, prowler, checkov, github, azure-devops, snyk, sonarcloud, trivy
│       └── SUMMARY.md
├── api/                     # API references
│   ├── SUMMARY.md
│   └── github-rest-api.service.md
├── code/                    # Programming languages + tools
│   ├── SUMMARY.md
│   └── tools/               # gitleaks, shellcheck, etc.
│       └── SUMMARY.md
├── ai/                      # AI tools: Claude Code, Copilot, Gemini
│   ├── SUMMARY.md
│   └── tools/
│       └── SUMMARY.md
├── 1337/                    # Security / CTF content
│   └── SUMMARY.md
├── awesome/                 # Curated references
│   └── SUMMARY.md
├── templates/               # Doc generation templates
│   ├── README.md
│   ├── tech-reference.template.md
│   └── tool-reference.template.md
└── resources/
    ├── css/
    │   ├── snape.css        # Custom styling (single file, DRY)
    │   └── images.css
    └── img/
        ├── logo.png
        └── favicon.png

Validation Checklist¶

When creating new documentation, use this checklist:

• Page has title and description in frontmatter
• All links are relative paths
• All images have alt text
• FontAwesome icons used (no plain emojis)
• Code blocks have language specified
• Admonitions used appropriately
• "Real talk" sections for practical advice
• Pro tips separated from gotchas
• Tags placed at bottom of page
• mkdocs build --strict passes
• Tone is cynical/realistic (not aspirational)

Tips for Content Creation¶

1. Use Templates¶

Start with tech-reference.template.md or tool-reference.template.md for consistency.

2. Three-Tab Structure¶

Essential → Common Patterns → Pro Tips & Gotchas structure works for most content.

3. Practical Examples¶

Copy-paste code examples that actually work. Include inline comments.

4. Honest Tone¶

Say "this is painful" instead of "this is challenging." Marketing-speak has no place here.

5. Link Everything¶

Internal links help users navigate. Use relative paths.

6. Organize with Sections¶

Use heading hierarchy (h2, h3, h4) to structure content logically.

Learning Resources¶

External Resources:

• Material for MkDocs Official Documentation
• MkDocs Documentation
• Python-Markdown Extensions
• squidfunk/mkdocs-material

Related Topics:

• Markdown syntax and best practices
• Color theory and accessibility
• Static site generation
• Full-text search optimization

Last Updated: 2026-03-22 Tags: material, showcase, features, markdown, theme, documentation