How to add a new version of an article

This tutorial will guide you through the steps it takes to add a new version of an existing article in the Umbraco Documentation.

Contents

• Prerequisites
• Forking and cloning the documentation repository
• Creating the new article
• Adding labels to the article
• Updating the content
• Creating the PR
• Umbraco 9 Documentation
• Example: Creating a new version of an article targetting Umbraco 9

Video tutorial

Prerequisites

To work with and contribute to the Umbraco Documentation there are a few tools and extensions we recommend that you use. Using these tools will ensure consistency throughout the documentation as well as help you create the best possible version of the article.

• Visual Studio Code (VS Code)
• Markdown linter - Extension for VS Code
• Vale - Extension for VS Code

We also highly recommend that you're familiar with Git and the Markdown syntax.

Forking and cloning the documentation repository

The first step is to get the documentation files down to your local machine, so you can start working with them. This is done by forking the UmbracoDocs repository and cloning it to your local machine.

1. Follow our guide on how to fork the UmbracoDocs repository.
2. Clone your fork to your local machine or open using GitHub Desktop.

Once you have a local clone of the UmbracoDocs repository on your local machine, open the entire UmbracoDocs/ folder using your favorite editor.

We recommend using Visual Studio Code as it can be extended with a lot of useful tools for writing documentation.

Creating the new article

Now it's time to create the new article. Depending on the article and the version of Umbraco you will be targetting, these are the two most common scenarios:

• The article is targetting an older Umbraco version and you want to create a new version of the article that targets the current major version, or
• You want to target a version of Umbraco that has not been released yet.

Each scenario involves a different set of steps, which are explained below.

Target the current major version

1. Create a copy of the existing article, e.g. index.md.
2. Place the new file in the same folder as the aricle you copied.
3. Rename the old article to target the version it was written for, e.g. index-vX.md - X being the old version, e.g. 7.
4. Rename the new article index.md.

You will now have (at least) two versions of the same article: one named index-v7, which is targetting Umbraco 7, and one named index, which will target the current major version.

Target an upcoming version

1. Create a copy of the existing article, e.g. index.md.
2. Place the new file in the same folder as the aricle you copied.
3. Rename the new article based on the Umbraco version that you want to target, e.g. index-vX.md - X being the next major version, e.g. 9.

You will now have (at least) two versions of the same article. One named index which is targetting the current major version, and one named index-vX which is targetting the upcoming Umbraco X version.

Adding labels to the article

You've now created a new version of an article and have used the file naming conventions to target the correct Umbraco version.

The targetted Umbraco version also needs to be added to the metadata in the article itself.

1. Open the new article.
2. Locate the versionFrom label in the metadata section at the very top of the article.
3. Update the version number to match the version you're targetting.

Example:

---
versionFrom: 9.0.0
meta.Title: "Installing Umbraco"
meta.Description: "Instructions on installing Umbraco: in VS code, via NuGet or on a Mac"
---

In some cases, you might also want to update the meta.Title and meta.Description labels.

See the Umbraco 9 Metadata requirements section for more details on which metadata to use when verifying material for Umbraco 9.

Updating the content

With the metadata in place, it is time to start verifying and updating the content in the article.

Here's a list of the most common tasks involved with updating an article.

• Update any text that is not correct for the new version.
• Verify and update all code samples and code snippets.
• Test and verify that any links in the article is targetting the same version.
• Update any images and screenshots that are/will be outdated.

Creating the PR

Now that you've created a new article and verified and updated the contents for the targeted Umbraco version, it is time to hand in the contribution.

This is done, by submitted a Pull Request (PR) on the UmbracoDocs repository.

1. Commit and push the changes you've made to your own fork of the UmbracoDocs repository.
2. Open your UmbracoDocs fork on Github.
3. Select "Pull request".
4. Verify that the correct files are part of the PR.
5. Select "Create pull request".
6. Give the PR a descriptive Title.
7. Use the comment section for adding notes to your contribution, asking questions or describing any issues you might have encountered along the way.
8. Select "Create pull request" again to finalize the process and submit the PR.

Once your PR has been created you can expect an answer from one of the UmbracoDocs maintainers within 48 hours (during business hours).

Umbraco 9 Documentation

To make the process of verifying and updating the documentation for Umbraco 9 as transparent and inclusive as possible, we're maintaining a set of lists of the sections and articles that needs to be worked on.

Following the links below, you will find lists for each of the main sections in the Umbraco Documentation.

• Getting Started
• Implementation
• Extending
• Reference
• Tutorials

Please note that the Add-ons sections as well as the sections related to our Cloud products are not included in the lists above.

Head on over to the Issue Tracker on the UmbracoDocs repository on Github to see how you can get involved and help us get all the documentation verified and updated for Umbraco 9.

Metadata requirements

As Umbraco 9 is still in development it is subject to change over the coming months. In order to ensure that any documentation written before the official release of the product will be kept up to date, we've implemented a set of metadata to help us identify various parameters for each article.