Learn the two different ways to submit a PR to the Umbraco Documentation.
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:
Edit a file directly on GitHub.
Create a fork of the GitHub repository.
You can submit a PR directly from our repository. 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.
Navigate to the article you want to edit.
Select "Edit on GitHub" from the right side of the article.
Select the 🖊️ icon to start editing the article.
Make the changes.
Add a commit message describing what you changed.
Select Propose changes.
Fill in the required information in the PR description.
Select Create pull request to submit the PR.
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 how to fork a repository (GitHub).
Ensure Git is installed on your machine.
Go to the Umbraco Documentation repository.
Select Fork in the top-right corner to create a personal copy of the repository.
Once the fork is created:
Clone your fork to your local machine.
Make your changes in a local branch.
If you add a new article, update the SUMMARY.md file to include it in the documentation navigation.
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.
git remote add upstream https://github.com/umbraco/UmbracoDocs/
git fetch upstream
git rebase upstream/mainTo sync via GitHub:
Use the Sync fork option when your fork is behind the original repository.
Once you have made changes and are happy with the result, you can create a PR.
Navigate to the Code section of your fork.
Select Contribute > Open pull request.
Add a title and description explaining your changes.
Select Create pull request to submit a PR to the original repository.
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.
Whether you've found a broken link or want to add a new article, this guide will help you contribute to the Umbraco documentation.
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.
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 Pull Request.
Submit a more extensive update or change by forking the Documentation repository.
Raise a question, start a discussion, or report an issue on the Issue Tracker.
Help improve the readability of the documentation by verifying articles against our Style Guide.
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.
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.
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 Documenting multiple versions and products article.
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
category/pending-release
Community
community/pr
help wanted
State
state/hq-discussion
Status
status/awaiting-feedback
status/idea
Type
type/bug
Internal Review
review/docsteam
review/developer
Labels are added during the initial review of your pull request or issue.
Learn how to create and add new material to the Umbraco Documentation, including updated material for upcoming releases.
There are 2 common scenarios where you might want to add a new article to the Umbraco Documentation:
You are adding new material to the documentation site.
This includes topics or tutorials not previously covered..
You are updating an existing article for an Upcoming major version of a product.
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:
Access the UmbracoDocs GitHub repository.
Fork the repository.
Clone your fork to your local machine.
Create a new branch using the following naming convention: productname/topic
Branch name example: cms/new-content-app-tutorial
Locate the section or folder in the existing structure where your article fits.
Create a new .md file and name it using the title you will give the article.
The file name needs to be in small caps and use hyphens instead of spaces.
File name example: statistics-content-app-tutorial.md.
Write the article following:
Add your new article to the file so it appears in the documentation navigation.
Commit and push your changes to your forked repository.
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
Umbraco Commerce
Umbraco UI Builder
Umbraco Engage
Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.
Access the UmbracoDocs GitHub repository.
Fork the repository.
Clone your fork to your local machine.
Create a new branch using the following naming convention: productnameXX/topic
Branch name example: cms15/configuration
Locate the article you need to make changes to.
Make the necessary changes to the article.
Add and commit the changes.
Push the branch to your forked repository.
Learn how to provide feedback on the Umbraco Documentation.
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.
On the right-hand side of every article, you'll find an option to submit feedback directly related to that article.
Sharing your feedback helps the team at Umbraco HQ provide better material across the products.
The feedback is used when determining which articles need to be reviewed by the documentation team at Umbraco HQ.
The Issue Tracker 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.
Go to the Issue Tracker on GitHub.
Select New Issue.
Fill out the form, answering the questions to explain your suggestion or problem clearly.
Submit the issue.
