MD2WordPress/QUICKSTART.md

# Schnellstart-Anleitung

## ⚠️ Wichtige Hinweise

**Autor-Zuordnung:** Beiträge werden dem importierenden WordPress-Benutzer zugeordnet (nicht dem Autor aus dem Frontmatter).

**Empfehlung:** Starten Sie mit **einzelnen URLs** zum Testen, bevor Sie Batch-Imports durchführen.

## Überblick

Das System extrahiert **automatisch alle Metadaten aus dem YAML-Frontmatter** Ihrer Markdown-Dateien:
- **name** → WordPress-Titel
- **description** oder **summary** → Excerpt
- **image** → Beitragsbild
- **tags** → WordPress-Tags
- **categories** → WordPress-Kategorien
- **author** → WordPress-Autor (aktuell nur extrahiert, nicht zugeordnet)

Sie müssen nur noch die **URL zur Markdown-Datei** angeben!

## Drei Verwendungsmodi

### 1. Einzelne URL (Am einfachsten! ⭐ Empfohlen zum Testen)

```bash
source .venv/bin/activate
python workflow.py "https://example.com/artikel.md"
```

### 2. Mehrere URLs aus YAML-Datei

Erstellen Sie `posts.yaml`:
```yaml
posts:
  - url: "https://example.com/artikel1.md"
  - url: "https://example.com/artikel2.md"
  - file: "content/lokaler-artikel.md"
```

Dann ausführen:
```bash
source .venv/bin/activate
python workflow.py posts.yaml
```

### 3. Ganzes Repository (Forgejo/Gitea)

**Alle Markdown-Dateien importieren:**
```bash
source .venv/bin/activate
python workflow.py --repo "https://codeberg.org/user/repo" main
```

**Nur bestimmte Dateien importieren (mit Filter):**
```bash
source .venv/bin/activate
python workflow.py --repo "https://git.rpi-virtuell.de/Comenius-Institut/FOERBICO_und_rpi-virtuell" main --filter 'Website/content/posts/*/index.md'
```

**Filter-Beispiele:**
- `'posts/*/index.md'` - Nur index.md in posts/-Unterverzeichnissen
- `'Website/content/posts/*/index.md'` - Mit vollständigem Pfad
- `'content/*.md'` - Alle .md-Dateien direkt in content/

**Hinweis:** Der Filter unterstützt Wildcards (`*`) für Verzeichnisnamen.

## Schnellstart-Schritte

## 1. Virtuelle Umgebung aktivieren

Aktivieren Sie zuerst die Python-Umgebung:

```bash
source .venv/bin/activate
```

Sie sollten jetzt `(.venv)` am Anfang Ihrer Kommandozeile sehen.

## 2. Abhängigkeiten installieren

Die Python-Pakete sind bereits installiert. Falls Sie sie neu installieren müssen:

```bash
pip install -r requirements.txt
```

## 3. WordPress-Username eintragen

Bearbeiten Sie die `.env`-Datei und tragen Sie Ihren WordPress-Benutzernamen ein:

```env
WORDPRESS_URL=https://news.rpi-virtuell.de
WORDPRESS_USERNAME=IHR_USERNAME_HIER  # ← Hier eintragen!
WORDPRESS_APP_PASSWORD=UIVI 4Tdy oojL 9iZG g3X2 iAn5
```

## 4. posts.yaml anpassen (Optional - nur für Batch-Verarbeitung)

Für **einzelne URLs** brauchen Sie keine YAML-Datei!

Für **mehrere Beiträge** erstellen Sie `posts.yaml`:

```yaml
posts:
  - url: "https://ihre-url.de/artikel.md"
  - file: "content/lokaler-artikel.md"
  
settings:
  default_status: "draft"
```

**Das war's!** Alle Metadaten (Titel, Tags, Kategorien, Bild) kommen aus dem Frontmatter der Markdown-Dateien.

## 5. Workflow ausführen

Stellen Sie sicher, dass die virtuelle Umgebung aktiviert ist (siehe Schritt 1), dann:

### Einzelne URL (empfohlen für Tests):
```bash
python workflow.py "https://example.com/artikel.md"
```

### Mehrere URLs aus YAML:
```bash
python workflow.py posts.yaml
```

### Ganzes Forgejo-Repository:
```bash
python workflow.py --repo "https://codeberg.org/user/repo" main
```

## Testen mit dem Beispiel-Beitrag

Ein Test-Beitrag mit vollständigem Frontmatter ist in `content/beispiel-beitrag.md`.

**Direkter Test:**
```bash
python workflow.py "content/beispiel-beitrag.md"
```

**Oder über YAML:**
```yaml
posts:
  - file: "content/beispiel-beitrag.md"
```

```bash
python workflow.py posts.yaml
```

## Was passiert beim Ausführen?

1. ✅ System lädt die Markdown-Datei (von URL oder lokal)
2. ✅ **Extrahiert automatisch Metadaten aus dem YAML-Frontmatter:**
   - `name` → Titel
   - `description`/`summary` → Excerpt
   - `image` → Beitragsbild
   - `tags` → WordPress-Tags
   - `categories` → WordPress-Kategorien (falls vorhanden)
   - `author` → Autor
3. ✅ Konvertiert Markdown zu HTML
4. ✅ Prüft ob Beitrag bereits existiert (nach Titel)
5. ✅ Erstellt fehlende Kategorien/Tags
6. ✅ Lädt Beitragsbilder hoch (falls vorhanden)
7. ✅ Erstellt den WordPress-Beitrag

## Frontmatter-Beispiel

Ihre Markdown-Dateien sollten so aussehen:

```markdown
---
name: "Mein Artikel-Titel"
description: "Eine kurze Zusammenfassung des Artikels"
image: "https://example.com/bild.jpg"
tags:
  - WordPress
  - Tutorial
  - Open Source
categories:
  - Tutorials
author:
  - Max Mustermann
---

# Artikel-Inhalt

Hier beginnt der eigentliche Inhalt...
```

Das System versteht auch Schema.org-Metadaten (wie im `beispiel-beitrag.md`)!

## Wichtige Hinweise

- **Duplikate**: Beiträge mit gleichem Titel werden NICHT doppelt erstellt
- **Medien**: Bilder mit gleichem Dateinamen werden NICHT doppelt hochgeladen
- **Status**: Standard ist "draft" - Sie können dies auf "publish" ändern
- **Sicherheit**: Die `.env`-Datei ist in `.gitignore` und wird nicht committed

## Beispiel-Ausgabe

```
Direkt-Modus: Verarbeite URL: https://example.com/artikel.md

Verbinde mit WordPress: https://news.rpi-virtuell.de

============================================================
Verarbeite Markdown von URL: https://example.com/artikel.md
============================================================
Titel: Die Kraft der Gemeinschaft: Prozesse statt Strukturen
Beitrag 'Die Kraft der Gemeinschaft' erstellt (ID: 123, Status: draft)

✅ Erfolgreich: Beitrag erstellt (ID: 123)
```

## Nächste Schritte

1. **Testen Sie mit dem Beispiel-Beitrag:**
   ```bash
   python workflow.py "content/beispiel-beitrag.md"
   ```

2. **Testen Sie mit Ihrer eigenen URL:**
   ```bash
   python workflow.py "https://ihre-url.de/artikel.md"
   ```

3. **Für Batch-Verarbeitung:** Erstellen Sie `posts.yaml` mit mehreren URLs

4. **Für Repository-Import:** Nutzen Sie `--repo` für Forgejo/Gitea

5. **Überprüfen Sie die Beiträge in WordPress**

6. **Bei Erfolg:** Ändern Sie `default_status: "publish"` in den Settings

## Hilfe

Bei Problemen siehe `README.md` → Abschnitt "Fehlerbehebung"