You can contribute to the Umbraco Documentation by submitting a Pull Request (PR). A PR is a way to suggest changes to an open-source project, such as fixing errors, improving readability, or adding new content.

There are two ways to create a PR:

1. Edit a file directly on GitHub.

2. Create a fork of the GitHub repository.

Option 1: Creating a PR directly on GitHub

You can submit a PR directly from our . You can also use the button on the right side of every article title. This allows you to jump straight into the file on GitHub and suggest your changes.

Following the approach is recommended for changes such as:

• Fixing typos or grammar mistakes.

• Changes that are confined to a single article.

• Updating code snippets.

1. Navigate to the article you want to edit.

2. Select "Edit on GitHub" from the right side of the article.

3. Select the 🖊️ icon to start editing the article.

4. Make the changes.

Option 2: Creating a PR through a Fork

The second option to submit a PR is by using a fork of the Umbraco Documentation repository. This method requires more initial setup but lets you reuse your fork for future contributions.

Following the approach is recommended for changes such as:

• Writing new articles or guides.

• Adding updates that affect multiple articles.

• Applying an update that needs to be added to multiple versions.

There are a lot of great tutorials available online on .

Step 1: Creating a Fork

1. Ensure Git is installed on your machine.

2. Go to the .

3. Select Fork in the top-right corner to create a personal copy of the repository.

Once the fork is created:

1. Clone your fork to your local machine.

2. Make your changes in a local branch.

3. If you add a new article, update the SUMMARY.md file to include it in the documentation navigation.

4. Sync your changes back to your fork.

To sync via command line:

• Set the original repository (UmbracoDocs) as an upstream to sync from.

• Fetch the updates.

• Update your own fork.

To sync via GitHub:

• Use the Sync fork option when your fork is behind the original repository.

Step 2: Creating a PR

Once you have made changes and are happy with the result, you can create a PR.

1. Navigate to the Code section of your fork.

2. Select Contribute > Open pull request.

1. Add a title and description explaining your changes.

2. Select Create pull request to submit a PR to the original repository.

Step 3: The Review Process

Your PR will be reviewed by the documentation team at Umbraco HQ.

Review times can vary based on the size and complexity of the contribution—from a few minutes to several weeks.

The Umbraco Documentation is presented here on GitBook. The documentation is also available as a GitHub repository and is open-source, just like the Umbraco CMS.

You can contribute to the documentation if something is missing or outdated. A GitHub account and a fork of the UmbracoDocs GitHub repository are required.

How to Get Started

There are many ways in which you can contribute to the Umbraco Documentation. The approach you choose to take depends on what you want to achieve with your contribution.

• Request a quick/minor change to an article by submitting a .

• Submit a more extensive update or change by .

• Raise a question, start a discussion, or report an issue on the .

• Help improve the readability of the documentation by verifying articles against our .

Consistency and readability are important when writing and reading documentation. When you contribute, follow the style guidelines and rules outlined in the Style Guide.

The Umbraco Documentation is written using the Markdown markup language.

Learn how we structure and name files in the Umbraco documentation.

Writing documentation locally

Use a text editor like Visual Studio Code to make changes to the documentation locally. Although it is possible, it is not recommended to use an Integrated Development Environment (IDE) like Visual Studio for making changes to the documentation on your local machine. This is because the IDE may create files in the project that are not needed for the document changes to be implemented.

Multi-version documentation

Whenever a new version of an Umbraco product is released, the previous way of doing things may change. This means that multiple versions of our documentation must exist.

Versioning is done via the file structure, where all versioned products are located under a folder named by the major version of Umbraco.

For example, version folders such as '10' and '11' contain documentation specific to those product versions.

Umbraco Cloud and Umbraco Heartcore are not documented by version, which is why they are separate from this structure.

Learn more about how versioning is managed in the article.

Labels

On both Issues and Pull Requests, labels are used to categorize the requests and submissions.

Here's a quick explanation of the labels (colors):

• Category

  • category/missing-documentation

  • category/umbraco-cloud

Labels are added during the initial review of your pull request or issue.

There are different ways to submit feedback on the Umbraco Documentation, whether it's about a single article or the platform as a whole. Your input helps us improve and prioritize what matters most to the community.

This article gives you an overview of the different feedback channels and how to use them.

Submit Feedback on an Article

On the right-hand side of every article, you'll find an option to submit feedback directly related to that article.

Submit a GitHub Issue

The is a way to keep track of ideas, issues with wrong or outdated documentation, and discussions with contributors.

Here are a few examples of when to create an issue:

• You are looking for a specific piece of information, but can't find it.

• You've found a broken link in one of the articles, but don't know how to fix it.

• An article contains outdated or incorrect information, and you don't have time or knowledge to submit a PR.

• You would like to propose a new section or discuss improvements to existing documentation.

Creating an Issue

1. Go to the .

2. Select New Issue.

1. Fill out the form, answering the questions to explain your suggestion or problem clearly.

2. Submit the issue.

There are 2 common scenarios where you might want to add a new article to the Umbraco Documentation:

1. You are adding new material to the documentation site.

   1. This includes topics or tutorials not previously covered..

2. You are updating an existing article for an Upcoming major version of a product.

Add New Material to the Documentation

When you are adding a brand new article to the Umbraco Documentation, there are a few questions that we recommend asking yourself before getting started:

The steps to create, write, and add a new article to the Umbraco Documentation are outlined below:

1. Access the repository.

2. Fork the repository.

3. Clone your fork to your local machine.

4. Create a new branch using the following naming convention: productname/topic

Update an Article for an Upcoming Major Version

The documentation is versioned using directories in the root of the repository. The major Umbraco CMS version number is used to name the directories, and you will find documentation for each versioned Umbraco product within them.

The following sections of the Umbraco Documentation follow the versioning strategy:

• Umbraco CMS

• Umbraco Forms

• Umbraco Deploy

• Umbraco Workflow

Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.

Update an article for the upcoming release

1. Access the repository.

2. Fork the repository.

3. Clone your fork to your local machine.

4. Create a new branch using the following naming convention: productnameXX/topic