# Black Bean Docs — Features

Markdown documentation for WordPress — admin editor, public `/docs` site, hierarchical categories, and **filesystem sync** from plugin `docs/` folders.

Current release: **v0.9.9**

Related: [GETTING-STARTED.md](./GETTING-STARTED.md) · [CHANGELOG.md](../CHANGELOG.md)

---

## Content

| Feature | Purpose |
|---------|---------|
| Markdown storage | Docs live in Black Bean Tables (not `wp_posts`) |
| Categories | Hierarchical taxonomy (many-to-many with docs) |
| Render cache | HTML + checksum + version; re-render from attachment |
| Live preview | Paste markdown in admin before save |
| Excerpt | Auto from HTML or manual |

## Sync from plugins

| Feature | Purpose |
|---------|---------|
| Discovery | Scan `{plugin}/docs/**/*.md` + root `README.md` / `CHANGELOG.md` |
| Sections | Guides · Features · Release notes · Reference · Internal |
| Upsert | Stable slug per file; skip when checksum unchanged |
| Dry-run / force | Preview counts or re-import everything |
| CLI | `wp bb-docs sync` |

Internal section docs default to **draft**; other sections default to **publish**.

## Front-end

- `/docs/` — archive
- `/docs/{slug}/` — single doc (TOC, prev/next)
- `/docs/category/{slug}/` — category archive
- `/bb-docs-sitemap.xml` — XML sitemap

## REST (`blackbean/v1`)

- `GET /docs` — list (search, page, category)
- `GET /docs/categories`
- `GET /docs/{slug}`

## Admin

- Getting started (setup checklist)
- All docs
- Categories
- **Sync** (import from plugins)
- Edit doc (upload `.md`, status, categories)

## Requirements

- WordPress **6.0+**, PHP **8.1+**
- **Black Bean Tables** with `docs` + `doc_categories` seeded and synced
- Optional: `composer install` in docs (or theme) for League CommonMark