> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Icon Selection Guide

> Comprehensive icon standards for Mintlify documentation with Font Awesome and Lucide icon libraries and semantic usage guidelines

# Mintlify Icon Style Guide

This guide defines the standard icon conventions for MCP Server LangGraph documentation. Consistent icon usage improves navigation and visual organization.

## Icon Libraries

Mintlify supports both **Font Awesome** and **Lucide** icon libraries.

### Preference Guidelines

**Prefer Font Awesome when:**

* Brand icons are needed (docker, google, aws, microsoft, github, etc.)
* Specialized technical icons exist (dharmachakra for Kubernetes, shield-halved for security)
* More specific/semantic icons are available

**Use Lucide for:**

* Generic UI icons (file, folder, settings, etc.)
* When Font Awesome doesn't have a suitable alternative
* Simple, clean iconography needs

## Icon Selection Principles

1. **Semantic Relevance**: Icons should clearly represent the document's purpose
2. **Category Consistency**: Related documents should use related icons
3. **Visual Distinction**: Different categories should have distinct icon families
4. **Accessibility**: Icons should be recognizable and meaningful
5. **Library Preference**: Use Font Awesome for brands/technical, Lucide for generic UI

## Icon Categories

### 1. Architecture Decision Records (ADRs)

**Icon**: Use **semantic icons** based on the ADR's topic

**Rationale**: Semantic icons improve discoverability and visual distinction. Each ADR should use an icon that represents its primary subject matter.

**Usage**: All files in `docs/architecture/adr-*.mdx`

**Semantic Icon Examples by Topic**:

| Topic                  | Icon                                     | Example ADRs                                                                   |
| ---------------------- | ---------------------------------------- | ------------------------------------------------------------------------------ |
| Authentication/JWT     | `key`                                    | adr-0007, adr-0031, adr-0032, adr-0034, adr-0035                               |
| Authorization/Security | `shield`, `shield-check`                 | adr-0002, adr-0039, adr-0066                                                   |
| Database/Storage       | `database`                               | adr-0006, adr-0015, adr-0022, adr-0036, adr-0041, adr-0048, adr-0051, adr-0060 |
| Testing                | `flask`                                  | adr-0016, adr-0044, adr-0045, adr-0049, adr-0052                               |
| Observability          | `chart-line`                             | adr-0003, adr-0026, adr-0043                                                   |
| CI/CD                  | `circle-check`, `arrows-rotate`          | adr-0021, adr-0053                                                             |
| Kubernetes/Pods        | `dharmachakra`                           | adr-0054                                                                       |
| Deployment             | `rocket`                                 | adr-0013, adr-0040, adr-0046                                                   |
| AI/LLM                 | `brain`, `robot`, `microchip`            | adr-0001, adr-0023, adr-0024, adr-0025                                         |
| Async/Performance      | `bolt`                                   | adr-0019, adr-0056, adr-0061                                                   |
| MCP Protocol           | `plug`                                   | adr-0004, adr-0020                                                             |
| Error Handling         | `bug`                                    | adr-0017, adr-0029                                                             |
| User/Identity          | `user-gear`, `user-shield`, `users-gear` | adr-0033, adr-0037, adr-0038                                                   |
| Package Management     | `package`                                | adr-0042, adr-0050, adr-0062                                                   |
| Diagrams/Workflow      | `diagram-project`                        | adr-0010, adr-0047, adr-0055                                                   |
| Documentation          | `book`                                   | adr-0063                                                                       |
| Code Quality           | `broom`, `code`, `code-branch`           | adr-0005, adr-0014, adr-0064, adr-0065                                         |
| Resilience             | `life-ring`                              | adr-0030                                                                       |
| Rate Limiting          | `gauge`                                  | adr-0027                                                                       |
| Caching                | `memory`                                 | adr-0028                                                                       |
| Versioning             | `tag`                                    | adr-0018                                                                       |
| Feature Flags          | `flag`                                   | adr-0009                                                                       |
| Secrets                | `lock`                                   | adr-0008                                                                       |
| Compliance             | `scale-balanced`                         | adr-0012                                                                       |
| Templates              | `cookie`                                 | adr-0011                                                                       |

**DO NOT use `file-lines`** - This generic icon lacks semantic meaning and may not render well in dark mode.

**Files**: All ADR documents (adr-0001 through adr-0066)

***

### 2. General Deployment Documentation

**Icon**: `rocket`

**Rationale**: Represents deployment, launch, and going to production.

**Usage**: General deployment guides, processes, configurations

**Examples**:

```yaml theme={null}
---
title: Deployment Overview
description: 'Deploy MCP Server with LangGraph to production'
icon: 'rocket'
contentType: 'how-to'
---
```

**Files**:

* `deployment/overview.mdx`
* `deployment/langgraph-platform.mdx`
* `deployment/release-process.mdx`
* `deployment/version-compatibility.mdx`
* `deployment/version-pinning.mdx`
* `deployment/vmware-resource-estimation.mdx`
* `deployment/model-configuration.mdx`
* `deployment/gdpr-storage-configuration.mdx`

***

### 3. Kubernetes-Specific Deployment

**Icon**: `dharmachakra` (Font Awesome)

**Rationale**: Official Kubernetes icon (ship's wheel/Dharmachakra). Available in Font Awesome.

**Usage**: Kubernetes deployment guides, manifests, K8s operations

**Examples**:

```yaml theme={null}
---
title: Kubernetes Deployment
description: 'Deploy MCP Server with LangGraph on Kubernetes'
icon: 'dharmachakra'
contentType: 'how-to'
---
```

**Files**:

* `deployment/kubernetes.mdx`
* `deployment/gke-staging-implementation-summary.mdx`
* `deployment/kubernetes/gke.mdx`
* `deployment/kubernetes/eks.mdx`
* `deployment/kubernetes/aks.mdx`
* `kubernetes/configmap-best-practices.mdx`
* `kubernetes/keycloak-readonly-filesystem.mdx`
* `kubernetes/pod-crash-resolution-2025-11-12.mdx`

***

### 4. Container/Docker Deployment

**Icon**: `docker` (Font Awesome)

**Rationale**: Docker's official brand icon. Available in Font Awesome.

**Usage**: Docker-specific deployment guides

**Examples**:

```yaml theme={null}
---
title: Docker Compose
description: 'Local development and testing with Docker Compose'
icon: 'docker'
contentType: 'how-to'
---
```

**Files**:

* `deployment/docker.mdx`
* `infrastructure/docker-healthcheck-patterns.mdx`

***

### 5. Helm Deployment

**Icon**: `cubes` (Font Awesome)

**Rationale**: Represents multiple packages/charts (Helm is a Kubernetes package manager). Font Awesome's `cubes` icon perfectly represents containerized packages and multi-component charts.

**Usage**: Helm chart deployment guides

**Examples**:

```yaml theme={null}
---
title: Helm Deployment
description: 'Deploy MCP Server using Helm charts for simplified management'
icon: 'cubes'
contentType: 'how-to'
---
```

**Files**:

* `deployment/helm.mdx`

***

### 6. Cloud Provider-Specific (GCP)

**Icon**: `google` (Font Awesome)

**Rationale**: Google's brand icon. Available in Font Awesome.

**Usage**: GCP-specific deployment guides (Cloud Run, Vertex AI, GKE-specific features)

**Examples**:

```yaml theme={null}
---
title: Google Cloud Run
description: 'Deploy to Google Cloud Run for serverless GCP deployment'
icon: 'google'
contentType: 'how-to'
---
```

```yaml theme={null}
---
title: Vertex AI with Workload Identity
description: 'Configure Vertex AI using Workload Identity Federation on GKE for keyless authentication'
icon: 'google'
contentType: 'how-to'
---
```

**Files**:

* `deployment/cloud-run.mdx`
* `deployment/vertex-ai-workload-identity.mdx`

**Note**: For AWS and Azure specific guides, use `aws` and `microsoft` (Font Awesome) icons respectively.

***

### 7. Security & Authentication

**Icon**: `shield-halved` (Font Awesome) or `shield`

**Rationale**: Represents security, protection, and access control. Font Awesome provides better shield variants.

**Usage**: Security guides, authentication/authorization, API gateways, secrets management

**Examples**:

```yaml theme={null}
---
title: Kong API Gateway
description: 'Deploy Kong Gateway for advanced API management, rate limiting, and security'
icon: 'shield-halved'
contentType: 'how-to'
---
```

```yaml theme={null}
---
title: Keycloak JWT Authentication Deployment Guide
description: 'Complete deployment guide for the Keycloak-centric authentication architecture'
icon: 'shield-halved'
contentType: 'how-to'
---
```

**Files**:

* `deployment/kong-gateway.mdx`
* `deployment/keycloak-jwt-deployment.mdx`
* `deployment/infisical-installation.mdx`
* `security/*` (security-related documentation)

**Alternative security icons**:

* `shield`: General security
* `shield-check`: Security verification
* `lock`: Access control
* `key`: Authentication/credentials

***

### 8. Observability & Monitoring

**Icon**: `chart-line`

**Rationale**: Represents metrics, monitoring, and time-series data.

**Usage**: Monitoring, metrics, observability guides

**Examples**:

```yaml theme={null}
---
title: Monitoring & Observability
description: 'Comprehensive monitoring, metrics, and observability setup'
icon: 'chart-line'
contentType: 'how-to'
---
```

**Files**:

* `deployment/monitoring.mdx`

**Related observability icons**:

* `database`: Log aggregation/storage
* `chart-bar`: Dashboards
* `magnifying-glass-chart`: Analytics

***

### 9. Log Aggregation

**Icon**: `database`

**Rationale**: Represents log storage and data aggregation.

**Usage**: Logging infrastructure, log aggregation platforms

**Examples**:

```yaml theme={null}
---
title: Log Aggregation
description: 'Multi-platform log aggregation with structured JSON logging'
icon: 'database'
contentType: 'how-to'
---
```

**Files**:

* `deployment/log-aggregation.mdx`

***

### 10. Scaling & Performance

**Icon**: `arrow-up-right-dots`

**Rationale**: Represents upward scaling and growth.

**Usage**: Auto-scaling, performance optimization, resource scaling

**Examples**:

```yaml theme={null}
---
title: Auto-Scaling
description: 'Configure horizontal and vertical scaling for production workloads'
icon: 'arrow-up-right-dots'
contentType: 'how-to'
---
```

**Files**:

* `deployment/scaling.mdx`

***

### 11. Disaster Recovery & Resilience

**Icon**: `life-ring`

**Rationale**: Represents rescue, recovery, and safety nets.

**Usage**: Disaster recovery, backup/restore, failover strategies

**Examples**:

```yaml theme={null}
---
title: Disaster Recovery
description: 'Backup, restore, and failover strategies for production resilience'
icon: 'life-ring'
contentType: 'how-to'
---
```

**Files**:

* `deployment/disaster-recovery.mdx`

***

### 12. Production Readiness & Checklists

**Icon**: `clipboard-check`

**Rationale**: Represents verification, checklists, and task completion.

**Usage**: Production checklists, pre-deployment verification

**Examples**:

```yaml theme={null}
---
title: Production Checklist
description: 'Pre-deployment verification for production environments'
icon: 'clipboard-check'
contentType: 'reference'
---
```

**Files**:

* `deployment/production-checklist.mdx`

***

### 13. Version History & Releases

**Icon**: `tag`

**Rationale**: Git tags represent releases and versions.

**Usage**: Release notes, version history, changelogs

**Examples**:

```yaml theme={null}
---
title: Version History
description: 'Complete release history and version comparison'
icon: 'tag'
contentType: 'reference'
---
```

**Files**:

* `releases/overview.mdx`
* `releases/v2-1-0.mdx` through `releases/v2-8-0.mdx`

***

### 14. Development & Reference

**Icon**: `code`

**Rationale**: Represents code, development, and technical reference.

**Usage**: Development guides, API reference, code examples

**Examples**:

```yaml theme={null}
---
title: Development Guide
description: 'Local development setup and workflow'
icon: 'code'
contentType: 'how-to'
---
```

**Files**:

* `development/commands.mdx`
* `development/validation-strategy.mdx`
* `development/workflows.mdx`
* `development/workflow-diagram.mdx`
* API reference documentation

***

### 15. Getting Started & Guides

**Icon**: `rocket` or `book-open`

**Rationale**: `rocket` for quickstart/deployment, `book-open` for guides and documentation.

**Usage**: Quickstart guides, tutorials, how-to documentation

**Examples**:

```yaml theme={null}
---
title: Quick Start
description: 'Get started with MCP Server LangGraph in 5 minutes'
icon: 'rocket'
contentType: 'tutorial'
---
```

```yaml theme={null}
---
title: Documentation Authoring Guide
description: 'Complete guide for contributing to documentation'
icon: 'book-open'
contentType: 'reference'
---
```

**Files**:

* `getting-started/*`
* `guides/*`
* `references/documentation-authoring-guide.mdx`

***

## Frontmatter Standards

### Complete Frontmatter Template

```yaml theme={null}
---
title: "Document Title Here"
description: 'Brief description of the document content'
icon: "font-awesome-icon-name"
contentType: "explanation|reference|tutorial|how-to"
---
```

### Standards

1. **Title**:
   * Double quotes `"..."`
   * Title Case capitalization
   * Clear and descriptive

2. **Description**:
   * Double quotes `"..."`
   * No ending period
   * 1-2 sentences max
   * Descriptive but concise
   * 140-160 characters recommended for SEO

3. **Icon**:
   * Double quotes `"icon-name"`
   * Font Awesome icon names (without `fa-` prefix)
   * Must be from approved icon set
   * Use lowercase

4. **contentType** (required):
   * One of: `explanation`, `reference`, `tutorial`, `how-to`, `guide`
   * See [Documentation Authoring Guide](/reference/documentation-authoring-guide) for definitions

***

## Icon Selection Flowchart

```
Is it an ADR?
├─ YES → Use semantic icon based on topic (see table above)
└─ NO  → Continue

Is it deployment-related?
├─ YES → What type?
│        ├─ General/Multi-platform → 'rocket'
│        ├─ Kubernetes → 'dharmachakra'
│        ├─ Docker → 'docker'
│        ├─ Helm → 'cubes'
│        ├─ GCP → 'google'
│        ├─ AWS → 'aws'
│        └─ Azure → 'microsoft'
└─ NO  → Continue

Is it security-related?
├─ YES → 'shield-halved' (or shield/lock/key variants)
└─ NO  → Continue

Is it observability?
├─ YES → What aspect?
│        ├─ Monitoring/Metrics → 'chart-line'
│        ├─ Logging → 'database'
│        └─ Scaling → 'arrow-up-right-dots'
└─ NO  → Continue

Is it operational?
├─ YES → What type?
│        ├─ Disaster Recovery → 'life-ring'
│        ├─ Checklist → 'clipboard-check'
│        └─ General → 'rocket'
└─ NO  → Continue

Is it a release/version?
├─ YES → 'tag'
└─ NO  → Continue

Is it development/code reference?
├─ YES → 'code'
└─ NO  → Continue

Is it documentation/authoring?
├─ YES → 'book-open'
└─ NO  → Use judgment or consult team
```

***

## Common Mistakes to Avoid

❌ **Don't**:

* Use inconsistent icons for the same category
* Mix icon families within related docs
* Use obscure or ambiguous icons
* Forget to add `contentType` to frontmatter
* Use UPPERCASE file names

✅ **Do**:

* Follow category conventions
* Use semantic, meaningful icons
* Maintain consistency within directories
* Include all required frontmatter fields
* Use lowercase kebab-case for file names

***

## Validation

### Automated Validation

Primary validator (runs on pre-push):

```bash theme={null}
cd docs
npx mintlify broken-links
```

This validates:

* Frontmatter presence and completeness
* Icon validity
* Navigation consistency

### Manual Validation

Check frontmatter compliance:

```bash theme={null}
python scripts/validators/frontmatter_validator.py --docs-dir docs
```

***

## Updates and Exceptions

If you need to use an icon not listed in this guide:

1. **Check semantic fit**: Does the icon clearly represent the content?
2. **Check for conflicts**: Is this icon already used for a different category?
3. **Document the pattern**: Update this guide with the new usage
4. **Ensure consistency**: Use the same icon for similar documents

For questions or exceptions, consult the documentation team or create an issue.

***

## Font Awesome Icon Reference

Mintlify uses Font Awesome icons. Common useful icons:

**Infrastructure**:

* `server`, `network-wired`, `cloud`, `database`

**Tools**:

* `gear`, `wrench`, `screwdriver`, `toolbox`

**Actions**:

* `play`, `stop`, `refresh`, `download`, `upload`

**Status**:

* `check`, `xmark`, `exclamation`, `info`, `question`

**Navigation**:

* `arrow-right`, `arrow-left`, `arrow-up`, `arrow-down`

**Documentation**:

* `book`, `book-open`, `file-lines`, `icons`

Full icon list: [https://fontawesome.com/icons](https://fontawesome.com/icons)

***

**Last Updated**: 2025-11-17 (Converted to public .mdx documentation)
**Version**: 2.0.0