# Create a project

## Create a project

A project is the documentation workspace you create from a repository or without a repository.
Use the project-creation wizard to choose the documentation types you want to produce.

| If you need to… | Go to |
|---|---|
| Open the creation surface | [Open the project-creation surface](#open-the-project-creation-surface) |
| Check the fields and wizard stages | [Recognize the wizard stages and fields](#recognize-the-wizard-stages-and-fields) |
| Enter details and choose documentation | [Enter project details and choose documentation](#enter-project-details-and-choose-documentation) |
| Choose a repository route or provider | [Choose repository access](#choose-repository-access) |
| Resolve a message or blocked action | [When creation or generation goes wrong](#when-creation-or-generation-goes-wrong) |
| Continue after generation | [Continue after the project is created](#continue-after-the-project-is-created) |
| Understand the project area | [Projects overview](doc:projects-overview) |
| Configure a created project | [Manage project settings](doc:manage-project-settings) |
| Follow generation stages | [Documentation generation lifecycle](doc:documentation-generation-lifecycle) |

![The initial project-creation screen with the repository choices and the option to continue without a repository.](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c48f3c9b00d7186b6bb9f817e8dd6f87.png)

## Before you start

**Prerequisites**

Have the information that matches the route you plan to use.

| Have this ready | Why it matters here |
|---|---|
| A GitHub, GitLab, or Bitbucket repository URL | The wizard accepts these repository types on the initial screen. |
| A project name and URL-friendly slug | The project details route requires both values before you continue. |
| The branch to use | A repository route requires a non-blank branch before you continue. |
| Provider or repository credentials | The Authentication tab can require **Username / Token Name** and **Password / Access Token** when repository access needs authentication. |
| Optional source paths | **Frontend Path** and **Backend Path** help describe the codebase structure. |
| Optional screenshot details | **Site URL**, **Login URL**, **Site Email**, and **Site Password** configure screenshot access. |
| At least one enabled documentation type | **Generate Documentation →** is unavailable until a type is selected. |

## Open the project-creation surface

Use this procedure when you are starting a new project from the Projects area.

**Prerequisites**

- You know whether you are using a repository or continuing without one.

**Steps**

1. Open **Projects**.
2. Select **New project**.
3. On the new-project screen, review the repository choices and choose the route that matches your starting point:

| If you want to… | Select |
|---|---|
| Start with a repository URL | **Get Started →** |
| Use a connected GitHub account | **GitHubConnected** |
| Use GitLab | **GitLab** |
| Use Bitbucket | **Bitbucket** |
| Continue without a repository | **Create without a repository** |

Opening the new-project route starts a fresh wizard and clears the selected project and saved wizard state.

**Result:** The wizard remains on the initial screen until you select a repository route or **Create without a repository**.

## Recognize the wizard stages and fields

The project-creation wizard is a sequence of repository access, project details, documentation types, and generation stages.
The fields and actions change with the route you choose.

| Stage or route | What you can use there |
|---|---|
| Initial repository choice | **Get Started →**, **GitHubConnected**, **GitLab**, **Bitbucket**, or **Create without a repository** |
| Authentication | **Username / Token Name**, **Password / Access Token**, **Test Connection**, and provider OAuth controls when authentication is required |
| Configuration | **Project Name**, **Slug**, **Branch**, **Frontend Path**, **Backend Path**, **Site URL**, **Login URL**, **Site Email**, and **Site Password** |
| Branch picker | Branch search, **Cancel**, and **Select Branch** |
| Repository browser | Repository search, repository selection, filters, **Retry**, **Back**, and **Continue →** |
| Documentation types | **Select All**, **Deselect All**, **User Guides**, **Technical Docs**, **API Reference**, **Support Bot**, **Back**, and **Generate Documentation →** |
| Generation | Progress, generation status, and completion destinations such as **Go to Project**, **View Documentation**, and **View Technical Docs** |

The Configuration tab is always available. Authentication is the repository-access step, and its tab appears when a repository needs authentication.
When a repository is present, **Branch** must contain a value. The project details route also requires non-blank **Project Name** and **Slug** before **Continue** becomes available.

The live initial screen has no labelled form fields or password field. Begin with the repository choice, then use the fields that appear on the route you select.

**Result:** You know which stage you are entering and which fields and actions belong to that stage.

## Enter project details and choose documentation

Use this procedure after you have chosen a repository route, or after you have selected **Create without a repository**.

**Prerequisites**

- You have a project name and slug.
- If you are using a repository, you have selected or entered its branch.

**Steps**

1. In **Project Name**, enter the name for the project when the field is shown.
2. In **Slug**, enter the URL-friendly identifier when the field is shown.
3. In **Branch**, enter the branch to use when a repository is present.
4. Enter optional project details:

   | If you want to provide… | Enter it in… |
   |---|---|
   | A frontend source location | **Frontend Path** |
   | A backend source location | **Backend Path** |
   | The application address | **Site URL** |
   | The sign-in address | **Login URL** |
   | The sign-in email | **Site Email** |
   | The sign-in password | **Site Password** |

5. Select **Continue →**.
6. Choose documentation types:

| Choice | Status and action |
|---|---|
| **User Guides** | Enabled; select it to include user guides. |
| **Technical Docs** | Enabled; select it to include technical documentation. |
| **API Reference** | Enabled; select it to include an API reference. |
| **Support Bot** | Unavailable; it is shown with **Soon**. |
| All enabled types | Select **Select All**. |
| All currently selected enabled types | Select **Deselect All**. |

7. Select **Generate Documentation →**.

**Result:** The project is created and the wizard moves to the generation stage.

## Choose repository access

Use this procedure when your project uses a repository.

**Prerequisites**

- You have a supported GitHub, GitLab, or Bitbucket repository route.
- You have provider access or repository credentials when the repository requires authentication.

**Steps**

1. Choose one repository route:

   | If you want to… | Action |
   |---|---|
   | Use a repository URL | Enter the URL, then select **Get Started →**. |
   | Browse a connected provider | Select **GitHubConnected**, **GitLab**, or **Bitbucket**. |
   | Skip repository access | Select **Create without a repository**. |

2. If the selected provider is not connected, select **Authorize GitHub**, **Authorize GitLab**, or **Authorize Bitbucket**.
3. If repository credentials are requested, enter **Username / Token Name**.
4. Enter **Password / Access Token**.
5. Select **Test Connection**.
6. Select **Configure** to continue to project configuration.
7. Search for a repository in the repository browser.
8. Select a repository.
9. Choose a branch:

   | If you want to… | Action |
   |---|---|
   | Enter a branch directly | Select **Continue →**, then enter it in **Branch**. |
   | Choose from the branch list | Select **Select Another Branch**, search for and select the branch, then select **Select Branch** and **Continue →**. |

Select **Back** to return from the repository browser to the previous wizard stage.

**Result:** The selected repository and branch are available to the project configuration route.

## When creation or generation goes wrong

Use the message on screen to choose the matching correction.

| Message | What to do |
|---|---|
| `Please enter a valid GitHub, GitLab, or Bitbucket repository URL` | Enter a supported repository URL. |
| `Please select or enter a branch to continue` | Enter a branch or use **Select Another Branch**. |
| `Connection successful` | Continue with project configuration. |
| `Connection test failed — check your credentials` | Review **Username / Token Name** and **Password / Access Token**, then select **Test Connection** again. |
| `Failed to load branches. You may not have access to this repository.` | Check repository access and try the branch picker again. |
| `Failed to load repositories. Please try again.` | Select **Retry**. |
| `No repositories found. Try a different search.` | Change the repository search. |
| `Popup was blocked. Please allow popups for this site.` | Allow pop-ups for the site, then start provider authorization again. |
| `Authorization was not completed. Please try again.` | Start provider authorization again. |
| `Failed to verify connection. Please try again.` | Try provider authorization again. |
| `Failed to start authorization. Please try again.` | Try provider authorization again. |
| `Failed to start generation` | Select **Retry** when it is available. |
| `Generation failed` | Select **Retry**. |
| `Generation was cancelled` | Select **Retry**. |
| `Project Created` | Select **Go to Project** or **Try Different Settings**. |
| `Documentation Ready!` | Continue with the available documentation destinations. |

If the project slug conflicts with an existing project, the wizard retries with a generated suffix.

## Continue after the project is created

When the selected generation work completes, the generation stage is the hand-off to the created project and its documentation destinations.

**Prerequisites**

- The project has been created.
- The selected documentation work has reached its completion screen.

**Steps**

1. Review the completion heading **Documentation Ready!**.
2. Choose the destination that matches your next task:

   | If you want to… | Select |
   |---|---|
   | Open the created project's documentation | **View Documentation** |
    | Open technical documentation after selecting **Technical Docs** or **API Reference** | **View Technical Docs** |
   | Open the created project | **Go to Project** |

3. For project-level configuration, continue with [Manage project settings](doc:manage-project-settings).
4. For generation stages and status transitions, continue with [Documentation generation lifecycle](doc:documentation-generation-lifecycle).
5. For the project area and its related surfaces, continue with [Projects overview](doc:projects-overview).

The generation stage starts the selected documentation jobs and shows their progress.

**Result:** The created project or one of its documentation destinations is open, and the selected documentation jobs are running or showing their progress.