# cms-edit — Article Field Reference

An `article` entry is a blog post, news item, or publication. It has a slug, date, article type classification, and usually a `content` array of body components.

Read `cms-edit://customer/articles` for site-specific playbooks (press releases, publications, tag rules).

---

## Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `slug` | Text | Yes | URL slug without leading or trailing slash. Example: `part1/part2/part3` |
| `title` | Text | Yes | Article title |
| `description` | Text | No | SEO meta description — keep under ~160 characters when used for meta |
| `subtitle` | Text | No | Display line on news/publication heroes (site-specific) |
| `cmsLabel` | Text | No | Label in Contentful's entry list. Defaults to `title` |
| `date` | Date | Yes | Publication date in `YYYY-MM-DD` format. Defaults to today in `create from-json` |
| `articleType` | Link (Entry) | Yes | Link to an `articleType` entry (categorises the article) |
| `tags` | Array of Links | No | Tag entries (often drives URL topic segment when primary tag is in slug) |
| `content` | Array of Links | No | Body components — see [Template hierarchy](#template-hierarchy) before adding heroes |
| `template` | Link (Entry) | No | Per-article layout override (rare); overrides `articleType.articleTemplate` |
| `featuredImage` | Link (Asset) | No | Often used for OpenGraph / social sharing — prefer **landscape** (wider than tall) |
| `visuals` | Array of Links | No | Media entries — on many sites drives on-page hero and listing thumbnails |
| `download` | Link (Asset) | No | Downloadable file (e.g. PDF poster) |
| `icon` | Link (Asset) | No | Icon asset |
| `authors` | Array of Links | No | Person entries (ordered bylines) |
| `externalLink` | Text | No | External URL (e.g. DOI, journal link) |
| `indexed` | Boolean | Yes | Search indexing (default `true`) |
| `hidden` | Boolean | Yes | Sitemap visibility (default `false`) |

### `featuredImage` vs `visuals`

On sites that use **both** fields, they often serve different purposes:

| Field | Typical use |
|-------|-------------|
| `visuals` | On-page hero image and listing/card thumbnail |
| `featuredImage` | OpenGraph and social sharing cards (landscape) |

Read `cms-edit://customer/articles` and `defaults` for site rules. When the playbook requires both, set each explicitly — do not omit `featuredImage` expecting inheritance to fill gaps on listing or OG surfaces.

---

## Template hierarchy

Rendered article layout is assembled from the article entry **and** a resolved **template** entry:

1. Article `template` field (if set) — takes precedence
2. Else linked `articleType` → `articleTemplate` field

Template entries provide `preContent` and `postContent` arrays that wrap the article's `content` field. On many marketing sites, **heroes and shells live in the template**, not in per-article `content`.

Before adding components to an article:

```bash
cms-edit list --type articleType
# Note articleTemplate on the target type, then inspect that template:
cms-edit peek --id <template-entry-id>
```

**Do not duplicate** hero or layout components in `content` when the resolved template's `preContent` / `postContent` already provides them. The site playbook (`cms-edit://customer/articles`) lists which component types belong in `content` (e.g. rich text only).

> **Note:** `articleType.articlePageTopContent` exists in Contentful on some spaces but is **not** read by the standard article converter — use `articleTemplate` → `preContent` instead.

---

## Finding article types (required)

```bash
cms-edit list --type articleType
```

Every article must link to an **articleType**. Prefer slug-based lookup for marketers:

- CLI: `--article-type-slug resources/blog` or `--article-type-name "Blog"`
- JSON: `articleTypeSlug` or `articleTypeName` (or `articleTypeId` if you have the ID)

---

## Listing Recent Articles

Sort by publication `date` (matches the website), not `sys.updatedAt`:

```bash
cms-edit list --type article --sort date -n 10
cms-edit search "keyword" --type article
cms-edit list --type article --sort date
```

To find **draft** articles: `cms-edit list --type article --sort date` (preview index includes drafts), then `cms-edit peek --article-slug <slug>` or `cms-edit open --id <id>`. `peek` and `open` load draft content — only `list --published` is published-only.

---

## Reading Article Fields

```bash
cms-edit open --article-slug /news/2025-hepatology-study
cms-edit read @c0              # all fields
cms-edit read @c0 date
cms-edit read @c0 description
```

---

## Setting Article Fields

```bash
cms-edit set @c0 title "Updated Article Title"
cms-edit set @c0 description "New meta description."
cms-edit set @c0 date "2025-06-01"
```

---

## Adding Content to an Article

Check [Template hierarchy](#template-hierarchy) and the site articles playbook first.

```bash
# Add a component to the article's content array
cms-edit add TextBlock component

# Add a collection
cms-edit add CardGrid collection

# Insert after a specific component
cms-edit add Generic component --after @c3
```

Rename component `cmsLabel` from defaults like "New Article rich text" to a descriptive label (site playbook may specify a pattern).

---

## In create from-json

```json
{
  "type": "article",
  "slug": "news/2025-hepatology-study",
  "title": "New Hepatology Cohort Study Published",
  "description": "A landmark study on hepatology cohort data.",
  "date": "2025-06-01",
  "articleTypeSlug": "resources/blog",
  "featuredImageAssetFilename": "hero-landscape.jpg",
  "visualsIds": ["<media-entry-id>"],
  "components": [
    {
      "contentType": "component",
      "type": "TextBlock",
      "fields": {
        "heading": "Study Overview",
        "body": "The study included 1,200 patients.\n\nResults showed significant improvement.",
        "cmsLabel": "News — New Hepatology Cohort Study Published"
      }
    }
  ]
}
```

Auto-detection: if `articleTypeId` is present and `type` is omitted, the entry is automatically created as an article.