Skip to main content

​
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:
TopicIconExample ADRs
Authentication/JWTkeyadr-0007, adr-0031, adr-0032, adr-0034, adr-0035
Authorization/Securityshield, shield-checkadr-0002, adr-0039, adr-0066
Database/Storagedatabaseadr-0006, adr-0015, adr-0022, adr-0036, adr-0041, adr-0048, adr-0051, adr-0060
Testingflaskadr-0016, adr-0044, adr-0045, adr-0049, adr-0052
Observabilitychart-lineadr-0003, adr-0026, adr-0043
CI/CDcircle-check, arrows-rotateadr-0021, adr-0053
Kubernetes/Podsdharmachakraadr-0054
Deploymentrocketadr-0013, adr-0040, adr-0046
AI/LLMbrain, robot, microchipadr-0001, adr-0023, adr-0024, adr-0025
Async/Performanceboltadr-0019, adr-0056, adr-0061
MCP Protocolplugadr-0004, adr-0020
Error Handlingbugadr-0017, adr-0029
User/Identityuser-gear, user-shield, users-gearadr-0033, adr-0037, adr-0038
Package Managementpackageadr-0042, adr-0050, adr-0062
Diagrams/Workflowdiagram-projectadr-0010, adr-0047, adr-0055
Documentationbookadr-0063
Code Qualitybroom, code, code-branchadr-0005, adr-0014, adr-0064, adr-0065
Resiliencelife-ringadr-0030
Rate Limitinggaugeadr-0027
Cachingmemoryadr-0028
Versioningtagadr-0018
Feature Flagsflagadr-0009
Secretslockadr-0008
Compliancescale-balancedadr-0012
Templatescookieadr-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):

​
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