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:

---
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:

---
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:

---
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:

---
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:

---
title: Google Cloud Run
description: 'Deploy to Google Cloud Run for serverless GCP deployment'
icon: 'google'
contentType: 'how-to'
---

---
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:

---
title: Kong API Gateway
description: 'Deploy Kong Gateway for advanced API management, rate limiting, and security'
icon: 'shield-halved'
contentType: 'how-to'
---

---
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:

---
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:

---
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:

---
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:

---
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:

---
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:

---
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:

---
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:

---
title: Quick Start
description: 'Get started with MCP Server LangGraph in 5 minutes'
icon: 'rocket'
contentType: 'tutorial'
---

---
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

---
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 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):

cd docs
npx mintlify broken-links

This validates:

• Frontmatter presence and completeness
• Icon validity
• Navigation consistency

Manual Validation

Check frontmatter compliance:

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

---

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