Learn how to create and add new material to the Umbraco Documentation, including updated material for upcoming releases.
There are 2 scenarios for when you are looking to add a new article to the Umbraco Documentation.
You are adding new material to the documentation site.
This includes not-before-documented topics and new tutorials.
You are updating an article for an Upcoming major version.
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 brand 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/folder in the existing structure, where your article fits.
Create a new .md file and name it identical to the title you will give the article.
The file name needs to be all small caps and use hyphens instead of spaces.
File name example: statistics-content-app-tutorial.md.
Write the article.
Ensure the article lives up to our Style Guide and follows the outlined Markdown Conventions.
Add a link to the new article in the file.
Once you have completed the article, submit the branch to your UmbracoDocs fork and submit a PR to the official UmbracoDocs 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 documentation follows the Long Term Support (LTS) strategy for Umbraco CMS. This means that whenever a major version is End of Life (EOL), documentation for that version will be moved to GitHub.
Read the Versioning Strategy article to learn more about how to handle documentation for the different versions.
The following sections of the Umbraco Documentation are following the versioning strategy:
Umbraco CMS
Umbraco Forms
Umbraco Deploy
Umbraco Workflow
Umbraco Commerce
Umbraco UI Builder
The documentation site for an upcoming major version of any of our products will be publicly available with the Release Candidate (RC). At Umbraco HQ we will typically start working with the site 3-4 weeks before, setting up the structure on GitHub.
Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.
Only updated and new material for the upcoming release will be available on the published RC documentation on GitBook. This will occur during the RC phase.
All articles will still be available through the UmbracoDocs GitHub repository.
When the final version is released, all the documentation will again be available for that version in the published documentation.
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.
After making the changes to the article(s), it needs to be added to the SUMMARY.md file to be published on the documentation site.
Follow the steps below to add the article to the by looking upwards in the file structure.
Locate the article in the SUMMARY.md file for version 14.
Copy the line along with any ancestors.
Siblings to the current and any ancestors should be left out unless they have also been updated.
See the image below for an example of what to include.
Merge what you have copied with the existing structure in the SUMMARY.md file for version 15.
You might experience that the article is already there. In this case you do not need to do anything further.
With the article(s) added to the SUMMARY.md file, the final steps involve creating a Pull Request.
Add and commit the changes.
Submit the branch to your UmbracoDocs fork.
Whether you've found a broken link or want to add a new article to the Umbraco documentation, this article will guide you on your way.
The Umbraco Documentation is presented here on , however, it is also a and is as open source as the .
You can contribute to the documentation if something is missing or outdated. You will need a GitHub account and a fork of the UmbracoDocs GitHub repository.
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/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 .
We have a few guidelines to follow when writing documentation and we have some tools you can use for it.
The Umbraco Documentation is written using the MarkDown markup language. We have put together .
Learn how we structure and name files in the Umbraco documentation.
We recommend using a text editor like Visual Studio Code for making changes to the documentation on your local machine. We do not recommend using 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 which 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 there need to be multiple versions of our documentation.
We do this by keeping documentation for each version in separate folders.
In the screenshot above, two versions are available: 10 and 11. Within each of these folders is the documentation for all the versioned products: Umbraco Forms, Umbraco Deploy, Umbraco Workflow, and Umbraco CMS.
Umbraco Cloud and Umbraco Heartcore are not following the same versioning, which is why they are separate from this structure.
On both Issues and Pull Requests we use labels to categorize the requests and submissions.
Here's a quick explanation of the labels (colors) we use:
Category (e.g. category/missing-documentation, category/umbraco-cloud, category/pending-release)
Community (e.g. community/pr, help wanted)
State (e.g. state/hq-discussion)
Status (e.g. status/awaiting-feedback, status/idea)
Type (e.g. type/bug)
Labels will be added to your Pull Request or Issue once it has been reviewed.
Learn more about how we handle the multiple version of our documentation in the article.
If your Pull Request to any Umbraco repository gets merged, you will receive a Contributor badge on your profile on :
Learn the two different ways to submit a PR to the Umbraco Documentation.
A Pull Request (PR) is a way of submitting changes to an open-source project like the Umbraco documentation.
Let us say you have found a typing or syntax error in one of the articles on the documentation, and you want to correct it. You can do that with a pull request.
There are two ways to create a pull request:
You can either edit a file directly on GitHub, or
You can create a fork of the GitHub repository.
In order to create a PR to the Umbraco Documentation it is required that you have a GitHub account.
GitHub has a functionality that allows you to submit a PR directly from our repository. There is also a button on the right side of every article title, which allows you to jump straight into GitHub to suggest your changes.
Select "Edit on GitHub" from the right-side of the article you want to suggest changes to.
Select the pen icon to start editing the article.
Make the changes.
Add a title and description explaining what changes you have made and why you made them.
Select Propose changes.
Select Create pull request to preview your PR.
Select Create pull request again to create the PR.
This is helpful to fix typing errors or add small things. If you are working on a larger update that includes pictures and editing files then it is not the best way to work. In that case, you will be better off creating a fork. See below for more thorough instructions on this approach.
There are a lot of great tutorials available online on how to fork a repository (GitHub), but we have also created a guide with instructions.
If you do not have Git installed on your machine, you should follow these instructions before you go any further.
Once you have set up Git you can create a fork of the Umbraco Documentation repository.
When you make a fork, you get a copy of the entire repository on your own GitHub profile.
You can create a fork by selecting the Fork option at the top of the screen:
Once the fork has been created you will have your own copy of the Umbraco documentation. If you clone your fork, you will have the files locally which means you can make changes and sync them back up to your fork.
Are you adding a new article to the documentation? Add it to the SUMMARY.md file as well to ensure it is added to the navigation.
When you are satisfied with the changes you have made, you can submit a pull request to sync your copy with the original repository:
When you have had your fork for some time, you need to sync with the original repository before making new changes. This is called a rebase.
Set the original repository (UmbracoDocs) as an upstream to sync from.
Fetch the updates.
Update your own fork.
This can also be done by using the Sync fork option, which will be present once your fork is behind the original repository.
Once you have made some changes and you are happy with the result, you can create a pull request.
Navigate to the Code section on your fork.
Select Contribute and then Open pull request to get started.
Add a title and description explaining what changes you have made and why you made them.
Select Create pull request to create the pull request on the original repository.
Your PR is now subject to review with the Umbraco HQ Documentation team.
We hope to review and resolve all incoming pull requests within a couple of weeks, depending on the extent of the changes.
Learn how to provide feedback on the Umbraco Documentation.
There are a couple of different ways to submit feedback on the documentation, be it the entire platform or a single article. This article will give you an overview of the different feedback channels and how to use them.
At the right side of each article in our documentation, you have the option to provide feedback for the content.
You can rate the content from one to five stars.
Once you have selected the number of stars, you can write feedback for the page.
Clicking the small square in the feedback window, you can select an element on the page that you want to highlight with your feedback.
We highly recommend that you share feedback on the articles you come across. This will help us provide better material across the line.
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 other contributors.
Here are a few examples of what the Issue Tracker can be used for:
You were looking for a specific piece of information, but could not find it.
You found a broken link in one of the articles.
You found an article with wrong or outdated information and you do not have the time or knowledge to rewrite it.
You want to discuss possible improvements or ways to deal with a specific thing in the documentation.
You can add issues directly from the Issue Tracker on GitHub.
We have set up a template that we recommend using when creating an Issue on the tracker. The template gives you a few questions to answer, to help you give the best explanation of what you are reporting or want to discuss.
