Adding Document

Adding New Documentation Pages

Dieser Leitfaden führt Sie durch den Prozess des Hinzufügens neuer Dokumentationsseiten zu Ihrer Dockit-Site, der ordnungsgemäßen Organisation dieser Seiten und der Sicherstellung, dass sie in der Navigation angezeigt werden.

File Structure

Alle Dokumentationsdateien befinden sich im Verzeichnis src/content/docs/. Der Aufbau sieht so aus:

src/content/docs/
├── index.mdx                 # Homepage
├── getting-started/          # Getting started section
│   ├── introduction/
│   ├── global-settings/
│   └── navigation.md
├── guides/                   # Guides section
│   └── example.md
├── reference/                # Reference section
│   ├── configuration.mdx
│   └── example.mdx
├── resources/                # Resources section
│   ├── community-content.mdx
│   ├── plugins.mdx
│   ├── showcase.mdx
│   └── themes.mdx
└── contents/                 # Additional content
    ├── components/
    └── editing/

Creating a New Page

Step 1: Create the File

Erstellen Sie eine neue .md- oder .mdx-Datei im entsprechenden Verzeichnis:

Für Markdown (.md):

touch src/content/docs/guides/my-new-guide.md

Für MDX (.mdx) – mit React-Komponenten:

touch src/content/docs/guides/my-advanced-guide.mdx

Step 2: Add Frontmatter

Jede Dokumentationsseite muss mit YAML frontmatter beginnen:

---
title: My New Guide
description: A comprehensive guide to using advanced features.
---

# My New Guide

Your content goes here...

Required Frontmatter Fields

Field	Type	Description
title	Zeichenfolge	Seitentitel (erscheint im Browser-Tab und in der Navigation)
description	Zeichenfolge	Seitenbeschreibung für SEO und Vorschauen

Optional Frontmatter Fields

Field	Type	Description
sidebar.order	number	Custom ordering in sidebar
sidebar.label	string	Custom label in sidebar (defaults to title)
sidebar.hidden	boolescher Wert	Seite aus der Seitenleistennavigation ausblenden
editUrl	boolean/string	Enable/disable edit link or set custom URL
lastUpdated	boolean	Show last updated date
prev	boolean/object	Configure previous page link
next	boolean/object	Configure next page link
hero	Objekt	Heldenbereich hinzufügen (für Splash-Seiten)
banner	object	Add banner message
draft	boolean	Mark as draft (won’t build in production)

Adding to Navigation

Method 1: Automatic Generation

Für Verzeichnisse mit mehreren Seiten verwenden Sie die automatische Generierung in src/config/config.json:

{
  "label": "My Section",
  "autogenerate": { "directory": "guides" }
}

Method 2: Manual Configuration

Für bestimmte Seiten oder benutzerdefinierte Organisation:

{
  "label": "Getting Started",
  "items": [
    {
      "label": "Introduction",
      "slug": "getting-started/introduction"
    },
    {
      "label": "Quick Start",
      "slug": "getting-started/quick-start"
    }
  ]
}

Method 3: Mixed Approach

Kombinieren Sie die automatische Generierung mit manuellen Elementen:

{
  "label": "Guides",
  "items": [
    {
      "label": "Essential Guide",
      "slug": "guides/essential"
    },
    {
      "label": "Advanced Guides",
      "autogenerate": { "directory": "guides/advanced" }
    }
  ]
}

Content Examples

Basic Markdown Page

---
title: Getting Started with Components
description: Learn how to use and customize components in your documentation.
---

# Getting Started with Components

This guide covers the basics of working with components.

## Overview

Components are reusable pieces of content that help maintain consistency.

### Key Benefits

- **Reusability**: Use the same component across multiple pages
- **Consistency**: Maintain uniform styling and behavior
- **Maintainability**: Update once, reflect everywhere

## Usage

To use a component:

1. Import it at the top of your MDX file
2. Use it in your content
3. Pass any required props

```mdx
import { Card } from '@astrojs/starlight/components';

<Card title="Example Card">
  Das ist Karteninhalt.
</Card>

Next Steps

• Advanced Components
• Custom Styling

### MDX Page with Components

```mdx
---
title: Interactive Examples
description: Examples with interactive components and code previews.
---

import { Tabs, TabItem, Code } from '@astrojs/starlight/components';
import NewCard from '~/components/user-components/NewCard.astro';

# Interactive Examples

This page demonstrates interactive components.

<Tabs>
<TabItem label="Preview">
<NewCard title="Example Card" icon="rocket">
  This is an example of the NewCard component.
</NewCard>
</TabItem>
<TabItem label="Code">
```astro
<NewCard title="Example Card" icon="rocket">
  Dies ist ein Beispiel für die NewCard-Komponente.
</NewCard>

Code Examples

<Code code={console.log("Hello, World!");} lang=“js” title=“example.js” />

## Creating New Sections

### Step 1: Create Directory Structure

```bash
mkdir -p src/content/docs/my-new-section

Step 2: Add Pages

touch src/content/docs/my-new-section/overview.md
touch src/content/docs/my-new-section/getting-started.md
touch src/content/docs/my-new-section/advanced-usage.md

Step 3: Update Navigation

Add to src/config/config.json:

{
  "sidebar": [
    // ... existing sections
    {
      "label": "My New Section",
      "items": [
        {
          "label": "Overview",
          "slug": "my-new-section/overview"
        },
        {
          "label": "Getting Started",
          "slug": "my-new-section/getting-started"
        },
        {
          "label": "Advanced Usage",
          "slug": "my-new-section/advanced-usage"
        }
      ]
    }
  ]
}

Best Practices

File Naming

• Verwenden Sie die Groß-/Kleinschreibung für Dateinamen: my-guide.md
• Be descriptive but concise
• Passen Sie die gewünschte URL-Struktur an

Content Organization

1. Logical Grouping: Group related content in directories
2. Progressive Disclosure: Beginnen Sie mit den Grundlagen und gehen Sie zu komplexen Themen über
3. Cross-References: Link related pages together
4. Konsistente Struktur: Verwenden Sie ähnliche Überschriften und Organisation

Writing Guidelines

1. Titel löschen: Machen Sie Titel beschreibend und durchsuchbar
2. Gute Beschreibungen: Schreiben Sie überzeugende Beschreibungen für SEO
3. Richtige Kopfzeilen: Verwenden Sie h1 für den Seitentitel und h2 für Hauptabschnitte
4. Code Examples: Provide working, copy-paste-ready examples
5. Visuelle Elemente: Verwenden Sie aus Gründen der Übersichtlichkeit Komponenten, Tabellen und Beschriftungen

SEO and Accessibility

• Schreiben Sie beschreibende title- und description-Frontmatter
• Use proper heading hierarchy (h1 → h2 → h3)
• Add alt text to images
• Use semantic HTML elements
• Testen Sie mit Screenreadern

Troubleshooting

Page Not Appearing in Navigation

1. Überprüfen Sie, ob sich die Datei im richtigen Verzeichnis befindet
2. Verify frontmatter syntax
3. Stellen Sie sicher, dass die Seite zur config.json-Seitenleiste hinzugefügt wird
4. Restart development server

Build Errors

1. Validate YAML frontmatter syntax
2. Suchen Sie nach fehlenden Importen in MDX-Dateien
3. Ensure all referenced files exist
4. Review component syntax

Navigation Order Issues

1. Verwenden Sie sidebar.order im Frontmatter für benutzerdefinierte Bestellungen
2. Check alphabetical sorting in autogenerated sections
3. Verify manual ordering in config.json

Advanced Features

Custom Page Layouts

Verwenden Sie das Frontmatter-Feld template:

---
title: Landing Page
template: splash
hero:
  title: Welcome to Our Docs
  tagline: Everything you need to Loslegen
---

Page-Specific Styling

Add custom CSS classes:

---
title: Styled Page
---

<div class="custom-content">
  # Custom Styled Content

  This content has custom styling applied.
</div>

<style>
.custom-content {
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
  padding: 2rem;
  border-radius: 8px;
}
</style>

Conditional Content

Use MDX to show content conditionally:

import { Aside } from '@astrojs/starlight/components';

# Feature Documentation

{process.env.NODE_ENV === 'development' && (
  <Aside type="caution">
    This feature is still in development.
  </Aside>
)}

Regular documentation content...

Next Steps

• Customizing Components
• Advanced Configuration
• Deployment Guide