Branding

Customize your Mordoc documentation with logos, favicons, colors, and typography to match your brand.

6 min read

Branding

Personalize your documentation site to match your brand identity by customizing logos, favicons, colors, fonts, and other visual elements.

Logo

Add your logo to display in the site header and navigation.

Logo Files

Place logo files in the config/ directory:

config/
├── logo.png          # Light mode logo
└── logo-dark.png     # Dark mode logo (optional)

Logo Requirements

Property	Recommendation
Format	PNG, SVG (PNG preferred for photos, SVG for icons/text)
Size	Width: 120-200px, Height: 40-60px
Background	Transparent (for PNG)
Resolution	2x for retina displays

Light and Dark Mode Logos

Provide separate logos for light and dark themes:

logo.png - Used in light mode
logo-dark.png - Used in dark mode

If only logo.png is provided, it will be used in both modes.

Logo Configuration

Configure logo behavior in config/site.json:

Json

{
  "branding": {
    "logo": {
      "src": "/logo.png",
      "darkSrc": "/logo-dark.png",
      "alt": "My Company",
      "height": "40px",
      "linkTo": "/"
    }
  }
}

Property	Description	Default
`src`	Path to light mode logo	`/logo.png`
`darkSrc`	Path to dark mode logo	`/logo-dark.png`
`alt`	Alt text for accessibility	Site title
`height`	Logo height	`40px`
`linkTo`	URL when logo is clicked	`/`

Favicon

The favicon appears in browser tabs, bookmarks, and history.

Favicon File

Place your favicon in the config/ directory:

config/
└── favicon.ico

Favicon Formats

Recommended: Multi-size ICO

favicon.ico (contains 16x16, 32x32, 48x48)

Alternative: PNG files

config/
├── favicon-16x16.png
├── favicon-32x32.png
└── favicon.ico

Modern Favicon Setup

For comprehensive browser support:

HTML

<!-- Add to config/site.json -->
{
  "branding": {
    "favicons": {
      "ico": "/favicon.ico",
      "png16": "/favicon-16x16.png",
      "png32": "/favicon-32x32.png",
      "appleTouchIcon": "/apple-touch-icon.png"
    }
  }
}

File sizes:

favicon.ico: 16x16, 32x32
favicon-16x16.png: 16x16
favicon-32x32.png: 32x32
apple-touch-icon.png: 180x180

Color Scheme

Customize colors to match your brand.

Edit config/styles/main.json:

Json

{
  "colors": {
    "primary": "#3b82f6",
    "secondary": "#8b5cf6",
    "accent": "#10b981",
    "background": "#ffffff",
    "surface": "#f9fafb",
    "text": "#111827",
    "textSecondary": "#6b7280",
    "border": "#e5e7eb",
    "link": "#3b82f6",
    "linkHover": "#2563eb",
    "success": "#10b981",
    "warning": "#f59e0b",
    "danger": "#ef4444"
  }
}

Color Properties

Property	Usage	Example
`primary`	Main brand color, buttons, active states	`#3b82f6`
`secondary`	Complementary color, accents	`#8b5cf6`
`accent`	Highlights, special elements	`#10b981`
`background`	Page background	`#ffffff`
`surface`	Cards, panels, elevated elements	`#f9fafb`
`text`	Primary text color	`#111827`
`textSecondary`	Secondary text, captions	`#6b7280`
`border`	Dividers, borders	`#e5e7eb`
`link`	Link color	`#3b82f6`
`linkHover`	Link hover color	`#2563eb`
`success`	Success messages, positive actions	`#10b981`
`warning`	Warnings, caution states	`#f59e0b`
`danger`	Errors, destructive actions	`#ef4444`

Dark Mode Colors

Define separate colors for dark mode:

Json

{
  "darkMode": {
    "colors": {
      "primary": "#60a5fa",
      "background": "#111827",
      "surface": "#1f2937",
      "text": "#f9fafb",
      "textSecondary": "#d1d5db",
      "border": "#374151"
    }
  }
}

Typography

Customize fonts and text styles.

Edit config/styles/typography.json:

Json

{
  "fontFamily": {
    "body": "Inter, system-ui, sans-serif",
    "heading": "Inter, system-ui, sans-serif",
    "code": "Monaco, 'Courier New', monospace"
  },
  "fontSize": {
    "base": "16px",
    "small": "0.875rem",
    "large": "1.125rem"
  },
  "fontWeight": {
    "normal": "400",
    "medium": "500",
    "semibold": "600",
    "bold": "700"
  },
  "lineHeight": {
    "tight": "1.25",
    "normal": "1.5",
    "relaxed": "1.75"
  }
}

Using Custom Fonts

Option 1: Google Fonts

Add to config/site.json:

Json

{
  "branding": {
    "fonts": {
      "googleFonts": [
        "Inter:400,500,600,700",
        "Roboto+Mono:400,700"
      ]
    }
  }
}

Then reference in typography.json:

Json

{
  "fontFamily": {
    "body": "Inter, sans-serif",
    "code": "Roboto Mono, monospace"
  }
}

Option 2: Self-Hosted Fonts

Add font files to public/fonts/:

public/
└── fonts/
    ├── CustomFont-Regular.woff2
    ├── CustomFont-Bold.woff2
    └── CustomFont.css

Reference in configuration:

Json

{
  "branding": {
    "fonts": {
      "customFonts": [
        "/fonts/CustomFont.css"
      ]
    }
  }
}

Site Title and Description

Set your site's metadata in config/site.json:

Json

{
  "title": "My Documentation",
  "description": "Comprehensive documentation for My Product",
  "author": "My Company",
  "keywords": ["documentation", "guide", "api"],
  "ogImage": "/images/og-image.png"
}

Metadata Properties

Property	Description	Usage
`title`	Site title	Browser tab, SEO
`description`	Site description	SEO, social sharing
`author`	Content author/organization	Metadata
`keywords`	Search keywords	SEO
`ogImage`	Social sharing image (1200x630)	Social media previews

Custom CSS

Add custom styles beyond configuration options.

Create config/styles/custom.css:

Css

/* Custom branding styles */
.site-header {
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

.custom-badge {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: 0.25rem 0.75rem;
  border-radius: 9999px;
  font-size: 0.875rem;
}

Reference in config/site.json:

Json

{
  "branding": {
    "customStyles": [
      "/styles/custom.css"
    ]
  }
}

Customize the footer content:

Json

{
  "branding": {
    "footer": {
      "copyright": "© 2024 My Company. All rights reserved.",
      "links": [
        {
          "label": "Privacy Policy",
          "url": "/legal/privacy"
        },
        {
          "label": "Terms of Service",
          "url": "/legal/terms"
        },
        {
          "label": "Contact Us",
          "url": "mailto:support@example.com"
        }
      ],
      "socialLinks": [
        {
          "platform": "github",
          "url": "https://github.com/yourorg"
        },
        {
          "platform": "twitter",
          "url": "https://twitter.com/yourorg"
        }
      ]
    }
  }
}

Complete Branding Example

Here's a comprehensive branding configuration:

config/site.json:

Json

{
  "title": "Acme Documentation",
  "description": "Official documentation for Acme products and services",
  "baseUrl": "https://docs.acme.com",
  "branding": {
    "logo": {
      "src": "/logo.png",
      "darkSrc": "/logo-dark.png",
      "alt": "Acme Corporation",
      "height": "40px"
    },
    "fonts": {
      "googleFonts": [
        "Poppins:400,500,600,700",
        "Fira+Code:400,700"
      ]
    },
    "footer": {
      "copyright": "© 2024 Acme Corp.",
      "links": [
        { "label": "About", "url": "/about" },
        { "label": "Contact", "url": "/contact" }
      ]
    }
  }
}

config/styles/main.json:

Json

{
  "colors": {
    "primary": "#6366f1",
    "secondary": "#8b5cf6",
    "accent": "#14b8a6",
    "background": "#ffffff",
    "text": "#1f2937"
  }
}

config/styles/typography.json:

Json

{
  "fontFamily": {
    "body": "Poppins, sans-serif",
    "heading": "Poppins, sans-serif",
    "code": "Fira Code, monospace"
  }
}

Best Practices

Logo Guidelines

Keep it simple: Logos should be recognizable at small sizes
Use SVG when possible: Scalable and lightweight
Optimize file size: Compress images without losing quality
Test both themes: Ensure logos work in light and dark modes

Color Accessibility

Ensure sufficient contrast ratios:

Normal text: 4.5:1 minimum
Large text: 3:1 minimum
UI components: 3:1 minimum

Test your colors at WebAIM Contrast Checker.

Typography Best Practices

Limit fonts: Use 2-3 font families maximum
Readable sizes: Minimum 16px for body text
Line height: 1.5-1.75 for body text
Font loading: Use font-display: swap for web fonts

Brand Consistency

Match your main product/website colors
Use consistent logo across all properties
Maintain visual hierarchy
Follow your brand guidelines

Troubleshooting

Logo Not Showing

Verify file exists in config/ directory
Check file name matches configuration
Ensure image format is supported (PNG, SVG, JPG)
Clear browser cache
Rebuild site: npm run build

Favicon Not Updating

Clear browser cache completely
Check file is named favicon.ico
Verify file is in config/ directory
Force refresh: Ctrl+Shift+R (or Cmd+Shift+R)

Colors Not Applying

Verify JSON syntax is correct
Check color format (hex, rgb, hsl)
Rebuild site
Clear browser cache
Check for CSS specificity issues

Font Not Loading

Verify font name is spelled correctly
Check font is installed or Google Fonts URL is correct
Inspect browser console for loading errors
Ensure font files are in public/fonts/

After making branding changes, always rebuild your site (npm run build) and clear your browser cache to see updates.

Next Steps

Build - Build your branded documentation site
Preview - Test your branding locally
Launch - Deploy your site to production

Branding

Logo

Logo Files

Logo Requirements

Light and Dark Mode Logos

Logo Configuration

Favicon

Favicon File

Favicon Formats

Modern Favicon Setup

Color Scheme

Color Properties

Dark Mode Colors

Typography

Using Custom Fonts

Site Title and Description

Metadata Properties

Custom CSS

Footer Customization

Complete Branding Example

Best Practices

Logo Guidelines

Color Accessibility

Typography Best Practices

Brand Consistency

Troubleshooting

Logo Not Showing

Favicon Not Updating

Colors Not Applying

Font Not Loading

Next Steps