# Conduit (Vue) # Discover articles ## Discover articles Article discovery is the work of finding something to read in the site's shared article collection, in the articles from people you follow, or under a particular tag. **Your Feed** is the following feed, **Global Feed** is the global feed, and a tag route supplies a tag-filtered list. Use the Home screen to choose a feed, review article summaries, and open an article when its subject interests you. The Home screen leads to the article page; an author's name leads to that author's profile. | If you need to… | Go to | |---|---| | Reach the right feed or tag route | [Find a feed](#find-a-feed) | | Understand the areas on the Home screen | [Understand the discovery screen](#understand-the-discovery-screen) | | Choose or filter the articles | [Choose and filter results](#choose-and-filter-results) | | Move through more than one page of results | [Work through the results](#work-through-the-results) | | Read the article you found | [Read an article](doc:read-an-article) | | View or follow its author | [View a profile](doc:view-a-profile) or [Follow an author](doc:follow-an-author) | | Find articles you have favorited | [View favorited articles](doc:view-favorited-articles) | | Learn the wider route layout | [Navigation basics](doc:navigation-basics) | ## Before you start You choose between the available feeds from the Home screen. Sign in before using the personal feed. A tag-filtered feed starts from a tag route, while the global feed is the default Home view. Prerequisites - Know whether you need articles from the people you follow or from the whole collection. - Sign in if you need **Your Feed**. - Have the tag you want to use if you are opening a tag-filtered feed. When you are signed out, the Home screen includes the **conduit** banner and the text “A place to share your knowledge.” ## Find a feed Use this procedure when you need to reach a following, global, or tag-filtered list of articles. Prerequisites - You are on the Home screen. - You are signed in before selecting **Your Feed**. Steps 1. Choose the list that matches what you want to read. | If you need to… | Select | |---|---| | Read articles from people you follow | **Your Feed** | | Read the complete article collection | **Global Feed** | | Read articles grouped under a tag | Open the tag route for the tag you want to review. | **Result:** The selected feed or tag-filtered article list is on screen. ## Understand the discovery screen The discovery screen is a feed view: feed choices are at the top, **Popular Tags** is in the sidebar, and article previews fill the main area. An article preview is a short version of an article; it contains the article title, description, author information, date, and tags. A page-number control appears when the results span more than one page. | Area | What you use it for | |---|---| | **Your Feed** and **Global Feed** | Change the article collection you are reviewing. | | Tag tab | Keep the selected tag as the article filter. | | **Popular Tags** | See the tag area beside the article list. | | Article preview | Review the title, description, author, date, and tags before opening the article. | | Page number | Move to another results page when more than one page is available. | | Article list while loading | Wait for the article area to finish loading. | | Empty article list | Read `No articles are here... yet.` when the loaded list has no articles. | | Empty personal feed | Read `Your feed is empty. Go to the Global Feed to discover articles.` when the following feed has no articles. | The personal-feed message includes a link to **Global Feed**, which takes you to the global list. ## Choose and filter results Choose a feed when you want to change the collection being reviewed. Use a tag route when a specific subject is more useful than a broad feed. Prerequisites - You are on the Home screen. - You are signed in if you are choosing **Your Feed**. Steps 1. Select the route that matches your reading goal. | Reading goal | Route or control | |---|---| | Read from people you follow | Select **Your Feed**. | | Read the global collection | Select **Global Feed**. | | Read one subject's articles | Open the tag route for that subject. | 2. Confirm that the selected feed is active at the top of the Home screen. **Result:** The Home screen shows the articles for the selected following feed, global feed, or tag filter. ## Work through the results The results list uses page 1 when no positive page number is in the route. When the article count is greater than 10, the list creates page numbers from the total count; selecting another page changes the results page. Prerequisites - You have opened a feed or tag-filtered list. Steps 1. Review the current article previews. 2. Choose what to do with the results. | If… | Then | |---|---| | More than one page is available | Select the page number you want to open. | | The loaded list has no articles | Read `No articles are here... yet.`. | | **Your Feed** has no followed articles | Read `Your feed is empty. Go to the Global Feed to discover articles.`. | **Result:** The selected results page is on screen, or the appropriate empty-list message tells you that there are no articles to review in that list. If the results do not reach this state, continue with [When results do not load](#when-results-do-not-load). ## When results do not load While articles are loading, the article area shows a loading placeholder. Article and tag request failures do not provide a user-facing error message in this flow. Prerequisites - You have opened a feed or tag-filtered list. Steps 1. Check the article area until the loading placeholder is replaced by results or an empty-list message. 2. If the results do not reach their result state, use the applicable guidance. | If… | Do this | |---|---| | The article request does not reach a result state | Use [General error messages](doc:general-error-messages) for shared error guidance. | | The tag area does not populate after opening a tag route | Use [General error messages](doc:general-error-messages) for shared error guidance. | **Result:** The article area either reaches its result state or remains covered by the shared error guidance. Continue with [Open an article](#open-an-article) when results are available. ## Open an article Use an article preview when its title or description tells you that the article is relevant; use the author's profile when you want author information. Prerequisites - You have an article preview on screen. Steps 1. Choose the destination that matches what you want to do. | If you want to… | Select or open | |---|---| | Read the article | **Read more...** or the article title in the preview | | View the author | The author's name | | Continue to sign in from a favorite action | The favorite button beside the article metadata | **Result:** The article route or the author's profile is on screen. Continue with [Read an article](doc:read-an-article) or [View a profile](doc:view-a-profile). # FAQ ## What this FAQ covers Find the page that owns the answer to your question. No dedicated FAQ surface is declared. | If you need to… | Go to | |---|---| | understand what conduit is | [What is conduit](doc:what-is-conduit) | | decide who uses conduit | [Who uses conduit](doc:who-uses-conduit) | | understand the available capabilities | [What can you do with conduit](doc:what-can-you-do-with-conduit) | | prepare the application | [System requirements](doc:system-requirements) | | choose a help destination | [Getting help](doc:getting-help) | | complete your first sign-in and profile visit | [Your first day](doc:your-first-day) | | understand the interface | [Understanding the interface](doc:understanding-the-interface) | | move around the application | [Navigation basics](doc:navigation-basics) | | personalize your workspace | [Personalizing your workspace](doc:personalizing-your-workspace) | | learn product terms | [Basic terminology](doc:basic-terminology) | | find articles | [Discover articles](doc:discover-articles) | | read an article | [Read an article](doc:read-an-article) | | create or edit an article | [Create an article](doc:create-an-article) or [Edit an article](doc:edit-an-article) | | view or follow a profile | [View a profile](doc:view-a-profile) or [Follow an author](doc:follow-an-author) | | view saved favourites | [View favorited articles](doc:view-favorited-articles) | | change your settings | [Update your settings](doc:update-your-settings) | | understand an error or solve a common issue | [General error messages](doc:general-error-messages) or [Common issues and solutions](doc:common-issues-and-solutions) | Choose a destination, then review its topic. ## Before you look for an answer The FAQ is a directory, not a separate application screen. There is no dedicated FAQ or Help & Troubleshooting destination to open. The FAQ has no fields, controls, or FAQ-specific condition to operate. | Before you look for an answer… | Know this | |---|---| | look for the FAQ in the application | Start here | | expect a form | The FAQ has no fields to complete | | expect an FAQ action | The FAQ has no controls to select | When you know the FAQ has no form or action, match your question to a destination. ## Find the page that answers your question Use the question you are trying to answer, not the name of an application screen. **Prerequisites** You know the subject of your question. **Steps** 1. Select the link in the Go to column that matches your question. 2. Open the named page. 3. Follow that page's instructions for the task or issue. **Result:** You are on the page that owns the instructions for your question. ## Continue with the owning page The selected page contains the task, error, or setup guidance for its subject. **Prerequisites** You have selected an owning topic from the table. **Steps** 1. Open the owning page. 2. Follow its preparation steps before acting in the application. 3. Return to the owning page when you need its task result or troubleshooting guidance. **Result:** The relevant task, setup, or troubleshooting guidance is in front of you. # Update your settings ## Update your settings Use **Your Settings** to change the personal details held on your profile: your profile-picture URL, username, bio, email address, and optional password. After a successful update, the app takes you to the profile for the submitted username. | If you need to… | Go to | |---|---| | See what each setting does | [Review the settings fields](#review-the-settings-fields) | | Change your personal details | [Update your settings](#update-your-settings-1) | | Handle an optional password or sign-in branch | [Handle optional password and sign-in branches](#handle-optional-password-and-sign-in-branches) | | Resolve an update error | [When an update goes wrong](#when-an-update-goes-wrong) | | Continue to your profile after saving | [View a profile](doc:view-a-profile) | | Read the general error messages | [General error messages](doc:general-error-messages) | ## Before you start You must be signed in before you can open the settings screen. The form loads your current username, email, bio, and profile-picture URL when the screen opens. Your password is not loaded into the form. **Prerequisites** - Have an authenticated account. - Have the new values ready for any details you want to change. If you open the settings route while signed out, the app sends you to the sign-in route. ## Open Your Settings ### Open the settings screen **Prerequisites** - You are signed in. **Steps** 1. Open `/settings`. **Result:** The **Your Settings** screen opens with the settings form. ## Review the settings fields The settings form contains five personal details that you can review before submitting a change. The prompts appear inside the fields rather than as separate visible field labels. | Field | What to enter | |---|---| | **URL of profile picture** | The URL for the profile picture you want to use. | | **Your username** | The username you want associated with the profile. | | **Short bio about you** | A short description about you. | | **Email** | Your email address. | | **Password** | A new password when you want to change it. | None of the five fields has a required marker. **Password** starts empty rather than being copied from your current account. ## Update your settings Change the details you want to store, then submit the form. The update sends the username, email, bio, and profile-picture URL. It sends a password only when you enter one. **Prerequisites** - You are signed in and the settings form is open. **Steps** 1. Enter the new value in the relevant field. 2. Choose the password handling that matches your change in **Password**: | If you need to… | In **Password** | |---|---| | Keep your current password | Leave the field empty. | | Change your password | Enter the new value. | 3. Select **Update Settings**. **Result:** The app clears the current error list and routes you to the profile for the submitted username. ## Handle optional password and sign-in branches The **Password** choice determines whether a password is included in the update. Sign-in controls whether the settings screen opens. **Prerequisites** - Decide whether you are changing the password. **Steps** 1. Choose the path that matches your situation: | If you need to… | Do this | |---|---| | Keep your current password | Leave **Password** empty, then continue with the other settings. | | Change your password | Enter the new value in **Password**, then continue with the other settings. | | Open settings while signed out | Sign in when the app sends you to the sign-in route. | **Result:** An empty **Password** is omitted from the update, an entered password is included, and a signed-out attempt is sent to sign-in. ## When an update goes wrong The error list displays the values returned when an update produces errors. A network failure uses the message `Unable to connect to the server`. **Prerequisites** - The settings form is open. - You have entered the values you want to submit. **Steps** 1. Select **Update Settings**. 2. Read the message shown in the error list: | Message | Where it appears | |---|---| | A server-provided error value | The error list. | | `Unable to connect to the server` | The error list. | **Result:** The error list displays the server-provided error value or `Unable to connect to the server`. ## Leave Settings After you submit a successful update, the app takes you to the profile for the submitted username. You can also sign out from the settings screen. **Prerequisites** - The settings screen is open. **Steps** 1. Choose the path that matches what you want to do: | If you need to… | Select | |---|---| | Continue with the updated profile | Select **Update Settings**, then continue from the submitted username's profile. | | End your signed-in session | Select **Or click here to logout.** | **Result:** A successful update takes you to the submitted username's profile. Logging out clears the signed-in session and takes you to home. # View a profile After reading this page, you can open an author's profile, identify the author's public information, and choose **Follow**, **Unfollow**, or **Edit Profile Settings**, as applicable. ## View a profile A profile is an author's public information on the Profile route. Open it when you need to read the author's username and bio or choose whether to follow the author. | If you need to… | Go to | |---|---| | Open an author's profile | [Open a profile](#open-a-profile) | | Read the author's image, username, and bio | [Read the profile information](#read-the-profile-information) | | Follow or unfollow another author | [Follow or unfollow the author](#follow-or-unfollow-the-author) | | Change your own profile settings | [Update your settings](doc:update-your-settings) | | View articles an author has favorited | [View favorited articles](doc:view-favorited-articles) | | Follow an author as a separate task | [Follow an author](doc:follow-an-author) | ## Before you start You need the author's username or an author link that opens the Profile route. The profile must load before its image, username, bio, and available action appear. | Before you start | What to have or expect | |---|---| | Profile route | A route for the author's username. | | Profile request | The profile request starts when the page opens and when the route changes. | | Loaded profile | The profile information appears after the profile loads without an error. | | Profile error | The profile page can show a load-error message instead of the profile information. | Continue with [Open a profile](#open-a-profile). ## Open a profile Use this procedure when you have an author link or a Profile route for a username. The profile information appears after the profile loads. Prerequisites - You have an author link or the author's username. Steps 1. Open the author's Profile route. 2. Read the profile information when it appears. **Result:** The author's profile information is on screen. Continue with [Read the profile information](#read-the-profile-information). ## Read the profile information The profile information identifies the author without offering profile fields for editing on this route. | What you see | When it appears | What it tells you | |---|---|---| | Profile image | After the profile loads | The author's profile image, or the default avatar when no image is available. | | Username | After the profile loads | The author represented by the profile. | | Bio | After the profile loads | The author's profile description. | Profile editing belongs in [Update your settings](doc:update-your-settings). The Profile route provides the **Edit Profile Settings** link for the current user's profile rather than editable profile fields. Use the profile information to choose the applicable action. ## Follow or unfollow the author The available action depends on whether the profile is your own and whether you already follow the author. Use the branch that matches the profile you opened. | If the profile is… | Select… | What happens | |---|---|---| | Your own profile | **Edit Profile Settings** | The settings route opens. | | Another author's profile that you follow | **Unfollow** | The profile's unfollow action runs. | | Another author's profile that you do not follow | **Follow** | The profile's follow action runs. | Prerequisites - You have opened the profile and can see the profile information. Steps 1. Check the username on the profile to decide whether it is your own profile. 2. Select the control shown in the table above for the current profile and follow state. **Result:** Your own profile opens the settings route, or the other author's profile shows the follow action that applies to its current follow state. ## When the profile does not load The profile page uses one message while it waits for the profile request and another when the profile cannot be loaded. | What you see | What it means | What to do | |---|---|---| | `Loading profile...` | The profile information has not loaded yet. | Wait for the profile information or the load-error message. | | `This profile could not be loaded. Please try again later.` | The profile information is unavailable. | Open the Profile route again later. | The profile view does not provide profile-specific validation or confirmation messages. Follow and unfollow actions use the profile action rather than a profile form. When the profile information is available, continue with [Continue from a profile](#continue-from-a-profile). ## Continue from a profile After you read a profile, continue with the task that matches what you want to do. 1. To follow or unfollow the author, open [Follow an author](doc:follow-an-author). 2. To view the author's favorited articles, open [View favorited articles](doc:view-favorited-articles). 3. To change your own profile information, open [Update your settings](doc:update-your-settings). **Result:** You are at the page for the next profile task. # What is conduit ## What conduit is Conduit is a Vue 3 application that follows the RealWorld specification and provides a place to share knowledge. Its Home screen is the starting point for browsing article feeds and popular tags. | If you need to… | Go to | | --- | --- | | Understand the wider capabilities | [What can you do with conduit](./what-can-you-do-with-conduit) | | Check setup and backend requirements | [System requirements](./system-requirements) | | Browse articles from Home | [Discover articles](./discover-articles) | | Open and read an article | [Read an article](./read-an-article) | | Choose a feed | [Choose a feed](#choose-a-feed) | | Understand what appears in the feed | [Understand the Home results](#understand-the-home-results) | ## Before you choose a feed The Home screen changes its choices according to whether you are signed in. The personal feed is available when you are authenticated; the public banner appears when you are not. **Prerequisites** - To use **Your Feed**, sign in first. - To browse the public feed, open Home without signing in. ## Choose a feed Home offers **Global Feed**, **Your Feed**, and a tag feed. **Prerequisites** - To choose **Your Feed**, you are signed in. - To choose a tag feed, you have a tag value available from Home. **Steps** 1. Select one feed from the table. | If you want to… | Select | | --- | --- | | Browse all articles | **Global Feed** | | Browse articles from accounts you follow | **Your Feed** | | Browse articles associated with a tag | the tag value in the tag feed tab | **Result:** Home displays the selected feed. When the following feed has no articles, Home displays the message `Your feed is empty. Go to the Global Feed to discover articles.` Select **Go to the Global Feed** to return to the public feed. ## Understand the Home results Use the selected feed to inspect article previews and popular tags. An article preview links through its title, description, or **Read more...** text, while each popular tag value opens its tag feed. **Prerequisites** - You can access Home and have selected a feed. **Steps** 1. Open an article by selecting one of its links in the table. | If you want to… | Select | | --- | --- | | Open it from its heading or summary | the article title or description | | Open it from the direct link | **Read more...** | 2. Select a popular tag value to open that tag's feed. 3. Read `Loading articles...` while articles are loading. 4. If the loaded feed has no articles, read `No articles are here... yet.`. 5. If the feed has more than one page, select the number for the page you want. **Result:** Home shows the selected feed page, an article preview, or the applicable loading or empty-feed message. # Your first day in conduit ## Your first day in conduit Conduit gives you two ways to start: sign in with an existing account or create an account, then open a profile. The profile route uses a username and provides the person's profile details, article lists, and—depending on whose profile you open—profile actions. | If you need to… | Go to | | --- | --- | | Sign in with an existing account | [Sign in or create your account](#sign-in-or-create-your-account) | | Create an account | [Sign in or create your account](#sign-in-or-create-your-account) | | Reach a sign-in, sign-up, or profile screen | [Reach the sign-in, sign-up, and profile screens](#reach-the-sign-in-sign-up-and-profile-screens) | | Recognize the fields and actions on these screens | [Recognize the first-day screens](#recognize-the-first-day-screens) | | Open and use a profile | [Visit a profile](#visit-a-profile) | | Follow another author | [Follow an author](doc:follow-an-author) | | View favorited articles | [View favorited articles](doc:view-favorited-articles) | | Update your profile | [Update your settings](doc:update-your-settings) | | Solve a general application error | [General error messages](doc:general-error-messages) | | Find a solution to a common problem | [Common issues and solutions](doc:common-issues-and-solutions) | | Get support | [Getting help](doc:getting-help) | ## Before you start Have the details for the account path you want to use and the username of the profile you want to visit. The first-day screens use these fields: | Screen | Details to have ready | What the screen calls it | | --- | --- | --- | | Sign in | Your email address and password | **Email** and **Password** | | Sign up | The username, email address, and password for the new account | **Username**, **Email**, and **Password** | | Profile | The profile username | The username in the profile address | These fields have no required marker, so enter the information needed for the account request before submitting it. ## Reach the sign-in, sign-up, and profile screens The sign-in screen is at `/login`, the sign-up screen is at `/register`, and a profile uses the profile screen for ``. You can also move between the two account screens using their account links. Prerequisites - Know whether you are signing in or creating an account. - Have the account details listed in [Before you start](#before-you-start). - Have the profile username if you are opening a profile. Steps 1. Open `/login` to reach the sign-in screen. 2. Select **Need an account?** to open the sign-up screen. 3. Select **Have an account?** to return to the sign-in screen. 4. Open the profile screen for ``. **Result:** The selected sign-in, sign-up, or profile screen is open. ## Sign in or create your account Sign-in uses an existing account; sign-up sends the details for a new account. Prerequisites - For sign-in, have your email address and password. - For sign-up, have the username, email address, and password for the new account. Steps 1. Choose one account path and complete only that path: | Path | Complete path | | --- | --- | | Existing account | In **Email**, enter your email address. In **Password**, enter your password. Select **Sign in**. | | New account | In **Username**, enter the new account name. In **Email**, enter the account email address. In **Password**, enter the account password. Select **Sign up**. | **Result:** The account request is submitted from the selected account screen. ## Recognize the first-day screens The three first-day screens have distinct jobs: Login and Register collect account details, while Profile displays profile information and article views. | Screen | Fields or information | Controls and areas | | --- | --- | --- | | Login | **Email**, **Password** | **Need an account?**, **Sign in**, and an error area | | Register | **Username**, **Email**, **Password** | **Have an account?**, **Sign up**, and an error area | | Profile | Profile username, bio, and image | **Edit Profile Settings**, profile action, **My Articles**, and **Favorited Articles** | On Profile, the page first has a loading state with `Loading profile...`. If loading fails, it shows `This profile could not be loaded. Please try again later.`. When the profile is loaded, the profile area includes the username and bio, followed by the profile action and article tabs. The error area on Login and Register displays a dynamic entry in the form ` `, where the field name and message come from the account response. A network failure uses `Unable to connect to the server`. ## Visit a profile The profile page presents the selected username and bio, offers article views, and shows an action that depends on whether the profile is yours and whether you follow it. Prerequisites - Know the profile username. - Know the username in the profile address. Steps 1. Open the profile screen for ``. 2. Confirm that the profile area has loaded. 3. Read the displayed username and bio. 4. Select **My Articles** to view the profile's articles. 5. Select **Favorited Articles** to view the profile's favorited articles. 6. Choose the profile action that matches the profile state: | Profile state | Action | | --- | --- | | The profile belongs to you | Select **Edit Profile Settings**. | | The profile belongs to another person and you do not follow the profile | Select **Follow**. | | The profile belongs to another person and you follow the profile | Select **Unfollow**. | **Result:** The profile information and the selected article view are on screen, or the selected profile action has been started. ## Handle the first-day branches The first-day flow branches according to the account path, the redirect address, the profile owner, and the profile's follow state. | Situation | What to use or expect | | --- | --- | | You already have an account | Use the sign-in path. | | You need an account | Use the sign-up path. | | The route includes a same-application redirect beginning with `/` | Successful authentication returns to that path. | | No accepted redirect is present | Successful authentication returns to Home. | | The profile is yours | The **Edit Profile Settings** control appears. | | You follow the profile | Select **Unfollow** to stop following that profile. | | You do not follow the profile | Select **Follow** to follow that profile. | | The profile request fails after its retries | `This profile could not be loaded. Please try again later.` appears. | **Result:** The account path, redirect destination, profile action, and profile error state match the situation on screen. ## When the first-day flow goes wrong When account errors are present, Login and Register display an error list above the form. When account errors are present, each entry shows the field name followed by the first message for that field. A network failure uses `Unable to connect to the server`. Prerequisites - Be on the screen that displays the message. Steps 1. Choose the recovery action that matches the message: | If you see… | Do this | | --- | --- | | `Unable to connect to the server` | Check the connection, then retry the account request. | | A dynamic ` ` entry above Login | Correct the named account detail, then select **Sign in**. | | A dynamic ` ` entry above Register | Correct the named account detail, then select **Sign up**. | | `This profile could not be loaded. Please try again later.` | Check the profile username, then open the profile screen for ``. | | `Loading profile...` | Confirm that the profile area has loaded before choosing a profile action or article tab. | **Result:** The account request or profile screen is ready for the next action. For reusable message explanations, see [General error messages](doc:general-error-messages). For broader troubleshooting, see [Common issues and solutions](doc:common-issues-and-solutions). ## Continue after your first visit After account access and a first profile visit, continue with the task that matches what you want to do next. | If you want to… | Continue with… | | --- | --- | | Understand the rest of the application surface | [Understanding the interface](doc:understanding-the-interface) | | Move between the application's routes | [Navigation basics](doc:navigation-basics) | | Read a profile in detail | [View a profile](doc:view-a-profile) | | Follow or unfollow an author | [Follow an author](doc:follow-an-author) | | Browse favorited articles | [View favorited articles](doc:view-favorited-articles) | | Edit your profile information | [Update your settings](doc:update-your-settings) | | Discover or read articles | [Discover articles](doc:discover-articles) or [Read an article](doc:read-an-article) | # Follow an author ## Follow an author Following an author lets you manage your relationship with another author's profile from the Profile route. The author's username appears in the profile header beside the `Follow` or `Unfollow` control. | If you need to… | Go to | |---|---| | Open an author's profile | [View a profile](doc:view-a-profile) | | Follow or unfollow the author | Follow [the procedure below](#follow-or-unfollow-the-author). | | Change your own profile settings | [Update your settings](doc:update-your-settings) | ## Before you start The Profile page must load a profile for an author other than the signed-in user. The page loads the profile before it presents the profile content. The following state records whether you already follow that author and determines whether `Follow` or `Unfollow` appears. **Prerequisites** - You know which author's profile to open. - You are signed in before selecting `Follow`. The follow handler returns without sending the request when the user is not authenticated. - The profile belongs to another user. Your own profile presents **Edit Profile Settings** instead of the `Follow` or `Unfollow` controls in the profile header. When these conditions are met, open the author's profile. ## Open an author's profile An author's profile is the Profile page identified by the author's username. **Steps** 1. Follow [View a profile](doc:view-a-profile) to open the author's Profile page. **Result:** The author's profile page is open, with the author's username beside the `Follow` or `Unfollow` control in the profile header. ## Recognize the Follow or Unfollow controls The `Follow` or `Unfollow` control appears in the profile header beside the author's username and profile information. Use the label shown there to choose the action. | The profile's following state is… | The control label is… | |---|---| | `false` | `Follow` | | `true` | `Unfollow` | Use the label shown in the profile header in the next procedure. ## Follow or unfollow the author Use this procedure when the author's Profile page is open and you can identify whether `Follow` or `Unfollow` appears in the profile header. **Prerequisites** - The author's profile is loaded. - The profile belongs to another user. **Steps** 1. Select **Follow** or **Unfollow** according to the profile state. | If the profile state is… | Select… | |---|---| | `false` | **Follow** | | `true` | **Unfollow** | **Result:** After the request succeeds, the Profile page displays the refreshed profile data and the profile's current following state. ## Choose the action for the current state The profile state determines whether you follow an author, unfollow an author, or manage your own profile settings. **Prerequisites** - The Profile page has loaded the profile username. **Steps** 1. Choose the action that matches the profile you opened. | If you opened… | Select… | |---|---| | Another user's profile that you do not follow | **Follow** | | Another user's profile that you already follow | **Unfollow** | | Your own profile | **Edit Profile Settings** | **Result:** The Profile page shows the action for the profile's current state. If the action does not complete, use the guidance in the next section. ## When the action does not complete The Profile page uses a loading message while the profile is being fetched and a separate message when the profile cannot be loaded. If a follow or unfollow request fails, the profile stays as it was and no error message appears. | What you see | What to do | |---|---| | `Loading profile...` | Wait for the profile to finish loading. | | `This profile could not be loaded. Please try again later.` | Try opening the author's Profile page again later. | | The profile stays unchanged after selecting **Follow** or **Unfollow** | Select **Follow** or **Unfollow** again when the profile is available. | ## What to do next After you finish the follow decision, continue from the author's Profile page. For changes to your own profile, go to [Update your settings](doc:update-your-settings). # General error messages Use this page to identify a loading, empty, connection, or request-error message and choose the next action. ## Overview Loading messages mean that the screen is waiting for a request to finish. Empty messages mean that the request completed without matching articles. A connection message describes the current sign-in connection state. A request error is shown when a request returns error data for the screen to display. | If you need to… | Go to | | --- | --- | | Tell a loading message from an empty result or request error | [Identify the message and its condition](#identify-the-message-and-its-condition) | | Prepare the route and account details before interpreting a message | [Before you start](#before-you-start) | | Respond to a message after a request | [Respond to a loading or error message](#respond-to-a-loading-or-error-message) | | Continue with article discovery | [Discover articles](doc:discover-articles) | | Read an article | [Read an article](doc:read-an-article) | | Create or edit an article | [Create an article](doc:create-an-article) or [Edit an article](doc:edit-an-article) | | View or follow a profile | [View a profile](doc:view-a-profile) or [Follow an author](doc:follow-an-author) | | Update account settings | [Update your settings](doc:update-your-settings) | | Review broader remedies | [Common issues and solutions](doc:common-issues-and-solutions) | ## Before you start Before interpreting a message, know which route you opened, whether you are signed in, and which profile, article, tag, or feed you requested. The message belongs to that request context. | Have this ready | Why it matters | Where it applies | | --- | --- | --- | | The opened page | The same message text can belong to a profile, feed, or article surface. | The page you opened | | The profile name | The profile request uses it to load the profile. | The profile page | | The article | The article and editor requests use it to identify the article. | The article page or editor | | The tag name | The feed request uses it to filter the article list. | The tag feed | | Your sign-in state | The header shows `Connecting…` only for a signed-out user while authentication is unavailable. | Signed-out header | | The request you just submitted | Login, registration, settings, article, comment, and comment-deletion requests place their returned messages in the relevant error surface. | The form or article action you used | ## Identify the message and its condition Read the message first, then compare the screen state with the condition in the table. An empty result means the request finished and returned no matching articles; it is different from a list that is still loading. | What you see | Condition | What it tells you | | --- | --- | --- | | `Loading profile...` | The profile is not loaded and no profile error is present. | The profile request is still in progress. | | `This profile could not be loaded. Please try again later.` | The profile has a profile error. | The profile request reached its error state. | | `Loading articles...` | The article list is loading. | The article-list request is still in progress. | | `No articles are here... yet.` | The list is no longer loading and contains zero articles. | The request completed with no matching articles. | | `Your feed is empty.` | The following feed is not loading and contains zero articles. | The following feed has no articles to display. | | `Go to the Global Feed` | The following feed is empty. | The page offers a route to the global feed. | | `Connecting…` | Authentication is unavailable while the user is signed out. | The header is showing the connection state. | When a request is rejected, the error list shows the validation messages returned for that request. The list is used on login, registration, settings, article editing, comment entry, and comment deletion surfaces. A rejected request can place API validation messages in the error list. ## Respond to a loading or error message Use this procedure after a request leaves a loading state, shows a fixed message, or displays returned request errors. Prerequisites - Know the route and request that produced the message. - Have the profile username, article slug, tag, or account details required by that request. Steps 1. Read the visible message and match it to the condition in the table above. 2. If the message is `Loading profile...` or `Loading articles...`, wait for the request to finish before choosing an outcome. 3. If the following feed shows `Your feed is empty.`, select **Go to the Global Feed** to open the global feed. 4. Return to the screen where you submitted the request, correct the relevant fields, and submit the request again. | Request | Fields to review | Submit control | | --- | --- | --- | | Sign in | **Email**, **Password** | **Sign in** | | Sign up | **Username**, **Email**, **Password** | **Sign up** | | Update settings | **URL of profile picture**, **Your username**, **Short bio about you**, **Email**, **Password** | **Update Settings** | | Publish or edit an article | **Article Title**, **What's this article about?**, **Write your article (in markdown)**, **Enter tags** | **Publish Article** | | Post a comment | **Write a comment...** | **Post Comment** | 5. Choose the action for the message that remains on screen. | If you see | Action | | --- | --- | | `This profile could not be loaded. Please try again later.` | Return to the profile page and request the profile again. | | `No articles are here... yet.` | Change the feed or tag name to look for a different article set. | | `Connecting…` | Check the header again after the connection state changes; continue when `Connecting…` is no longer displayed. | **Result:** The screen shows the state for the request you selected, or the relevant feed, profile, or form is open for the next action. ## Know what happens next After a successful request, the affected screen clears its request errors or proceeds to the next screen. After a failed request, the screen keeps the returned messages in its error surface when that surface is available. | Request or load | Result after success | Result after failure | | --- | --- | --- | | Login or registration | The authentication store records the returned user and the form proceeds to its destination. | Returned errors appear in the form's error list. | | Settings update | The settings errors clear and the screen goes to the profile route. | Returned errors appear above the settings form. | | Article publish or edit | The screen goes to the article route for the returned article. | Returned errors appear above the editor. | | Profile load | The profile is displayed. | After the retry sequence, the profile error message appears and the profile is cleared. | | Article-list load | The article list leaves loading and displays articles or an empty-list message. | The list remains in its loading state. | | Follow or unfollow | The profile is replaced with the returned profile. | The profile stays unchanged and no error message is displayed. | | Article or comment fetch | The article or comments are loaded into the article page. | The article page has no dedicated fetch-error message. | For a request that has no dedicated message, continue from the screen state that remains visible. Use [Common issues and solutions](doc:common-issues-and-solutions) for broader remedies. Continue with [Update your settings](doc:update-your-settings), [Create an article](doc:create-an-article), [Edit an article](doc:edit-an-article), [View a profile](doc:view-a-profile), or [Read an article](doc:read-an-article) when that task owns the next action. # Read an article ## Read an article An article is a page with a title, body, and tags that you read before deciding whether to comment, follow its author, favorite it, or use an article action. Start with [Before you start](#before-you-start), then find and open the article. | If you need to… | Go to | | --- | --- | | Read the article and its tags | [Understand the reading surface](#understand-the-reading-surface) | | Add a comment or use a favorite or follow action | [Comment on and react to an article](#comment-on-and-react-to-an-article) | | Choose an author or reader action | [Handle author and reader actions](#handle-author-and-reader-actions) | | Continue to another article | [Discover articles](doc:discover-articles) | | Open the author's profile | [View a profile](doc:view-a-profile) | | See articles you favorited | [View favorited articles](doc:view-favorited-articles) | | Edit an article you authored | [Edit an article](doc:edit-an-article) | ## Before you start The Article route displays an existing article and its comments. Have the article route available, and sign in before you comment, follow an author, or favorite an article. **Prerequisites** - Know which existing article you want to open. - Have the article route available. - Sign in before commenting, following an author, or favoriting an article. When these prerequisites are in place, continue to [Find and open an article](#find-and-open-an-article). ## Find and open an article Use the article-discovery pages to choose an existing article, then open its Article route. The article and its comments load before the page is displayed. **Steps** 1. Open [Discover articles](doc:discover-articles). 2. Select the article you want to read. 3. Open the article route provided for the article. 4. If you are signed out, select **Sign in** to authenticate before commenting or using an interaction that requires sign-in. **Result:** The selected article opens with its title, body, tags, author information, and comments area on screen. Continue to [Understand the reading surface](#understand-the-reading-surface). ## Understand the reading surface The reading surface combines the article content with author information, tags, comments, and actions that depend on who you are. | Area | What you use it for | | --- | --- | | Title | Identify the article you opened. | | Body | Read the article content. | | Tags | Recognize the topics attached to the article. | | Author information | Open the author's profile and use article actions. | | Comment area | Read existing comments or enter a comment when signed in. | | Article actions | Edit or delete your article, or follow and favorite another author's article. | The Article route does not contain article-editing fields. When you are the author, select **Edit Article** to move to the editor. **Delete Article** is the author-only action for removing the article; use the editor page for editing. When you can locate the content and the controls you need, continue to [Comment on and react to an article](#comment-on-and-react-to-an-article). ## Comment on and react to an article A comment records your response below the article. Favorite and follow actions are available for an article you did not author; their labels change with the current favorite or follow state. **Prerequisites** - Be signed in to see the comment editor. - Open the article you want to discuss or react to. **Steps** 1. Choose the alternative that matches what you want to do: | If you need to… | Do this | | --- | --- | | Write a response | Enter it in **Write a comment...**, then select **Post Comment**. | | Add the article to your favorites | Select **Favorite Article**. | | Remove the article from your favorites | Select **Unfavorite Article**. | | Start following the author | Select **Follow **. | | Stop following the author | Select **Unfollow **. | | Sign in before using an interaction control | Select **Sign in** at the login screen. | **Result:** Your comment is added to the article's comments after a successful post, or the selected favorite or follow state is applied after a successful interaction. Continue to [Handle author and reader actions](#handle-author-and-reader-actions) when the action depends on your relationship to the article. ## Handle author and reader actions The article page shows different actions for the article author and for another reader. Your signed-in identity determines which set you see. | Your situation | Actions available | | --- | --- | | You are the article author | **Edit Article** and **Delete Article** | | You are signed in but are not the article author | **Follow **, **Unfollow **, **Favorite Article**, or **Unfavorite Article** | | You are signed out | **Sign in** and **sign up** in the comment area; sign-in is required for the interaction controls | **Steps** 1. Select the action that matches your situation: | If you need to… | Select | | --- | --- | | Change an article you authored | **Edit Article** | | Remove an article you authored | **Delete Article** | | Remove a comment you authored | The delete icon in that comment's footer | **Result:** The page presents the action set for your relationship to the article and comment. If an action fails, continue to [When something goes wrong](#when-something-goes-wrong). ## When something goes wrong | What you see | What it means | What to do | | --- | --- | --- | | `Unable to connect to the server` | The client could not connect to the server. | Check the connection and try the action again. | | `Server-provided field and message values` | The server returned validation or other API errors for the action. | Read the message beside its field and correct the requested value before trying again. | For broader error guidance, see [General error messages](doc:general-error-messages) and [Common issues and solutions](doc:common-issues-and-solutions). ## What to do next After reading or interacting with an article, choose the next destination that matches your work. **Steps** 1. Choose the next action: | If you need to… | Go to | | --- | --- | | Read another article | [Discover articles](doc:discover-articles) | | Review the author's other work | [View a profile](doc:view-a-profile) | | Review articles you favorited | [View favorited articles](doc:view-favorited-articles) | | Edit the article you authored | [Edit an article](doc:edit-an-article) | | Change your account settings | [Update your settings](doc:update-your-settings) | | Learn how following works | [Follow an author](doc:follow-an-author) | **Result:** You have a destination for the next article, profile, favorites, editing, settings, or following task. # Understanding the interface ## What the Conduit interface is Conduit is a RealWorld application built for browsing, creating, and managing articles. The interface connects the home feeds, article pages, comments, profiles, and article editor so you can move from finding an article to working with it. Use this page to recognize the main surfaces and choose where to continue: | If you need to… | Go to | |---|---| | Choose a feed, tag, article, profile, or destination | [Choose where to work](#choose-where-to-work) | | Read the Home surface | [Recognize the Home surface](#recognize-the-home-surface) | | Read or comment on an article | [Read an article](doc:read-an-article) | | Create a new article | [Create an article](doc:create-an-article) | | Change or remove an existing article | [Edit an article](doc:edit-an-article) | | Learn the product's visible terms | [Basic terminology](doc:basic-terminology) | | Follow an author or view profile work | [Personalizing your workspace](doc:personalizing-your-workspace) | | Resolve a general message | [General error messages](doc:general-error-messages) | ## Before you start The interface changes according to whether you are signed in and, on an article page, whether the article belongs to you. Have the article route available when you need to work with an existing article. Prerequisites | What to have ready | Why it matters | |---|---| | Your sign-in state | It determines whether the interface offers signed-out links or authenticated links. | | An existing article route | It lets you open the article page and its article actions. | | The task you want to complete | It tells you whether to use **Home**, an article, the editor, a profile, or **Settings**. | ## Choose where to work The shared header is the starting point for the main destinations. **Home** also gives you feed, tag, and article links, while the article surface can lead you to the editor or an author's profile. Steps 1. Choose the destination that matches your work: | If you want to… | Select or open | |---|---| | Return to the home feed | **Home** | | Read articles from authors you follow | **Your Feed** | | Browse all articles | **Global Feed** | | Filter articles by a tag | The tag value in the feed navigation | | Open a listed article | **Read more...** | | Write a new article | **New Article** | | Change your settings | **Settings** | | Open an author's profile | The author's username | | Sign in | **Sign in** | | Register | **Sign up** | 2. If the following feed has no articles, select **Go to the Global Feed** to browse the global list. **Result:** The selected feed, article, editor, profile, or settings surface is on screen. ## Recognize the Home surface The **Home** surface is where you choose a feed and browse article previews. The signed-out **Home** banner identifies Conduit with `conduit` and the text `A place to share your knowledge.`. Steps 1. Choose a feed: | If you want to… | Select | |---|---| | Read articles from authors you follow | **Your Feed** | | Browse all articles | **Global Feed** | 2. Select a tag value when you want a tag-filtered feed. 3. Use **Popular Tags** to identify the available tag choices. 4. Select **Read more...** in an article preview to open the article. 5. Select a page number when the article list has more than one page. The article list can show these states: | What appears | What it tells you | |---|---| | `Loading articles...` | Wait until the list finishes loading before assessing its contents. | | `No articles are here... yet.` | Choose another feed or tag to browse available articles. | | `Your feed is empty. Go to the Global Feed to discover articles.` | Select **Go to the Global Feed** to browse available articles. | **Result:** **Home** shows the feed or tag list you selected, the current article-list state, and any available article previews or page controls. ## Recognize article and editor surfaces An article surface is where you read an article, see its author and tags, and work with comments or article actions. The editor surface is where you enter an article's title, description, body, and tags before publishing it. Steps 1. Choose the surface that matches your task: | If you want to… | Use this surface | |---|---| | Read the article body and its tags | Article page | | Add a comment | **Write a comment...**, then **Post Comment** | | Enter a title | **Article Title** | | Enter the article description | **What's this article about?** | | Enter the article body | **Write your article (in markdown)** | | Add tags | **Enter tags** | | Publish or edit the article | **Publish Article** | | Change an existing article | **Edit Article** | | Remove an existing article | **Delete Article** | | Follow or unfollow the author | **Follow** or **Unfollow**, followed by the author value | | Add or remove a favorite | **Favorite Article** or **Unfavorite Article**, followed by the counter | 2. In the editor, enter tags in **Enter tags** and press Enter to add the tag. 3. Select **Publish Article** when the article fields are ready. 4. On an article page, select **Write a comment...**. 5. Select **Post Comment** to submit the comment. **Result:** The article page contains the article body, tags, comments, and article actions; the editor contains the article fields, tags, and publish control. ## Handle signed-in and signed-out variations Authentication and article ownership determine which controls appear. Use the control that is present on your screen rather than looking for an action on the other branch. Steps 1. Choose the branch that matches what you see: | If you see… | Continue with… | |---|---| | **Sign in** and **Sign up** in the header | Select **Sign in** or **Sign up** before using authenticated features. | | **New Article** and **Settings** in the header | Select the destination for the authenticated task. | | **Edit Article** and **Delete Article** on an article | Use the article-owner actions. | | **Follow** or **Unfollow** and a favorite action | Use the article interaction actions available for an article you do not modify. | | **Connecting…** | Wait for the authentication status to become available. | | `Loading articles...` | Wait for the article list to finish loading. | | `No articles are here... yet.` | Choose another feed or tag. | | An article action sends you to sign-in | Select **Sign in** before returning to the article work. | **Result:** You use the route and controls available for your sign-in state, article ownership, article state, and feed contents. ## When expected content is missing An empty feed and a loading list are normal interface states. An error list appears when an article or comment request supplies error keys and messages. | What appears | What to do | |---|---| | `Your feed is empty. Go to the Global Feed to discover articles.` | Select **Go to the Global Feed**. | | `Loading articles...` | Wait for the list to finish loading. | | `No articles are here... yet.` | Choose another feed or tag. | | An error list above the editor or comment form | Read the displayed field key and message, then correct the affected entry or use [General error messages](doc:general-error-messages). | The editor and comment forms can display error keys and messages returned for the request. **Result:** You can distinguish a normal empty or loading state from an error list and choose the next route for message-specific help. ## Continue with the task you chose Use the task page that matches the surface you selected: | Your next task | Continue with | |---|---| | Find articles in feeds, tags, and previews | [Discover articles](doc:discover-articles) | | Read an article, comment, favorite, or follow an author | [Read an article](doc:read-an-article) | | Publish a new article | [Create an article](doc:create-an-article) | | Change or remove an existing article | [Edit an article](doc:edit-an-article) | | Move between Home, tags, articles, and profiles | [Navigation basics](doc:navigation-basics) | | Understand visible product terms | [Basic terminology](doc:basic-terminology) | | Update profile or settings information | [Personalizing your workspace](doc:personalizing-your-workspace) | | Resolve a general message | [General error messages](doc:general-error-messages) | **Result:** You have the task page for the next action on the selected surface. # Who uses conduit Conduit is “A place to share your knowledge.” Use this page to decide whether you need to sign in with an existing account or create a new one. ## What conduit is for Conduit is a place to share your knowledge. When you arrive signed out, the home page presents this purpose and the **Global Feed** as the starting point for browsing. | If you need to… | Go to | |---|---| | Prepare information for sign-in or registration | [Before you start](#before-you-start) | | Reach the sign-in or registration screen | [Reach the sign-in or registration screen](#reach-the-sign-in-or-registration-screen) | | Locate fields and submit controls | [Understand the authentication screens](#understand-the-authentication-screens) | | Enter an existing account or create a new one | [Sign in or create an account](#sign-in-or-create-an-account) | | Choose between the two account paths | [Choose the account path that applies](#choose-the-account-path-that-applies) | | Understand an authentication error | [When authentication goes wrong](#when-authentication-goes-wrong) | | Continue after authentication | [Know what happens next](#know-what-happens-next) | | Complete the next getting-started task | [Your first day](doc:your-first-day) | | Learn about the wider interface | [Understanding the interface](doc:understanding-the-interface) | ## Before you start For sign in, have the account email address and password. For sign up, have the username, email address, and password for the new account. Prerequisites | Account path | Have ready | |---|---| | Existing account | The account email address and password | | New account | The username, email address, and password for the new account | The sign-in and registration screens do not show a required marker, so prepare the information for the path you choose before you begin. > [!NOTE] > The account path determines which fields you complete. ## Reach the sign-in or registration screen Use the sign-in screen for an existing account and the registration screen for a new account. The sign-in screen has **Need an account?**. The registration screen has **Have an account?**. Steps 1. Select **Need an account?** on the sign-in screen or **Have an account?** on the registration screen. | If you are on… | Select | |---|---| | The sign-in screen | **Need an account?** | | The registration screen | **Have an account?** | **Result:** The screen for your account path is open. ## Understand the authentication screens The sign-in screen collects an email address and password. The registration screen collects a username, email address, and password. | Screen | Field | Type | Required marker | |---|---|---|---| | Sign in | **Email** | Text | None shown | | Sign in | **Password** | Text | None shown | | Sign up | **Username** | Text | None shown | | Sign up | **Email** | Text | None shown | | Sign up | **Password** | Text | None shown | The sign-in form ends with **Sign in**. The registration form ends with **Sign up**. ## Sign in or create an account Use the form that matches your account situation. Prerequisites - Have the information listed in [Before you start](#before-you-start). - Have the matching authentication screen open. Steps 1. Complete the row that matches your account situation. | Account situation | Enter | Then select | |---|---|---| | Existing account | **Email** and **Password** | **Sign in** | | New account | **Username**, **Email**, and **Password** | **Sign up** | **Result:** Conduit processes the selected account action and follows the applicable destination. ## Choose the account path that applies When deciding which action applies, use the account situation that matches you. The sign-in screen does not ask for a username or password confirmation. The registration screen does not ask for password confirmation. After either action, Conduit returns you to the page you requested within Conduit. If you did not request a page, it opens the home page. Steps 1. Select the account path that matches your situation. | If you… | Select | Complete | |---|---|---| | Already have an account | **Sign in** | **Email** and **Password** | | Need an account | **Sign up** | **Username**, **Email**, and **Password** | **Result:** The account path that matches your situation is selected. ## When authentication goes wrong Authentication errors appear in the message list above the form fields. The message lists the error key followed by the first value returned for that key. The API supplies the returned error values, so use the text shown in the message list when deciding what to correct. ## Know what happens next After either action, Conduit returns you to the page you requested within Conduit. If you did not request a page, it opens the home page. Continue with [Your first day](doc:your-first-day) for the next getting-started task. For a broader catalogue of messages, see [General error messages](doc:general-error-messages). # Common issues and solutions ## Common issues and solutions Common issues and solutions help you diagnose problems signing in, opening an article, publishing, posting a comment, or connecting to the server. | If you need to… | Go to | |---|---| | Match a problem to the screen where it occurs | [Find the relevant screen](#find-the-relevant-screen) | | Identify the field, control, or message on screen | [Read the screen and message](#read-the-screen-and-message) | | Recover from a sign-in, publishing, comment, or connection error | [Choose and apply the recovery](#choose-and-apply-the-recovery) | | Continue after signing in or working with an article | [Continue after recovery](#continue-after-recovery) | | Read the complete error-message reference | [General error messages](doc:general-error-messages) | | Check application setup requirements | [System requirements](doc:system-requirements) | | Find help when the listed recovery does not resolve the problem | [Getting help](doc:getting-help) | The relevant application surfaces are Home, Login, Article, and Article editor. The routes for these surfaces are listed in [Find the relevant screen](#find-the-relevant-screen). ## Before you start The sign-in, article editor, and comment forms use the fields listed below. Error feedback appears in the error list after a request returns an error. | Screen | Fields to identify | What to use as your clue | |---|---|---| | Login | Email; Password | The field placeholder | | Article editor | Article Title; What's this article about?; Write your article (in markdown); Enter tags | The field placeholder | | Article comments | Write a comment... | The field placeholder | Use the exact text on screen when you compare an error with the recovery table. A server error can identify a field by key and provide one or more messages. A connectivity error uses `Unable to connect to the server`. **Prerequisites** - You know whether you are signing in, opening an article, editing an article, publishing, or posting a comment. - You can identify the screen from its route or its visible field placeholder. - You have the exact error text available when the problem is message-based. ## Find the relevant screen Use this procedure when you know what went wrong but are not sure which screen to open. **Steps** 1. Open the screen that matches the problem: | If the problem concerns… | Open… | |---|---| | the home surface or article discovery | Home at `/` | | signing in | Login at `/login` | | reading an article, comments, or article actions | the Article screen for the article you need | | creating an article | the Article editor for a new article | | editing a saved article | the Article editor for that article | **Result:** You are on the screen whose fields, controls, and message can identify the problem. ## Read the screen and message Use this procedure before choosing a recovery. **Prerequisites** - You are on the screen where the problem appears. **Steps** 1. Read the field placeholders and controls on the screen: | Screen | Identify… | |---|---| | Login | **Email**, **Password**, and **Sign in** | | Article editor | **Article Title**, **What's this article about?**, **Write your article (in markdown)**, **Enter tags**, and **Publish Article** | | Article comments | **Post Comment** and the `Write a comment...` field | 2. Match the visible condition to the next move: | What you see | What it means for your next move | |---|---| | **Need an account?** on Login | Open registration from the Login screen. | | **Sign in** and **sign up** in the article comment area | The article is being viewed without an authenticated session; use the matching link before adding a comment. | | **Edit Article** and **Delete Article** | The article is open for its current author. | | Follow and favorite controls | The article is open for someone who is not its author. | | The editor fields and **Publish Article** are disabled during publishing | Wait for the publishing request to finish before continuing. | | An error list with a field key and message | The API error object is rendered as a field key followed by each returned message. Use the field key to locate the affected input, then follow the message-specific recovery. | | `Unable to connect to the server` | Follow the connectivity branch in [Choose and apply the recovery](#choose-and-apply-the-recovery). | 3. On Login, use a redirect beginning with `/` to return to that same-app path after successful sign-in; without that safe redirect, sign-in returns you to Home. **Result:** You have identified the relevant field, control, or message. ## Choose and apply the recovery Use this procedure when an error has stopped the action you were taking. The first table chooses the branch by the reader's question. | If you need to… | Follow this branch | |---|---| | Sign in and the server cannot be reached | Connectivity | | Sign in and the error identifies a field | Login field error | | Publish an article and the error identifies a field | Publishing field error | | Post a comment and the error identifies a field | Comment field error | | Sign in after a rejected session | Authentication response | **Prerequisites** - You are on the screen where the error appears. - You can read the full error list, including its field key and message when provided. **Steps** 1. If the message is `Unable to connect to the server`, check the connection to the server before repeating the action. 2. If the error shows a field key and one or more messages, locate that field and correct the value according to the message. 3. After correcting the affected value, select the control for the action you were taking: | If the error appeared while… | Select… | |---|---| | signing in | **Sign in** | | publishing | **Publish Article** | | posting a comment | **Post Comment** | 4. Follow the authentication response that you received: | If authentication receives… | Action | |---|---| | a 4xx response | Wait for the logged-out view, then sign in again. | | a 5xx response or network failure | Restore the connection, then select **Sign in** again. | **Result:** The matching form is ready for another attempt, or the relevant sign-in branch is identified by the message on screen. ## Continue after recovery After a successful action, use the destination or cleared field to choose your next task. | After you… | Continue with… | |---|---| | Sign in successfully | The same safe same-app path, or Home when no safe redirect is present | | Publish an article successfully | [Create an article](doc:create-an-article) for another new article | | Open **Edit Article** | [Edit an article](doc:edit-an-article) | | Open an article for reading or comments | [Read an article](doc:read-an-article) | | Need the full error catalogue | [General error messages](doc:general-error-messages) | | Need further assistance | [Getting help](doc:getting-help) | **Prerequisites** - You have completed the action or reached the control that opens the next task. **Steps** 1. Choose the next action that matches what you completed: | After you… | Select or open… | |---|---| | publish an article | the article destination shown by the application | | submit a comment successfully | the article with the cleared comment field | | are the article author and want to continue editing | **Edit Article** | | need to remove your article | **Delete Article** | **Result:** You are on the article, editor, or Home destination that matches your next task. # 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. # Navigation basics ## Navigation basics Conduit uses routes to take you from the home feed to filtered articles, individual articles, and author profiles. A tag is a label that filters the article list. A profile is the page for one author and that author's articles. The article and profile routes include a value identifying the record you want to open. | If you need to… | Go to | | --- | --- | | Browse all articles | **Global Feed** on Home | | Browse articles for a tag | A tag in **Popular Tags** | | Read one article | **Read more...** in an article preview | | Open an author's profile | The author's username in article details | | See a profile's articles | **My Articles** | | See a profile's saved articles | **Favorited Articles** | | Understand the Home surface | [Understanding the interface](doc:understanding-the-interface) | | Find articles in detail | [Discover articles](doc:discover-articles) | | Read an article in detail | [Read an article](doc:read-an-article) | | View a profile in detail | [View a profile](doc:view-a-profile) | | View favorited articles in detail | [View favorited articles](doc:view-favorited-articles) | ## Before you start Home is the starting surface for global and tag-filtered browsing. Sign-in is required for **Your Feed**; if you open the following feed without being signed in, the application sends you to `/login`. Article and profile destinations need an existing article slug or profile username in the route. | Have this ready | Why it matters | | --- | --- | | Your sign-in state | It determines whether **Your Feed** and the authenticated header links appear. | | An existing article | Its route uses the article's slug. | | An existing profile | Its route uses the profile's username, with a favorites path for saved articles. | ## Find a destination The header is the quickest way to move between the main destinations. Its links change with your sign-in state. **Prerequisites** - Know whether you are signed in. **Steps** 1. In the table below, select the header destination that matches your need. | If you need to… | Select | | --- | --- | | Open Home | **conduit** or **Home** | | Open sign-in | **Sign in** | | Open registration | **Sign up** | | Create an article while signed in | **New Article** | | Open settings while signed in | **Settings** | | Open your profile while signed in | Your username | **Result:** The selected header destination is open. ## Understand Home and profile navigation Home is the place to choose an article feed or a tag; a profile is the place to switch between articles written by that profile and articles saved by that profile. | Surface | What it provides | | --- | --- | | **Your Feed** | Articles from profiles you follow; available when you are signed in. | | **Global Feed** | The general article feed. | | **Popular Tags** | Links that filter Home to the selected tag. | | **My Articles** | Articles associated with the profile. | | **Favorited Articles** | Articles saved by the profile. | | `Loading profile...` | The profile is still loading. | | `This profile could not be loaded. Please try again later.` | The profile could not be loaded. | | `Loading articles...` | The article list is still loading. | | `No articles are here... yet.` | The current article list has no articles. | ## Navigate to content Use the control that matches the content you want to reach. **Prerequisites** - For a specific article or profile, know which existing record you want to open. **Steps** 1. On Home, choose one destination from this table. | If you need to… | Select | | --- | --- | | Open the general article list | **Global Feed** | | Open articles from profiles you follow | **Your Feed** | | Filter the list by a tag | A tag under **Popular Tags** | | Open an article from the list | **Read more...** | 2. On an article, select the author's username to open that author's profile. 3. On a profile, select **My Articles**. 4. On a profile, select **Favorited Articles**. 5. On a list with more than one page, select the page number you need. **Result:** The selected feed, tag, article, profile, or profile article view is on screen. ## Choose the right navigation branch The available route depends on the question you are trying to answer and, for some destinations, your sign-in state. **Prerequisites** - Decide whether you need the general feed, followed profiles' articles, a tag filter, an article, or a profile view. **Steps** 1. In the table below, select the control that matches your need. | If you need to… | Select | | --- | --- | | Open the general list | **Global Feed** | | Open articles from profiles you follow | **Your Feed** | | Open a tag-filtered list | The tag under **Popular Tags** | | Open an article's full content | **Read more...** | | Open the author's profile | The author's username in the article details | | Open the profile's own articles | **My Articles** | | Open the profile's saved articles | **Favorited Articles** | **Result:** The screen matches the work you selected: a feed, a tag-filtered feed, an article, or a profile article view. ## When navigation content does not load The messages below tell you whether a profile or article list is still loading, empty, or unable to load. API validation text appears as returned for the current request. | What you see | What to do | | --- | --- | | `Loading profile...` | Wait for the profile to finish loading. | | `This profile could not be loaded. Please try again later.` | Try the profile again later. | | `Loading articles...` | Wait for the article list to finish loading. | | `No articles are here... yet.` | Choose another feed, tag, or profile tab. | | `Your feed is empty. Go to the Global Feed to discover articles.` | Select **Global Feed**. | | API validation text | Follow the instruction in the message returned for the current request. | ## Continue from the destination Navigation ends when the destination that owns the next task is open. **Prerequisites** - Have the relevant destination on screen. **Steps** 1. Continue according to the destination on screen. | If you are on… | Continue with | | --- | --- | | Home or a tag-filtered feed | [Discover articles](doc:discover-articles) | | An individual article | [Read an article](doc:read-an-article) | | A profile | [View a profile](doc:view-a-profile) | | **Favorited Articles** | [View favorited articles](doc:view-favorited-articles) | **Result:** You are on the page that documents the work available from the destination. # View favorited articles Favorited Articles is the profile list for articles that the profile has marked as favorites. Open it when you want to review those articles from the profile rather than browse the general article feed. | If you need to… | Go to | | --- | --- | | Prepare to open the list | [Before you start](#before-you-start) | | Reach a profile first | [View a profile](doc:view-a-profile) | | Read an article from the list | [Read an article](doc:read-an-article) | | Follow or unfollow the profile | [Follow an author](doc:follow-an-author) | | Change your profile settings | [Update your settings](doc:update-your-settings) | ## Before you start The profile page loads the profile before it shows the profile content and its article list. The favorites list opens from the profile's favorites tab and uses the profile username as its favorites filter. **Prerequisites** - Know the profile you want to open. - Open the profile route before selecting the favorites tab. - Wait for the profile to load before reviewing its articles. ## Find the favorites list Use the article tabs to switch between the profile's articles and its favorites. The profile's favorites tab opens the favorites view. **Steps** 1. Open the profile you want to review. 2. Select **Favorited Articles**. 3. Confirm that the favorites route is open in the browser address bar. **Result:** The profile's Favorited Articles list is on screen. ## Understand the favorites screen The profile header contains the profile image, username, and bio. An article preview contains an article title, description, tags, and a link to the article. Pagination provides a page-number control when the result count creates more than one page. | Area | What you can see or select | | --- | --- | | Profile header | The profile image, username, and bio | | Article list | Article title, description, tags, and **Read more...** | | Article tabs | **My Articles** and **Favorited Articles** | | Current-user action | **Edit Profile Settings** | | Other-profile action | **Follow ** or **Unfollow ** | | Page navigation | **** for each available page | The screen can also display these messages while the profile or article list is changing state: `Loading profile...`, `Loading articles...`, and `No articles are here... yet.` The profile header and article previews are ready for review when the list is on screen. ## Review the favorited articles The favorites list requests articles using the profile username as the `favorited` filter and shows five articles per page. **Prerequisites** - Open the profile's Favorited Articles list. **Steps** 1. Review each article preview in the list. 2. Select **Read more...** on an article you want to open. 3. If **** buttons are present, select the page you want to review. 4. Review the articles on the selected page. **Result:** The selected article opens from its preview, or the selected page of favorited articles is on screen. If a loading, empty, or profile-error message appears instead, use the matching response below. ## Handle loading and empty results The list has separate states for loading, an empty result, and a profile that cannot load. Use the message on screen to identify the state before continuing. **Prerequisites** - Open the profile's Favorited Articles list. **Steps** 1. Read the message on screen and follow the matching instruction. | Message | Action | | --- | --- | | `Loading profile...` | Wait for the profile content to appear. | | `Loading articles...` | Wait for the article list to finish loading. | | `No articles are here... yet.` | Select **My Articles** or open another profile. | | `This profile could not be loaded. Please try again later.` | Return to the profile later. | **Result:** The profile content or article list is on screen, or the matching message identifies the next response. The article-list request has no separate error message in this surface; its failure handler leaves the list in its loading state. ## When the list does not load Use the exact message on screen to choose the response. The profile error path displays `This profile could not be loaded. Please try again later.` The connectivity error is normalized as `Unable to connect to the server`, while the profile template displays the generic profile error message instead. **Prerequisites** - Open the profile's Favorited Articles list. **Steps** 1. Select the response in the table that matches the message on screen. | Message | Response | | --- | --- | | `This profile could not be loaded. Please try again later.` | Return to the profile later. | | `Unable to connect to the server` | Return to the profile later. | **Result:** You have the next action for the message that is on screen. ## Continue from the favorites list The profile screen also provides routes into the next task: an article preview leads to the article, **Edit Profile Settings** leads to settings, and the profile's follow controls lead to author following. **Steps** 1. Select the control for the next task. | If you want to… | Select | | --- | --- | | Read an article | **Read more...** | | Change profile settings | **Edit Profile Settings** | | Follow a profile | **Follow ** | | Stop following a profile | **Unfollow ** | **Result:** You are on the article, settings, or author-following task that matches the action you selected. # What can you do with conduit ## What you can do with conduit conduit is a frontend application for authentication, article creation and editing, routing, and pagination. Use it to find articles, read and discuss them, publish or revise your own articles, and work with author profiles. The main route families place those jobs in a simple flow: | If you need to… | Go to | |---|---| | Find articles or browse tags | [Discover articles](doc:discover-articles) | | Read an article, comment, follow its author, or favorite it | [Read an article](doc:read-an-article) | | Publish a new article | [Create an article](doc:create-an-article) | | Revise or remove an article you own | [Edit an article](doc:edit-an-article) | | View an author or follow them | [View a profile](doc:view-a-profile) or [Follow an author](doc:follow-an-author) | | See articles a profile has favorited | [View favorited articles](doc:view-favorited-articles) | | Change your profile settings | [Update your settings](doc:update-your-settings) | | Learn the shared screen vocabulary | [Understanding the interface](doc:understanding-the-interface) or [Basic terminology](doc:basic-terminology) | Choose the relevant destination after you have checked what you need before starting. ## What you need before you start Prerequisites - Sign in when you need **Your Feed**, the comment editor, or authenticated article and profile actions. - Have the article identifier for an article route and the username for a profile route. - Open the profile after it has loaded if you need profile details or profile actions. The available controls change with these conditions. On Home, **Your Feed** appears for an authenticated reader. On an article, the comment editor appears for an authenticated reader; otherwise, **Sign in** and **sign up** appear. A profile shows its loading or error message before its profile content is ready. With those conditions in mind, choose the destination that matches your work. ## Find the capability you need Use the route that matches the work you want to do. The application provides Home, article, article editing, profile, favorites, and settings destinations. Steps 1. Choose a destination for your work. | Your job | Continue with | |---|---| | Discover articles | [Discover articles](doc:discover-articles) | | Read or discuss an article | [Read an article](doc:read-an-article) | | Publish an article | [Create an article](doc:create-an-article) | | Revise an article | [Edit an article](doc:edit-an-article) | | View or follow an author | [View a profile](doc:view-a-profile) and [Follow an author](doc:follow-an-author) | | View favorited articles | [View favorited articles](doc:view-favorited-articles) | | Change account settings | [Update your settings](doc:update-your-settings) | **Result:** You are on the route or detailed page for the job you want to complete. ## Understand what each capability lets you do Use the selected surface for the reader job it supports. The controls below show what each capability provides. | Reader job | What you can use | |---|---| | Browse your followed authors' feed | **Your Feed** | | Browse the complete article feed | **Global Feed** | | Leave an empty following feed | **Go to the Global Feed** | | Read and comment on an article | **Write a comment...** and **Post Comment** | | Sign in or register before commenting | **Sign in** and **sign up** | | Publish an article | **Article Title**, **What's this article about?**, **Write your article (in markdown)**, **Enter tags**, and **Publish Article** | | Edit or remove your own article | [Edit an article](doc:edit-an-article) | | Follow or unfollow an author | [Follow an author](doc:follow-an-author) | | Favorite or unfavorite an article | [Read an article](doc:read-an-article) | | Open your own profile settings | **Edit Profile Settings** | | Browse a profile's authored articles | **My Articles** | | Browse a profile's favorited articles | **Favorited Articles** | Use this map to choose the detailed instructions for the job you want to complete. ## Choose the task instructions Choose the detailed procedure that matches your intended result. Steps 1. Choose one destination from this table. | If you want to… | Open | |---|---| | Discover articles | [Discover articles](doc:discover-articles) | | Read, comment on, favorite, or follow from an article | [Read an article](doc:read-an-article) | | Publish | [Create an article](doc:create-an-article) | | Revise or remove an article | [Edit an article](doc:edit-an-article) | | View a profile | [View a profile](doc:view-a-profile) | | Follow or unfollow an author | [Follow an author](doc:follow-an-author) | | View favorited articles | [View favorited articles](doc:view-favorited-articles) | 2. Open the destination page. **Result:** The detailed page for your chosen article or profile task is open. ## When a capability does not load or respond The screen can show a loading message, a profile-load message, an empty following feed, or an error list. Match what you see to the action you were taking. | What you see | What to do | |---|---| | `Loading profile...` | Wait for the profile to finish loading. | | `This profile could not be loaded. Please try again later.` | Return to the profile later or use [Common issues and solutions](doc:common-issues-and-solutions). | | `Your feed is empty.` | Select **Go to the Global Feed** to continue browsing. | | ``Dynamic values from the `errors` object; no fixed message text is declared.`` | Use [General error messages](doc:general-error-messages) or [Getting help](doc:getting-help) for the error text shown in the list. | After you match the message, continue with the detailed instructions for that problem or task. ## Continue to the detailed instructions Continue with the destination that matches your next action. | After you need to… | Continue with | |---|---| | Understand the product and its purpose | [What is conduit](doc:what-is-conduit) | | Set up the supported environment | [System requirements](doc:system-requirements) | | Learn the shared interface | [Understanding the interface](doc:understanding-the-interface) | | Learn navigation | [Navigation basics](doc:navigation-basics) | | Personalize your workspace | [Personalizing your workspace](doc:personalizing-your-workspace) | | Learn product terms | [Basic terminology](doc:basic-terminology) | | Get help | [Getting help](doc:getting-help) | | Find answers to common questions | [FAQ](doc:faq) | | Resolve general errors | [General error messages](doc:general-error-messages) | | Resolve a recurring problem | [Common issues and solutions](doc:common-issues-and-solutions) | # Edit an article An article record is the saved article page. Its editor is the article editing page. An existing article is one you open and change in the article editor. Use this page when you need to update its title, description, body, or tags, or when you need to remove it as its author. For a new article, see [Create an article](doc:create-an-article). | If you need to… | Go to | |---|---| | Open an existing article | [Find and open the article](#find-and-open-the-article) | | Identify the fields and tag controls | [Understand the editor](#understand-the-editor) | | Change and submit an article | [Edit and save the article](#edit-and-save-the-article) | | Remove an article | [Delete the article](#delete-the-article) | | Read an article after editing | [Read an article](doc:read-an-article) | | Handle general error messages | [General error messages](doc:general-error-messages) | | Resolve a common issue | [Common issues and solutions](doc:common-issues-and-solutions) | ## Before you start Prerequisites - Have an authenticated account. - Have an existing article to edit. - Be the article's author to see **Edit Article** and **Delete Article**. - Open the saved article record before starting the edit. ## Find and open the article Prerequisites - Meet the prerequisites above. Steps 1. Open the existing article record. 2. Select **Edit Article**. The article editor opens for that article. **Result:** The existing article is open in its editor. ## Understand the editor The four reader-facing strings in the editor are placeholders. | What you need to change | Control | What you use it for | |---|---|---| | Title | **Article Title** | Change the article title. | | Description | **What's this article about?** | Change the article description. | | Body | **Write your article (in markdown)** | Change the article body. | | Tags | **Enter tags** | Add a tag by entering it and pressing Enter. | | Tags | close icon beside a tag | Remove that tag. | | Submission | **Publish Article** | Submit the existing article edit. | While the submission is in progress, the editor fields and **Publish Article** are disabled. **Result:** You can identify each field, the tag actions, and the control that submits the edit. ## Edit and save the article Editing an article changes the existing values in the article editor and submits them through **Publish Article**. Prerequisites - Meet the prerequisites above and have the article editor open. Steps 1. Enter the new title in **Article Title**. 2. Enter the new description in **What's this article about?**. 3. Enter the article text in **Write your article (in markdown)**. 4. Use one of these tag actions: | If you need to… | Action | |---|---| | Add a tag | Enter the tag in **Enter tags**, then press Enter. | | Remove a tag | Select the close icon beside that tag. | 5. Select **Publish Article**. After a successful edit request, the application opens the returned article. **Result:** The edited article is displayed on its article page. ## Delete the article **Delete Article** is the author-only action that removes the article and takes you away from its article page after the delete request succeeds. Prerequisites - Meet the prerequisites above and have the article record open. Steps 1. Select **Delete Article** in the article actions. After the delete request succeeds, the application returns to the Home page. **Result:** The Home page is displayed after the article is deleted. ## When the edit does not work The error list shows each returned error key and message value verbatim. The fields have no visible required or pattern rule. | What appears | What it means | What to do | |---|---|---| | The returned error key and message value | The edit request returned an error. | Read the displayed entry and correct the related article value before selecting **Publish Article** again. | ## After editing or deleting After a successful edit, the application opens the returned article. After a successful deletion, the application returns to the Home page. To continue reading the article, open [Read an article](doc:read-an-article). # Personalizing your workspace Your workspace has three related surfaces: **Your Settings** is where you maintain your account details, Profile is where you view a person's information and articles, and **Favorited Articles** is the profile view for articles that person has favorited. | If you need to… | Go to | |---|---| | Change your account details | [Update your settings](#update-your-settings) | | View a person's profile and articles | [View your profile and favorited articles](#view-your-profile-and-favorited-articles) or [View a profile](doc:view-a-profile) | | View favorited articles | [View your profile and favorited articles](#view-your-profile-and-favorited-articles) or [View favorited articles](doc:view-favorited-articles) | | Follow or unfollow another person | [Follow an author](doc:follow-an-author) | **Result:** You can choose the surface that matches the account or article task you want to complete. ## Before you start **Prerequisites** - Sign in before opening **Your Settings**; the surface requires authentication. - Have the values ready for the fields in the following table. | Field | What to have ready | |---|---| | **URL of profile picture** | The picture URL you want to use | | **Your username** | The username you want displayed | | **Short bio about you** | The short description you want displayed | | **Email** | The email address for the account | | **Password** | A new password only when you want to change it | **Result:** You have signed in and have the account values needed for the Settings fields. ## Find your settings and profile 1. Open the surface that matches your task. | If you need to… | Open or select… | |---|---| | Change account details | **Your Settings** | | View a person's profile | The profile for that username | | View that person's favorited articles | **Favorited Articles** | **Result:** You are on the Settings surface, a profile, or that profile's **Favorited Articles** view. ## Understand the surfaces The Settings surface contains five account fields, an update action, and a logout action. A profile contains the person's picture, username, biography, article tabs, and a profile action whose label depends on whose profile you opened. | Surface | What you can use | |---|---| | Settings | **URL of profile picture**, **Your username**, **Short bio about you**, **Email**, **Password**, and **Update Settings** | | Profile | **Edit Profile Settings** for your own profile | | Profile | The follow or unfollow action for another profile | | Article lists | **My Articles** and **Favorited Articles** | | Settings | **Or click here to logout.** | When a profile is loading, it displays `Loading profile...`. When loading ends in an error, it displays `This profile could not be loaded. Please try again later.`. When you select **Favorited Articles**, the article list uses that username as its favorites filter. On the profile's article view, the article list uses that username as its author filter. **Result:** You can identify the fields, tabs, messages, and profile action available on the surface you opened. ## Update your settings Change the account details shown on your profile from **Your Settings**. **Prerequisites** - You are signed in. - You know which account values you want to change. **Steps** 1. Open **Your Settings**. 2. Review or change the fields in the form. | If you need to change… | Enter the value in… | |---|---| | Your profile picture | **URL of profile picture** | | Your displayed name | **Your username** | | Your biography | **Short bio about you** | | Your account email | **Email** | | Your password | **Password** | 3. Select **Update Settings**. 4. Review the profile page. **Result:** A successful update clears the current validation list and opens the profile for the username you submitted. If the service returns validation errors, the Settings surface displays the returned field and message values in a validation list. ## View your profile and favorited articles Use the profile to view a person's identity details and article lists. **My Articles** lists articles associated with the profile's username; **Favorited Articles** lists articles that username has favorited. **Prerequisites** - You have a profile username to open. **Steps** 1. Open the profile for the username you want to view. 2. Check the profile username and biography to confirm that you opened the intended profile. 3. Select the tab that matches what you want to view. | If you want to view… | Select… | |---|---| | Articles associated with the profile | **My Articles** | | Articles favorited by the profile | **Favorited Articles** | **Result:** The selected tab is active, and the article list shows the corresponding author or favorites view. The list is configured for five articles per page. ## Handle profile branches and errors The profile surface chooses what you can do from the profile state and whose profile you opened. | What you encounter | What appears | |---|---| | The profile request is still in progress | `Loading profile...` | | The profile request ends unsuccessfully | `This profile could not be loaded. Please try again later.` | | The profile belongs to you | **Edit Profile Settings** | | The profile belongs to someone else and you follow that person | The unfollow action | | The profile belongs to someone else and you do not follow that person | The follow action | | You open the favorites route | The article list is filtered by the profile username's favorites | | You open the profile route | The article list is filtered by the profile username as author | Selecting the follow or unfollow action updates the profile when the operation succeeds. If either operation fails, the profile remains unchanged. **Result:** You can distinguish the profile state and choose the available profile action without treating an unavailable branch as another control. ## When it goes wrong Use the message on screen to identify the branch you are in, then take the matching action. | What you see | What it means | What to do | |---|---|---| | `Loading profile...` | The profile content has not loaded yet. | Wait for the profile request to finish. | | `This profile could not be loaded. Please try again later.` | The profile could not be loaded. | Try opening the profile again later. | | A validation list after selecting **Update Settings** | The service returned account-validation errors. | Read the listed field and message, correct the corresponding value, and select **Update Settings** again. | **Result:** You know which profile message or validation response to act on. ## Know what to do next After a successful Settings update, the profile for the submitted username opens. From there, use **My Articles** for that profile's articles or **Favorited Articles** for its favorited articles. For detailed follow-on tasks, continue to [Update your settings](doc:update-your-settings), [View a profile](doc:view-a-profile), [Follow an author](doc:follow-an-author), or [View favorited articles](doc:view-favorited-articles). # System requirements ## What you need to run Conduit Conduit is a Vue 3 application. Pinia stores application state, Vue Router handles navigation, and Vite serves and builds the application. Bun installs packages and runs project commands. Playwright runs the end-to-end browser tests. `marked` renders Markdown, DOMPurify sanitises rendered content, and `date-fns` handles dates. The application uses a thin `fetch` wrapper for API requests. Prepare the project locally before opening Conduit. | If you need to… | Go to | |---|---| | Prepare the repository | Before you start | | Install packages and run the application | Install and run the application | | Select a backend URL | Point Conduit to a backend | | Run browser tests or code checks | Test and check the project | | Understand what Conduit does | What is conduit; What can you do with conduit | | Get help with a problem | Getting help | ## Before you start Before you run a project command, have a clone that includes the `realworld` git submodule. This submodule supplies the specification and test suite, and the application imports its theme from it. Prerequisites - Access to the project repository. - The `realworld` git submodule available in the clone. Steps 1. Prepare the repository using the command that matches its current state: | If you need to… | Run | |---|---| | Clone the repository with its submodules | `git clone --recurse-submodules https://github.com/realworld-apps/vue-realworld-example-app` | | Initialise the submodule in an existing clone | `git submodule update --init` | **Result:** The repository and its `realworld` submodule are available for installing dependencies. ## Install and run the application Use this procedure to install the project, start its development server, or create a production build for preview. Prerequisites - The repository and `realworld` submodule are available. Steps 1. Install the project dependencies by running: ```bash bun install ``` 2. Choose the way you want to run the project: | If you need to… | Run | |---|---| | Develop with hot reload | `bun run serve` | | Create a production build | `bun run build` | | Preview the production build | `bun run preview` | 3. Open `http://localhost:8080` after starting the development server. **Result:** The development server is available at `http://localhost:8080`, or the production build is ready for preview and backend configuration. ## Point Conduit to a backend Conduit sends its API requests to a RealWorld backend. By default, it uses `https://api.realworld.show/api`; use `VITE_API_URL` when you need to point the application to another spec-compliant backend. Prerequisites - A backend URL to use when you are not using the default. Steps 1. Choose where to set the backend URL: | If you need to… | Set | |---|---| | Use the default backend | Leave `VITE_API_URL` unset | | Use another backend for a shell command | `VITE_API_URL=http://localhost:8000/api` before `bun run serve` | | Use another backend for local development | Set `VITE_API_URL` in `.env.local` | 2. Start the application with `bun run serve`. **Result:** The application starts with the selected backend URL and is ready for project checks. ## Test and check the project Run the browser suite after setup, then use linting and formatting checks before sharing changes. Prerequisites - The project dependencies are installed. - The development server can be started by the Playwright configuration. Steps 1. Install the Chromium browser and its dependencies by running: ```bash bunx playwright install --with-deps chromium ``` 2. Run the end-to-end test suite by running: ```bash bun run test ``` 3. Check the source with ESLint by running: ```bash bun run lint ``` 4. Format the source with Prettier by running: ```bash bun run format ``` **Result:** The browser, end-to-end, lint, and formatting commands have been run for the project. # Basic terminology ## Basic terminology Conduit uses **Feed**, **Article**, **Profile**, and **Settings** to name the places where you find content, read or write it, view an author, and change profile information. The same terms identify links, lists, fields, and actions across the application. | If you need to… | Go to | |---|---| | Choose between **Your Feed** and **Global Feed** | [Find terms in feeds, articles, and profiles](#find-terms-in-feeds-articles-and-profiles) | | Read or comment on an article | [Read an article](doc:read-an-article) | | Enter article information | [Use the editor and settings terms](#use-the-editor-and-settings-terms) and [Create an article](doc:create-an-article) | | View an author or their article lists | [View a profile](doc:view-a-profile) | | Change profile information | [Update your settings](doc:update-your-settings) | | Interpret a loading, empty, or error message | [Recognize messages and know what comes next](#recognize-messages-and-know-what-comes-next) and [General error messages](doc:general-error-messages) | ## Before you start The terms you see depend on whether you are signed in, whose profile you are viewing, and which profile route you open. **Prerequisites** - Know whether you are signed in before looking for **Your Feed**, comment controls, or profile actions. - To see **Your Feed**, be signed in. **Global Feed** is available without that condition. - To see **Edit Profile Settings**, open your own profile. Another person's profile offers **Follow** or **Unfollow** according to the following state. - To see **Favorited Articles**, open the profile's favorites route. The other profile route uses **My Articles**. The Editor and Settings fields appear without a required marker. ## Find terms in feeds, articles, and profiles Use Home to choose a feed, an Article page to work with its author actions and comments, and a Profile page to choose an author's article list. **Prerequisites** - Be signed in when you need **Your Feed**, comments, or a profile action that requires authentication. - Know whether you want the global list, the following list, an article, or an author's profile. **Steps** 1. Choose the feed that matches what you need: | If you need to… | Select | |---|---| | Read articles from the people you follow | **Your Feed** | | Read the global article list | **Global Feed** | 2. On an Article page, use the available article action for the task you need: | If you need to… | Select | |---|---| | Change an article you can modify | **Edit Article** | | Remove an article you can modify | **Delete Article** | | Change whether you follow the author | **Follow** or **Unfollow** | | Change whether the article is in your favorites | **Favorite Article** or **Unfavorite Article** | | Add a comment while signed in | **Post Comment** | 3. Choose the profile list that matches what you need: | If you need to… | Select | |---|---| | Read the author's articles | **My Articles** | | Read the profile's favorited articles | **Favorited Articles** | **Result:** The selected feed, article action, comment action, or profile article list is on screen. ## Use the editor and settings terms Use the Editor to enter an article's title, description, body, and tags. **Prerequisites** - Open the Editor when you are creating or changing an article. - Open Settings when you are changing your profile information. **Steps** 1. In the Editor, enter the article information in the fields below. | Information you need to enter | Field term | |---|---| | Article name | **Article Title** | | Short description | **What's this article about?** | | Article body | **Write your article (in markdown)** | | Article tags | **Enter tags** | 2. Select **Publish Article** to publish a new article or finish an edit. 3. In Settings, enter profile information in the fields below. | Information you need to change | Field term | |---|---| | Profile picture address | **URL of profile picture** | | Profile name | **Your username** | | Profile biography | **Short bio about you** | | Account email | **Email** | | Account password | **Password** | 4. Select **Update Settings** to save the profile fields. 5. Select **Or click here to logout.** to log out and return to Home. **Result:** The Editor takes you to the article after publishing or editing. Settings takes you to the profile after a successful update, or Home after logout. ## Recognize messages and know what comes next These messages tell you whether an article list is loading, empty, or ready, whether a profile is loading or unavailable, and whether comments require sign-in. | What you see | What it means | Next action | |---|---|---| | `Your feed is empty. Go to the Global Feed to discover articles.` | The following feed has no articles. | Select **Go to the Global Feed**. | | `Loading articles...` | The article list is loading. | Wait for the list to finish loading. | | `No articles are here... yet.` | The current article list has no articles. | Choose another feed, profile list, or tag. | | `Read more...` | An article preview offers a link to the full article. | Select **Read more...**. | | `Loading profile...` | The profile information is loading. | Wait for the profile to load. | | `This profile could not be loaded. Please try again later.` | The profile information is unavailable right now. | Try opening the profile again later. | | `Sign in or sign up to add comments on this article.` | The comment editor is not available until you sign in or register. | Select **Sign in** or **sign up**. | After a successful article publish or edit, the Article page opens. After a successful settings update, the Profile page opens. Logging out returns you to Home. **Result:** You can match the message on screen to the next available action. # Getting help ## Getting help When you need answers about Conduit or help with a common problem, choose the destination that matches your question. Questions, error messages, and common issues are handled in separate help and troubleshooting pages rather than in an in-app help screen. | If you need to… | Go to | | --- | --- | | Find answers to questions about using the application | [FAQ](doc:faq) | | Match an error or loading message to its explanation | [General error messages](doc:general-error-messages) | | Work through a recurring problem | [Common issues and solutions](doc:common-issues-and-solutions) | For general questions about using Conduit, open the [FAQ](doc:faq). Open [General error messages](doc:general-error-messages) for an error or loading message. For a recurring problem, open [Common issues and solutions](doc:common-issues-and-solutions). ## Before you look for help Use the three reference pages in the table above for questions, messages, and recurring problems. Choose one of the three reference pages in the table to continue. ## Choose a help destination Use this procedure when you need to decide which reference page to open. Prerequisites You know whether you are looking for a general answer, an explanation of a message, or a solution to a recurring problem. Steps 1. Select the reference page that matches your question in the orientation table above. **Result:** The reference page for your question or problem is open.