# Create an article

A new article is a content record you prepare in the article editor and publish to its own
article view. Use this task when you have the article's title, description, markdown body, and
tags ready to enter.

| If you need to… | Go to |
|---|---|
| Confirm what the new-article task contains | [Understand the editor](#understand-the-editor) |
| Open the new-article editor | [Open the article editor](#open-the-article-editor) |
| Enter content, add tags, and publish | [Enter the article and publish it](#enter-the-article-and-publish-it) |
| Handle tags or the disabled editor | [Handle tags and editor states](#handle-tags-and-editor-states) |
| Read the published article | [Read an article](doc:read-an-article) |
| Change an existing article | [Edit an article](doc:edit-an-article) |
| Resolve a publish error | [General error messages](doc:general-error-messages) |
| Find broader recovery guidance | [Common issues and solutions](doc:common-issues-and-solutions) |

## Before you start

Prerequisites

- Sign in before opening the new-article editor.
- Have the article title, description, markdown body, and tags ready to enter.
- Decide which tags belong to the article before publishing; each tag is added separately.

The new-article route requires authentication. If you open it without being signed in, the
application sends you to the sign-in route. With the content ready and your account signed in,
open the editor.

## Open the article editor

The new-article editor is the page where you enter the content that becomes a new article.

Prerequisites

- You are signed in.

Steps

1. Open `/editor`.
2. Confirm that the editor shows **Article Title**, **What's this article about?**, **Write your
   article (in markdown)**, **Enter tags**, and **Publish Article**.

**Result:** The new-article editor is open and ready for content.

## Understand the editor

The editor has four inputs for the article's main content and a tag area for the labels attached
to it. A tag is a repeatable label attached to the article. The main content inputs are:

| If you need to enter… | Use | What it holds |
|---|---|---|
| The article's name | **Article Title** | The title shown for the article |
| A short description | **What's this article about?** | The article description |
| The article content | **Write your article (in markdown)** | Markdown text; the area is eight rows high |
| A tag | **Enter tags** | One tag before you add it to the tag list |

After you add a tag, it appears in the tag list. Each existing tag has a close control beside it,
which removes that tag from the list. The page has one committing control, **Publish Article**.
There is no table of detail rows in this editor, so article content goes in the four inputs rather
than in a grid. Publishing does not open a confirmation dialog.

The editor does not show a required marker for the four inputs. Enter the information that belongs
in each field, then publish the article.

## Enter the article and publish it

Enter the article's main content, add each tag, and submit the completed form from the same editor.

Prerequisites

- The new-article editor is open.
- You have the title, description, markdown body, and tags ready.

Steps

1. Enter the article title in **Article Title**.
2. Enter the short description in **What's this article about?**.
3. Enter the article content in **Write your article (in markdown)**.
4. Add each tag through **Enter tags** and Enter.

   | If you need to… | Do this |
   |---|---|
   | Add the first tag | Enter it in **Enter tags**, then press Enter. |
   | Add another tag | Replace the cleared input with the next tag, then press Enter. |

5. Select **Publish Article**.

The editor submits the article and temporarily disables its fields and publish control while the
publish request is in progress.

**Result:** The application opens the article view when the publish request returns an article
slug.

## Handle tags and editor states

Use the tag list to review and remove labels before publishing.

Prerequisites

- The new-article editor is open.
- To remove a tag, that tag is already visible in the tag list.

Steps

1. Enter a tag in **Enter tags**.
2. Press Enter to add the tag and clear the input.
3. Review the tag list for the tag you added.
4. Select the close control beside an existing tag to remove it.

Use the tag list to keep only the labels that belong to the article. When publishing starts, the
editor fields and **Publish Article** are disabled until the request finishes.

**Result:** The tag list contains the labels you kept, and the editor is available again after the
publish request finishes.

## When publishing goes wrong

The editor displays publish failures in its error list above the form. A connection failure uses
the message `Unable to connect to the server`. The error list shows the error key and message
returned by the server. The server-provided error key and message values are rendered.

| What you see | What it means | What to do |
|---|---|---|
| `Unable to connect to the server` | The application could not connect to the server. | Check the connection and select **Publish Article** again. |
| A server-provided error key followed by one or more messages | The server rejected the publish request or returned another error. | Correct the information named by the message, then select **Publish Article** again. |

After a failed publish, the editor becomes available again and the error list remains the place to
read the returned messages.

## After publishing

The article view is the page for the article that has just been published. A successful response
supplies the article's slug, and the application uses that slug to open the view.

Publishing has no separate confirmation message. Continue with [Read an article](doc:read-an-article)
from the article view. To change the article later, use [Edit an article](doc:edit-an-article).

**Result:** The published article is open in its article view.