Mkdocs - Material cheatsheet¶

Complete reference for all enabled extensions and features.

Table of Contents¶

Use [TOC] or it auto-generates from headers with permalink: true.

Code Blocks¶

Basic Syntax Highlighting¶

Supported languages: promql, go, bash, python, yaml, json, dockerfile, etc.

PromQL

# PromQL query
rate(http_requests_total{job="api"}[5m])

Go

// Golang example
func main() {
    fmt.Println("Hello World")
}

Bash

# Bash commands
kubectl get pods -n monitoring
systemctl status prometheus

Markdown source:

Markdown

```promql
rate(http_requests_total[5m])
```

Code Blocks with Line Numbers¶

Add line numbers to any code block:

Python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

result = fibonacci(10)
print(f"Result: {result}")

Markdown source:

Markdown

```python linenums="1"
def fibonacci(n):
    return n if n <= 1 else fibonacci(n-1) + fibonacci(n-2)
```

Highlighting Specific Lines¶

Highlight important lines:

YAML

apiVersion: v1
kind: Service  # This line is highlighted
metadata:
  name: prometheus  # These lines
  namespace: monitoring  # are also
  labels:  # highlighted
    app: prometheus

Markdown source:

Markdown

```yaml hl_lines="2 4-6"
apiVersion: v1
kind: Service
```

Code with Title¶

fibonacci.py

def fibonacci(n):
    """Calculate fibonacci number."""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

Markdown source:

Markdown

```python title="fibonacci.py"
def fibonacci(n):
    return n
```

Code Annotations¶

Add inline explanations to code:

YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx  # (1)!
spec:
  replicas: 3  # (2)!
  selector:
    matchLabels:
      app: nginx

The name of your deployment
Number of pod replicas

Markdown source:

Markdown

```yaml
metadata:
  name: nginx  # (1)!
```

1. The name of your deployment

Inline Code Highlighting¶

Use inline syntax highlighting with backticks and language: range(10) or curl -X GET.

Markdown source:

Markdown

Use `#!python range(10)` for inline code.

Admonitions (Info Boxes)¶

Basic Admonitions¶

Note

This is a note admonition. Use it for general information.

Tip

This is a tip admonition. Use it for helpful suggestions.

Warning

This is a warning admonition. Use it for important cautions.

Danger

This is a danger admonition. Use it for critical warnings.

Markdown source:

Markdown

!!! note
    This is a note admonition.

!!! warning
    This is a warning admonition.

Custom Titles¶

PromQL Pro Tip

Always use rate() for counters, never raw values.

Markdown source:

Markdown

!!! tip "PromQL Pro Tip"
    Always use `rate()` for counters.

Collapsible Admonitions¶

Use ??? instead of !!! to make them collapsible:

Click to expand

This content is hidden by default. Users must click to see it.

Critical Performance Issue

Querying large time ranges without aggregation can crash Prometheus.

PromQL

# Bad - queries all series
http_requests_total

# Good - aggregated
sum(rate(http_requests_total[5m]))

Markdown source:

Markdown

??? note "Click to expand"
    This content is hidden by default.

Inline Blocks (Already Expanded)¶

Pre-expanded Tip

Use ???+ to make collapsible blocks expanded by default.

Markdown source:

Markdown

???+ tip "Pre-expanded Tip"
    Content here starts visible.

Content Tabs¶

Compare different approaches side-by-side:

PromQLLogQLBash

PromQL

rate(http_requests_total[5m])

PromQL

rate({job="nginx"}[5m])

Bash

curl -s localhost:9090/api/v1/query?query=up

Markdown source:

Markdown

=== "PromQL"
    ```promql
    rate(http_requests_total[5m])
    ```

=== "LogQL"
    ```promql
    rate({job="nginx"}[5m])
    ```

Nested Tabs¶

MonitoringLogging

PrometheusGrafana

YAML

scrape_configs:
  - job_name: 'api'
    static_configs:
      - targets: ['localhost:8080']

JSON

{
  "datasource": "Prometheus",
  "expr": "rate(http_requests[5m])"
}

Loki

YAML

auth_enabled: false
server:
  http_listen_port: 3100

Markdown source:

Markdown

=== "Monitoring"
    === "Prometheus"
        Content here
    === "Grafana"
        Content here

Keyboard Keys¶

Press Ctrl+C to copy or Ctrl+Shift+P to open command palette.

Common shortcuts: - Save: Ctrl+S - Quit: Ctrl+Q - Search: Ctrl+F - Terminal: Ctrl+`

Markdown source:

Markdown

Press ++ctrl+c++ to copy.
Press ++ctrl+shift+p++ for command palette.

Snippets (Reusable Content)¶

Create reusable content in separate files:

File: docs/snippets/common-queries.md

PromQL

# CPU Usage
100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# Memory Usage
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

Include in any page:

Markdown

Markdown source:

Markdown

Combining Features¶

Here's a complex example using multiple features:

Complete Monitoring Setup

Prometheus ConfigQuery Examples

prometheus.yml
global:
  scrape_interval: 15s  # (1)!
scrape_configs:
  - job_name: 'kubernetes-pods'  # (2)!
    kubernetes_sd_configs:
      - role: pod

How often to scrape targets
Auto-discover Kubernetes pods

PromQL

# Request rate per service
sum by (service) (rate(http_requests_total[5m]))

# P95 latency
histogram_quantile(0.95, 
  sum by (le) (rate(http_request_duration_seconds_bucket[5m]))
)

Tip

Test queries in Prometheus UI before adding to Grafana dashboards.

Best Practices Summary¶

Quick Reference

Code Blocks: - Use line numbers for long snippets: linenums="1" - Highlight important lines: hl_lines="2 4-6" - Add titles for context: title="config.yaml"

Organization: - Use tabs for comparing alternatives - Use admonitions for warnings/tips - Make long sections collapsible with ???

Keyboard Shortcuts: - Format: ++ctrl+shift+p++ - Separate keys with +

Inline Code: - Add syntax highlighting: `#!python print()`

Common Admonition Types¶

Note

General information

Abstract

Summary or TL;DR

Info

Additional context

Tip

Helpful suggestions

Success

Positive outcome

Question

Questions or help needed

Warning

Important cautions

Failure

Errors or failures

Danger

Critical warnings

Bug

Known issues

Example

Code examples

Quote

Citations or quotes

Markdown Source Template¶

Markdown

# Your Page Title

## Section

Regular paragraph with `inline code`.

### Code Example

```bash
command --flag value

Info Box¶

Helpful Tip

Your tip content here.

Tabs¶

Option 1Option 2

Content for option 1

Content for option 2

Keyboard¶

Press Ctrl+C to copy. ```