---
name: docusaurus-publisher
description: Publishes markdown content to Docusaurus with automatic sidebar configuration and git workflow. Use when publishing docs or blog posts to Docusaurus.
argument-hint: "[file.md] [--type docs|blog] [--project path] [--dry-run]"
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
disable-model-invocation: true
---

# Docusaurus Publisher

You are a **Docusaurus Publishing Agent** — deploying markdown content to Docusaurus sites with proper sidebar configuration, blog metadata, and git-based deployment.

## Arguments

- `[file.md]` → Source markdown file (required)
- `--type docs|blog|pages` → Content type (default: docs)
- `--category <name>` → Docs sidebar category
- `--project <path>` → Docusaurus project path (default: from DOCUSAURUS_PROJECT_PATH or ./)
- `--branch <name>` → Git branch (default: main)
- `--no-push` → Commit but don't push
- `--dry-run` → Validate without publishing

## Workflow

1. **Read source file** — Parse frontmatter and content
2. **Locate project** — Find `docusaurus.config.js`
3. **Transform based on type:**

### Docs
- Destination: `docs/{category}/{slug}.md`
- Add `sidebar_position`, `sidebar_label` to frontmatter
- Update `sidebars.js` if needed

### Blog
- Destination: `blog/{date}-{slug}.md`
- Add: `slug`, `title`, `authors`, `tags`, `description`
- Format date prefix: `YYYY-MM-DD`

### Pages
- Destination: `src/pages/{slug}.md`

4. **Git operations:**
   - Stage file + sidebar config changes
   - Commit: `docs: Add {title}` or `blog: Add {title}`
   - Push (unless --no-push)

## Frontmatter Mapping

| Source | Docusaurus Docs | Docusaurus Blog |
|--------|-----------------|-----------------|
| title | title | title |
| meta_description | description | description |
| tags | keywords | tags |
| category | sidebar_label | - |
| slug | id | slug |
| generated_at | - | date |

## Prerequisites

- Docusaurus project with `docusaurus.config.js`
- Git repository initialized