Global Configuration

DocKit bietet flexible globale Konfigurationsoptionen, um das Erscheinungsbild, das Verhalten und die Funktionalität Ihrer Dokumentationsseite anzupassen. In dieser Anleitung werden alle wesentlichen Einstellungen behandelt, die Sie konfigurieren können.

Configuration Files

DocKit verwendet mehrere Konfigurationsdateien, die sich im Verzeichnis src/config/ befinden:

src/config/
├── config.json      # Main site configuration
├── theme.json       # Theme and styling options
├── menu.json        # Navigation menu structure
├── social.json      # Social media links
└── locals.json      # Localization settings

Main Configuration (config.json)

Die Hauptkonfigurationsdatei steuert die Grundeinstellungen Ihrer Site:

{
  "site": {
    "title": "DocKit Documentation",
    "description": "Beautiful documentation made simple",
    "author": "Your Name",
    "email": "your.email@example.com",
    "base_url": "https://yourdomain.com"
  },
  "metadata": {
    "meta_author": "DocKit Team",
    "meta_image": "/images/og-image.png",
    "meta_description": "Create beautiful documentation with DocKit"
  }
}

Configuration Options

Option	Type	Description
site.title	Zeichenfolge	Der Haupttitel Ihrer Website
site.description	Zeichenfolge	Kurze Beschreibung Ihrer Dokumentation
site.author	String	Default author name
site.email	String	Contact email address
site.base_url	Zeichenfolge	Die Produktions-URL Ihrer Website
metadata.meta_image	String	Default Open Graph image

Theme Configuration (theme.json)

Passen Sie das visuelle Erscheinungsbild Ihrer Website an:

{
  "theme": {
    "primary_color": "#2563eb",
    "secondary_color": "#64748b",
    "accent_color": "#06b6d4",
    "background_color": "#ffffff",
    "text_color": "#1e293b"
  },
  "layout": {
    "sidebar_width": "280px",
    "content_max_width": "1200px",
    "enable_breadcrumbs": true,
    "enable_toc": true
  },
  "features": {
    "dark_mode": true,
    "search": true,
    "print_button": true,
    "edit_page": true
  }
}

Theme Options

Colors

• primary_color: Hauptmarkenfarbe für Links und Schaltflächen
• secondary_color: Sekundäre Elemente und Ränder
• accent_color: Highlights und Call-to-Action-Elemente
• background_color: Main background color
• text_color: Default text color

Layout

• sidebar_width: Breite der Navigationsseitenleiste
• content_max_width: Maximum width of content area
• enable_breadcrumbs: Show/hide breadcrumb navigation
• enable_toc: Show/hide table of contents

Features

• dark_mode: Enable dark mode toggle
• search: Enable site search functionality
• print_button: Show print button on pages
• edit_page: Links „Diese Seite bearbeiten“ anzeigen

Navigation Menu (menu.json)

Definieren Sie die Navigationsstruktur Ihrer Website:

{
  "main": [
    {
      "name": "Getting Started",
      "url": "/getting-started/",
      "children": [
        {
          "name": "Introduction",
          "url": "/getting-started/introduction/"
        },
        {
          "name": "Global Settings",
          "url": "/getting-started/global-settings/"
        }
      ]
    },
    {
      "name": "Guides",
      "url": "/guides/"
    },
    {
      "name": "Reference",
      "url": "/reference/"
    }
  ]
}

Social Links (social.json)

Konfigurieren Sie soziale Medien und externe Links:

{
  "social": [
    {
      "name": "GitHub",
      "icon": "github",
      "url": "https://github.com/yourusername/your-repo"
    },
    {
      "name": "Twitter",
      "icon": "twitter",
      "url": "https://twitter.com/yourusername"
    },
    {
      "name": "Discord",
      "icon": "discord",
      "url": "https://discord.gg/your-server"
    }
  ]
}

Localization (locals.json)

Set up multi-language support:

{
  "defaultLocale": "en",
  "locales": {
    "en": {
      "label": "English",
      "lang": "en",
      "dir": "ltr"
    },
    "de": {
      "label": "Deutsch",
      "lang": "de",
      "dir": "ltr"
    }
  }
}

Astro Configuration

DocKit lässt sich auch in die Konfiguration von Astro in astro.config.mjs integrieren:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'DocKit',
      description: 'Beautiful documentation made simple',
      logo: {
        src: './src/assets/logo.svg',
      },
      customCss: [
        './src/styles/global.css',
      ],
    }),
  ],
});

Environment Variables

Configure environment-specific settings using .env files:

.env.local

PUBLIC_SITE_URL=http://localhost:4321
PUBLIC_ANALYTICS_ID=your-analytics-id
GITHUB_TOKEN=your-github-token

Best Practices

Performance

• Halten Sie die Konfigurationsdateien klein und fokussiert
• Use appropriate data types (strings, booleans, numbers)
• Avoid deeply nested structures

Maintenance

• Dokumentieren Sie Ihre benutzerdefinierten Konfigurationen
• Verwenden Sie die Versionskontrolle für Konfigurationsänderungen
• Test configuration changes in development first

Security

• Never commit sensitive data to configuration files
• Verwenden Sie Umgebungsvariablen für Geheimnisse
• Validate configuration inputs

Troubleshooting

Common Issues

Konfiguration wird nicht geladen: Stellen Sie sicher, dass JSON-Dateien eine gültige Syntax und die richtigen Dateierweiterungen haben.

Stile gelten nicht: Überprüfen Sie, ob die theme.json-Werte eine gültige CSS-Syntax verwenden.

Menü wird nicht angezeigt: Überprüfen Sie, ob die Struktur von menu.json dem erwarteten Format entspricht.

Build errors: Validate all configuration files against their schemas.

---

Benötigen Sie Hilfe bei der erweiterten Konfiguration? Schauen Sie sich unser customization guide an oder fragen Sie in unserem community discussions.