Create a new version of an article
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.
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 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.
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 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
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 by using the version drop-down on the Documentation site.
Only updated and new material for the upcoming release will be available in the RC documentation.
When the final version is released, the RC documentation will be merged with the rest of the articles. This will then become the new default version on the documentation site.
In order to create a new version of an article, follow these steps:
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 article in question in the documentation for the current major version.
Make a copy of the article.
Take note of the path to the article.
Move the copy into the documentation for the RC version following the same path.
If the structure for the path is not created in the RC documentation, create it using placeholder articles.
Add the article to the by looking upwards in the file structure.
Update the article to match the upcoming major version.
Once you have made the necessary changes, submit the branch to your UmbracoDocs fork and submit a PR to the official UmbracoDocs repository.
Last updated