Problem
A default documentation site often lacks a distinct visual identity in the browser. It uses generic favicons and provides poor previews when links are shared on social media or communication tools. This reduces brand recognition and click-through rates.
Why it matters
Your favicon is the primary visual anchor in a crowded browser window. High-quality OpenGraph and Twitter metadata ensure your documentation looks professional and trustworthy when shared. This provides context through titles, descriptions, and hero images.
Approach
docmd provides a built-in favicon property for easy icon configuration. For advanced SEO and social metadata, use the SEO Plugin. This automates the generation of meta tags based on your project configuration and page frontmatter.
Implementation
1. Configuring the Favicon
Place your favicon file (e.g., favicon.svg or favicon.ico) in your source directory and reference it in your docmd.config.json. docmd will automatically handle the relative pathing and cache-busting.
"title": "My Project",
"favicon": "/favicon.svg"
2. Global SEO Configuration
Enable and configure the SEO Plugin to set default social media previews for your entire site.
"url": "https://docs.example.com",
"plugins": {
"seo": {
"defaultDescription": "The ultimate guide to our amazing software.",
"openGraph": {
"defaultImage": "/static/og-banner.png"
},
"twitter": {
"siteUsername": "@myproject",
"cardType": "summary_large_image"
}
}
}
3. Page-Specific Overrides
You can override SEO settings for individual pages using the seo property in the Frontmatter.
---
title: "Major Release v2.0"
description: "Everything you need to know about our new engine."
seo:
image: "/assets/v2-hero-banner.png"
keywords: ["release", "v2", "update", "performance"]
---
Trade-offs
While the favicon property is convenient, it only supports a single file. For complex multi-size favicon sets (Apple Touch Icons, Android manifests, etc.), you may need to use a custom plugin to inject additional <link> tags into the <head>.
