> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skayle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contentful Setup

> Connect Contentful with Management API credentials, map content type fields, and publish taxonomy references safely.

## 1. Overview

Contentful connector publishes Skayle posts to a chosen Contentful content type.

It requires:

* `spaceId`
* `environment`
* `token` (Management API token)
* `contentTypeId`
* `fieldMapping`
* `taxonomyMapping`

## 2. Prerequisites

Before connecting:

* Contentful space and environment
* Post content type for Skayle posts
* Taxonomy content types for category/tag/author
* Reference fields on your post content type

## 3. Creating API credentials

In Contentful:

1. Go to `Settings -> API keys`.
2. Create a `Content Management API` token (or Personal Access Token with equivalent rights).
3. Copy Space ID, Environment, and token.

In Skayle, enter these values in connector settings.

## 4. Required permissions

Use a token with read/write management rights.

Do not use Delivery API or Preview API tokens for connector publishing.

## 5. CMS-side setup

Create/confirm:

* Main post content type (for example `blogPost`)
* Required fields for title, slug, excerpt, content
* Optional fields for featured image, publish date, status
* Taxonomy content types for categories/tags/authors
* Reference fields in post entries for taxonomy relations

No webhook setup is required.

## 6. Connecting in Skayle

1. Open `Settings -> Connector`.
2. Select `Contentful`.
3. Enter Space ID, Environment, and Management token.
4. Test connection.
5. Select post content type.
6. Map Skayle fields to Contentful field IDs.
7. Map taxonomy content type IDs.
8. Save connector.

## 7. Field mapping explanation

Required post field mappings:

* Title
* Slug
* Excerpt
* Content

Optional mappings:

* Featured image
* Publish date
* Status

Taxonomy mapping maps each taxonomy entity to a Contentful content type ID.

Publishing behavior:

* Published posts are created/updated and then published.
* Draft posts are created/updated and remain unpublished.
* Referenced taxonomy entries must be publishable for parent entry publish to succeed.

## 8. Publishing test article

1. Create a draft in Skayle.
2. Assign category/tag/author.
3. Publish from Skayle.
4. Confirm entry appears under selected content type.
5. Confirm referenced taxonomy entries exist and are linked.
6. Confirm entry status in Contentful matches expected draft/published state.

## 9. Common errors & troubleshooting

| Issue                            | Likely cause                                       | Fix                                                |
| -------------------------------- | -------------------------------------------------- | -------------------------------------------------- |
| Unauthorized token error         | Delivery/Preview token used                        | Replace with Management API token                  |
| Space or environment not found   | Wrong IDs                                          | Verify Space ID and environment name               |
| Publish conflict/version errors  | Entry version mismatch                             | Retry publish/update from latest state             |
| Failed publish due to references | Referenced taxonomy entries unpublished or invalid | Publish/fix referenced entries and retry           |
| Taxonomies not linked            | Missing taxonomy mappings or reference fields      | Verify taxonomy content types and reference fields |

## 10. Best practices

* Keep content type field IDs stable after mapping.
* Define taxonomy content types before first publish.
* Validate one post and one update cycle before bulk rollout.
* Keep one connector-specific service token for auditability.