> For the complete documentation index, see [llms.txt](https://docs.sageseo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sageseo.ai/getting-started/publishing.md).

# Publishing Articles to WordPress

When an article is finished generating, Sage publishes it directly to your WordPress site — no copy-paste, no manual upload. One click (or zero clicks if autopilot is on), and the article is live with featured image, proper category, meta description, and slug.

This page covers the user-facing flow. For the methodology behind how Sage assembles the post, see [How Sage Publishes Articles](/reference/publishing-mechanics.md).

{% hint style="info" %}
**Key Takeaways**

* Click Publish on any **Ready for review** article — Sage pushes it to WordPress with no dialog if your credentials are already saved
* Featured image, meta description, slug, and category are all derived automatically
* Auto-publish mode (autopilot ON) skips the manual click and publishes the moment generation finishes
* Sage immediately submits the URL to Google for indexing after every publish
* If credentials are missing or rejected, you'll see a one-screen modal to fix that — never a multi-step dialog otherwise
  {% endhint %}

## One-time setup: connect your WordPress site

Before Sage can publish, you need to give it permission to log into your WordPress site. Sage uses **WordPress Application Passwords** — a native WP feature since version 5.6 (December 2020).

### Why App Passwords (not your main login)

Application Passwords are:

* **Revocable from your WP user profile** without changing your main password
* **Audit-tracked separately** so Sage's actions show up distinctly from your own logins
* **Scoped to API access only** — they can't log in to the WP admin UI as you
* **Industry standard** — same pattern used by Buffer, Jetpack, ManageWP, etc.

### How to connect

1. Go to **Settings → WordPress** in Sage
2. Click **Connect WordPress** on the domain you want to publish to
3. Sage redirects you to your WP site's authorization screen
4. Approve the Sage application
5. WP redirects back to Sage with the connection live

After this, every article on that domain publishes through Sage automatically.

```mermaid
sequenceDiagram
    participant You
    participant Sage
    participant WP as Your WordPress Site
    You->>Sage: Click Connect WP
    Sage->>WP: Redirect to authorize-application URL
    WP->>You: "Approve Sage to access this site?"
    You->>WP: Approve
    WP->>Sage: Return with App Password
    Sage->>Sage: Store credentials securely
    Note over Sage,WP: Future publishes use this connection
```

## Publishing an article

### Auto-publish mode (autopilot ON)

If autopilot is on for the domain, every generated article publishes automatically the moment it finishes — no clicks required. You see it move from **Generating** → **Published** in the Activity panel.

### Review-first mode (autopilot OFF)

Generated articles land in the **Up next** column as **Ready for review**. To publish:

1. Click the green **Publish** button on the article card
2. Sage pushes the article to WordPress with the saved credentials
3. You see a "Published to WordPress" confirmation
4. The article appears in WordPress immediately + on your site

No dialog appears for normal publishes — Sage already has everything it needs. If your credentials are missing or have been revoked, you'll see a small modal to reconnect, but otherwise the flow is one click → live.

## What Sage assembles before pushing

Sage doesn't just hand WordPress a blob of HTML. Before publishing, it builds a polished, structured post:

| Element                      | What Sage does                                                                                                                  | Why                                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Body**                     | Strips duplicate sections sage-ai's writer sometimes inlines, then re-injects the canonical Key Takeaways callout + FAQ section | Avoids double "Key Takeaways" sections on the published page                         |
| **Featured image**           | Uses the AI-generated image from the pipeline                                                                                   | Required for the WP post to display properly + show in social previews               |
| **Meta title + description** | Derived from the article title + opening paragraph                                                                              | Drives the Google search snippet — without this it'd be auto-truncated content       |
| **URL slug**                 | Kebab-case version of the title, capped at 80 chars                                                                             | Clean URLs rank better and look more credible in search results                      |
| **Category**                 | Auto-picks the best-matching non-Uncategorized category from your WP site                                                       | Affects internal navigation, archive pages, and Google's read of your site structure |
| **Status**                   | `publish`                                                                                                                       | Article goes live immediately, not as draft                                          |
| **Tags**                     | (Coming soon)                                                                                                                   | Not currently auto-assigned                                                          |

If you want to override any of these before publishing, click **Edit** on the article first — you can modify title, body, slug, etc.

See [How Sage Publishes Articles](/reference/publishing-mechanics.md) for the full methodology behind the assembly.

## Category auto-pick

Sage will **never publish an article as "Uncategorized"** if your WP site has any other category. The auto-pick logic:

```mermaid
flowchart TD
  A[Article ready to publish] --> B[Fetch your WP site's category list]
  B --> C{Topic match?}
  C -->|"Yes — category name contains target keyword"| D[Use matching category]
  C -->|No match found| E[Use first non-Uncategorized category]
  E --> F{Any non-Uncategorized exists?}
  F -->|Yes| G[Publish to that category]
  F -->|No, only Uncategorized exists| H[Publish to Uncategorized + log warning]
  D --> I[Article publishes with right category]
  G --> I
  H --> J[Add a real category to your WP site]
  classDef good fill:#E3FCEF,stroke:#006644,color:#091E42
  classDef warn fill:#FFF4E5,stroke:#FF8B00,color:#091E42
  class D,G,I good
  class H,J warn
```

If you want all articles on a domain to land in one specific category, set a **default category** in the domain settings. Sage will use that instead of the auto-pick.

## What happens after publishing

Sage's job isn't done when the article goes live. The next \~24–72 hours determine whether it actually drives traffic:

1. **Sage tells Google about the URL** — submitted to the Indexing API the moment publishing succeeds, shortening crawl time from days to hours. See [Telling Google About New Articles](/reference/indexing-submission.md).
2. **Sage queues a URL inspection** — checks Google's index status within a few hours so you know whether the article was accepted. See [Checking If Google Has Your Article](/reference/url-inspection.md).
3. **Article appears on the Google Index dashboard** — with status pill, last-crawled date, and impression count once Google starts ranking it.
4. **Performance flows into analytics** — clicks, impressions, top queries all surface in the Domain Performance Dashboard once they accumulate.

## What happens if something fails

| Error                              | Why                                                           | What you see                                                                 |
| ---------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **WordPress credentials missing**  | No App Password stored for this domain                        | A modal asking you to connect WP first                                       |
| **WordPress credentials rejected** | The stored App Password was revoked or expired                | A modal asking you to reconnect WP                                           |
| **Article body is empty**          | Generation finished but the body never made it to the article | Error toast; the article goes back to a state where you can retry generation |
| **Can't reach WordPress site**     | Your WP site is down or the URL is wrong                      | Error toast — check that your domain URL is correct in Sage                  |
| **WordPress returned an error**    | WP-level issue (plugin conflict, server error, etc.)          | Error message from WP shown in the toast so you can debug                    |

Most of these resolve themselves with one retry. Sage doesn't retry automatically — it shows you what happened so you can decide.

## Frequently asked questions

### Do I need the old JSON Basic Authentication plugin?

No — Sage uses WordPress Application Passwords, which is a native feature in any WP 5.6+ site (December 2020 and later). No plugin install needed. If you're on an older WP version, upgrade — App Passwords are more secure than the legacy basic auth flow.

### Can I publish to a site that isn't WordPress?

Currently Sage publishes to WordPress only. Shopify, Webflow, and custom CMS integrations are on the roadmap. For now, you can copy a finished article from Sage and paste it into any platform manually — but you'll lose the auto-categorization, auto-image, and auto-indexing features.

### Will Sage overwrite an existing article on my WP site?

No. Each Sage article creates a new WP post with a unique slug. If you want to update a previously-published Sage article, edit it in Sage and re-publish — Sage detects the existing WP post by its stored WP ID and updates that instead of creating a duplicate.

### Can I publish to a draft state instead of live?

Currently Sage publishes as `publish` status (live). Publishing as `draft` is on the roadmap for agencies that want a final WP-side review gate in addition to Sage's review-first mode.

### What if the article publishes but Google doesn't index it?

This is normal — not every URL gets indexed, especially on newer or lower-authority sites. The Google Index dashboard will show "Not indexed" status; see [Google Index Status](/getting-started/google-index.md) for the playbook.

### How do I publish to multiple WordPress sites?

Connect each domain to its own WP site (one App Password per domain). Sage handles multiple connections in parallel — articles on Domain A publish to Site A, articles on Domain B publish to Site B.

## Related

* [How Sage Publishes Articles](/reference/publishing-mechanics.md) — the methodology behind what Sage assembles
* [Telling Google About New Articles](/reference/indexing-submission.md) — what happens immediately after publishing
* [Checking If Google Has Your Article](/reference/url-inspection.md) — how Sage tracks indexing post-publish
* [Google Index Status](/getting-started/google-index.md) — where post-publish status lives in the UI
* [Autopilot](/reference/autopilot.md) — auto-publish mode mechanics