Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Examples, tutorials, references, and best practices—everything you need to build future-proof applications with Umbraco and the available add-on products.
Whether you're using Umbraco CMS, Umbraco Cloud, or Umbraco Heartcore, our documentation has you covered for all your needs.
Are you looking to get started?
In the Getting Started section, you find links to articles depending on what you're looking to do with Umbraco.
The Getting Started section will provide you with what you need: create a website, set up hosting, or looking to customize an Umbraco website, etc.
Head on over to the Getting Started section
Don´t know which product to choose?
If you're unsure which products to choose for your specific needs, see the Exploring the Umbraco Products article.
The documentation project is open source and hosted on GitHub. If you have any corrections or additions to the documentation, suggest a change or let us know.
Head over to the Contribute section to start contributing to the Umbraco Documentation.
Build and add forms to your Umbraco websites with Umbraco Forms.
Ensure smooth code and content deployments on your Umbraco projects.
Setup custom workflows for managing content on your Umbraco website.
Generate a management user interface for your custom data sources.
Find all the resources you need in order to manage your Umbraco project.
This section allows you to investigate the development process, the commercial options and how to best plan out an Umbraco project.
An Umbraco project is the process of developing a website, program or application including the Content Managing System (CMS) which you can use to customise.
In this section you will find information on the key concepts and requirements of working with Umbraco CMS. You will find advice on everything from how to lead a project, how to work with design to the process of launching the completed website.
What commercial options are available from Umbraco?
What is the Umbraco Community?
Explore the unique features and use cases of Umbraco products to find the perfect fit for your project needs.
Embarking on a journey with Umbraco can be an exciting process. At Umbraco, we understand that choosing the right tool for your project can be overwhelming, given the variety of products available. We are here to help you navigate through the different product options so you can find the best fit for your needs.
Let's explore the typical stages of using Umbraco:
Begin by familiarizing yourself with Umbraco CMS, its features, and its capabilities. Umbraco CMS is an open-source .NET content management system (CMS) designed for building websites and web applications. Read more about Umbraco CMS or if you want to try it out head on to the Umbraco CMS Documentation.
All Umbraco products are based on the Core of the Umbraco CMS. We've got a short introduction video that will help you dive in to the Umbraco CMS world.
Umbraco CMS is an open-source software released under the MIT License. It is free to install, setup, and host for yourself. For more information, see the Umbraco Source Code License site.
The Council of the European Union wanted to replace its outdated CMS with one that would streamline content publishing and translation across multiple languages.
Using Umbraco CMS, they developed a solution that facilitated rapid content creation and multilingual translation, meeting the Council's requirements while minimizing time and effort.
Read the Case Study to know how the Council of the European Union successfully utilized Umbraco CMS to modernize their content management system.
Once, you have installed Umbraco locally, it's time to start building websites. Let's talk about where your Umbraco masterpiece will live. You've got options!
You can opt for Umbraco Cloud for a managed hosting solution. Umbraco Cloud is a hosting and development platform designed to streamline the process of building and managing Umbraco CMS projects.
Read more about Umbraco Cloud or if you want to try it out head on to the Umbraco Cloud Documentation.
You can take a 14 day free trial of Umbraco Cloud with no obligation to purchase a subcription.
For more information on the details and features of each pricing plan, see the Umbraco Cloud Pricing site.
Cab Engine leverages Umbraco Cloud's Baseline feature to empower clients, facilitating quicker launches, seamless user experiences, and effortless updates through their Cab Chassis product.
Read the Case Study to know how Umbraco Cloud's Baseline feature offered a centralized solution and integrated development environment for seamless project evolution.
You can host your Umbraco CMS website on your own servers . For more information, see the Hosting an Umbraco project and Get a good grip on the best Umbraco hosting options! articles.
Ready to take your website to the next level? Say hello to the world of headless CMS - Umbraco Heartcore. A headless CMS is where the backend content management capabilities are decoupled (or "headless") from the frontend presentation layer. It focuses solely on content creation, storage, and distribution through APIs.
Umbraco Heartcore provides developers with the flexibility to deliver content across various channels and platforms through APIs. With the use of APIs, the content is then delivered to any device or platform. This is while maintaining the correct structure, allowing for faster development and delivery of digital experiences.
Read more about Umbraco Heartcore or if you want to try it out, head on to the Umbraco Heartcore Documentation.
You can take a 14 day free trial of Umbraco Heartcore with no obligation to purchase a subcription.
For more information on the details and features of each pricing plan, see the Umbraco Heartcore Pricing site.
Aardman - the renowned animation studio, embraced Umbraco Heartcore, a headless CMS, to streamline their content creation and distribution processes.
By implementing a headless CMS, Aardman decoupled the content management and presentation layers, allowing them to manage content centrally while delivering it to multiple frontend channels through APIs.
Read the Case Study to know how Umbraco Heartcore empowered Aardman to create engaging experiences for different platforms, from websites and mobile apps to smart TVs and voice assistants.
Whether you're creating a website, launching an e-commerce store, or building a custom application, Umbraco has you covered every step of the way.
Below, you can find the available Umbraco Add-On Products for digital experience:
Overview
Umbraco Forms is designed to simplify the process of creating and managing web forms within the Umbraco CMS environment. It empowers users to build interactive forms without the need for coding knowledge, enhancing user engagement and data collection capabilities.
Read more about Umbraco Forms or if you want to try it out head on to the Umbraco Forms Documentation.
Subscription
Umbraco Forms is free to try out on your local machine with limitations of some features. You can read more about what is included in a license on the Licensing page.
Umbraco Forms is included in Umbraco Cloud and Umbraco Heartcore (standard plan and above) subscriptions. If you are using Umbraco Cloud or Umbraco Heartcore, you do not need to pay for an Umbraco Forms license.
Case Study
The Legal Ombudsman needed a complete overhaul of their website as well as an online complaints form. The organization had to ensure that its online forms comply with the UK Government Design System (GDS).
Read the Case Study to know how Umbraco Forms, hosted on Umbraco Cloud, maintains GDS compliance while securely storing forms data in a Cosmos database on Azure within a UK datacentre, meeting storage requirements.
Overview
Umbraco Workflow is a comprehensive workflow management tool integrated into the Umbraco CMS platform. It enables you to streamline content creation, review, and approval processes, ensuring efficient collaboration within your digital projects.
Read more about Umbraco Workflow or if you want to try it out head on to the Umbraco Workflow Documentation.
Subscription
You can try out Umbraco Workflow on your local machine with a trial license. The trial license introduces some restrictions around advanced features but is otherwise a full-featured workflow platform.
You can find which features are included in the trial versus the paid license in the Umbraco Workflow Product page.
Use-Case Example
Organizations managing websites, such as news portals or corporate blogs, can implement Umbraco Workflow to establish content publication workflows. Content creators can submit articles or blog posts for review, and editors can review, edit, and approve the content before publication, ensuring quality control and adherence to editorial standards.
Overview
Umbraco Deploy is designed to streamline the process of deploying Umbraco CMS websites across different environments and managing content synchronization between instances. It provides developers with a reliable and efficient solution for deploying website changes and ensuring content consistency across development, staging, and production environments.
Read more about Umbraco Deploy or if you want to try it out head on to the Umbraco Deploy Documentation.
Subscription
Umbraco Deploy is free to try out on your local machine with limitations of some features. You can read more about what is included in a license on the Licensing page.
Umbraco Deploy is included in the Umbraco Cloud subscription. If you are using Umbraco Cloud, you do not need to pay for an Umbraco Deploy license.
Use-Case Example
Large enterprises managing complex Umbraco CMS websites with multiple contributors and environments can benefit from Umbraco Deploy to maintain content consistency and streamline deployment workflows. This ensures seamless website updates and content changes across the organization.
Overview
Umbraco Commerce is an e-commerce solution built on top of the Umbraco CMS platform. It provides businesses with the tools they need to create and manage online stores, sell products or services, and deliver seamless shopping experiences to customers.
Read more about Umbraco Commerce or if you want to try it out head on to the Umbraco Commerce Documentation.
Subscription
Umbraco Commerce is free to try out on your local machine without the need for a license. For information on license, raise a request on the Umbraco Commerce Product page. A member of the sales team will manage this process.
Case Study
TCMM aimed for market dominance with a focus on brand positioning and leveraging their new technology platform for improved conversion rates.
true implemented the solution headlessly using the Umbraco Content Delivery API and the Umbraco Commerce Storefront API, which fits seamlessly into their project's architecture.
Read about the Case Study to know how Umbraco's ability to handle multiple sites with a focus on conversion and content aligned with TCMM's growth ambitions without compromising existing site components.
Overview
Umbraco UI Builder is designed to simplify the process of creating custom user interfaces (UIs) within the Umbraco CMS environment. It empowers developers and designers to build interactive and responsive UI components for Umbraco-based websites and applications with ease.
Read more about Umbraco UI Builder or if you want to try it out head on to the Umbraco UI Builder Documentation.
Subscription
Umbraco UI Builder is free to try out on your local machine without the need for a license. For information on license, raise a request on the Umbraco UI Builder Product page. A member of the sales team will manage this process.
Umbraco UI Builder is included in the Umbraco Cloud (Standard plan and above) subscription. If you are using Umbraco Cloud, you do not need to pay for an Umbraco UI Builder license.
Use-Case Example
E-commerce retailers offering customizable products can use Umbraco UI Builder to create product configurator tools. This allows customers to customize product attributes, such as color, size, and features, in real-time, visualizing the changes dynamically before making a purchase decision, thereby enhancing the shopping experience and driving sales.
In this section, we will build an online presence with some of Umbraco's products and add-on products. Let's assume:
Company Profile: John Doe Enterprises is a growing e-commerce company specializing in handmade jewelry. They aim to expand their online presence, enhance customer engagement, and streamline their business operations.
Solution Overview: John Doe Enterprises has decided to leverage various Umbraco products and add-on products to achieve their goals effectively.
Below you can find a journey on how John Doe Enterprises can use the different Umbraco Products and add-on products:
By leveraging some of Umbraco's products and add-on products, John Doe Enterprises successfully builds a comprehensive online presence, enhancing customer engagement, and streamlining their business operations, positioning themselves for sustainable growth and success in the competitive e-commerce market.
Below you can find a list of Testimonials and other resources to see how Umbraco and its products are used in real life:
Videos of Umbraco Cloud Testimonials
Videos of Umbraco Testimonials
Videos of Umbraco Case Webinar
Other resources: Book a live Demo, Training, Video Tutorials, Blog, Documentation, and so on.
This section will guide you on where to find the answers for any questions you may have.
If you haven't been able to find a topic that suits your needs, there are many ways for you to find help.
You can talk to developers across the globe via the Umbraco Forum, report an issue with the Documentation team or check out our Training options. We also have UmbracoTV, a team of friendly supporters and direct links to contact the team at Umbraco HQ for any questions you may have.
Umbraco Forms, Umbraco Deploy, and Umbraco Workflow are commercial products.
Find documentation for all official Umbraco add on packages.
The Umbraco Documentation is versioned based on major versions of the Umbraco CMS. Learn more about how that works in this article.
The Umbraco Documentation covers multiple versions of multiple different products. This article explains how we version the documentation as well as how to use it when reading the documentation.
The major version of Umbraco CMS is currently used for versioning the documentation for the following Umbraco products:
The Umbraco CMS
Umbraco Forms
Umbraco Deploy
Umbraco Workflow
Umbraco Commerce
Umbraco UI Builder
The documentation for Umbraco Cloud and Umbraco Heartcore is not following the CMS versioning as these are both Software as a Service (SaaS) projects.
The Umbraco Documentation covers all supported versions of the Umbraco CMS as well as the official Umbraco add-ons. For each supported major version of Umbraco CMS, a version of the documentation for CMS and the add-ons exists.
The documentation for each Umbraco product will always document the latest minor version of the current major version.
When an RC for a new major version of an Umbraco product is released, a new version of that documentation will be available. When the major version is released, the documentation for it will be the new default version of the Umbraco Documentation.
This means that the Umbraco Documentation will cover each major version of the Umbraco product until they are EOL. After a major version is EOL the documentation for that version will be unpublished after 1 month extended to 3 months for LTS versions.
Unpublished versions of the Umbraco Documentation will continue to be available from GitHub.
We reserve the right to change the strategy for EOL versions. This is due to the fact that we want to thoroughly test the process before making a decision.
The main
branch on the repository holds all versions of the documentation for all Umbraco products, including Cloud and Heartcore. A directory exists for each published major version of Umbraco CMS, under which you can find the corresponding documentation for each Umbraco product.
The Umbraco Documentation follows the .
The Umbraco Documentation is synchronized with a GitHub repository, , which is open source. Read the to learn more about contributions and how to get started.
Documentation for Umbraco 8 and earlier versions are gathered in a single branch, legacy-docs
. These versions are live on a different site: .
With Umbraco's flexible architecture, John Doe can customize his website's design and functionality according to his specific requirements, ensuring a unique and engaging user experience.
John Doe can host his Umbraco-powered website on Umbraco Cloud for hassle-free deployment, scalability, and maintenance. He can take advantage of Umbraco Cloud's built-in features, such as automatic updates, backups, and multiple environments, to ensure his website's reliability and performance.
John Doe can utilize Umbraco Forms to create and manage interactive and dynamic forms on his website. He can use forms for collecting customer inquiries, feedback, and orders, streamlining the communication and order processing workflows.
John Doe can integrate Umbraco Commerce to leverage its robust features, including product catalog management, order processing, and payment gateways, to create a seamless online shopping experience for their customers.
This section shows you some beginner tools and information to get you started with editor content in Umbraco.
Creating, editing, and publishing content onto your website using Umbraco doesn't require any super special skills or prior knowledge - honestly!
This section will help you get started as a content editor in Umbraco, introduce Umbraco-specific terminology, and lead you to find further help.
There is also information on how to use features such as translations, forms, and other ways to personalize your site.
Here you will find details on Azure, Umbraco Cloud, upgrading Umbraco, server configuration and system requirements.
This section shows you some beginner tools and information to get you started with Umbraco. From making a local installation to extending the backoffice.
In this section, you will find information on which frameworks, languages, and platforms to use with Umbraco to create user-friendly and responsive websites.
There is a set of key concepts that you will need to familiarize yourself with. This section will give you the details you need as well as introduce you to how you can work with them in the Umbraco backoffice.
We've even included some helpful tutorials which you can follow for creating a basic site to get you started.
Your website's content is based on Document Types. Each of these Document Types is structured by Properties made up of Data Types, and each Data Type has an underlying Property Editor.
Once you've created content based on the Document Types, they will be published on your website using Templates.
There are a lot of terminologies here! Let's look at breaking those terms down:
Video: Create an Umbraco website
You can find resources to guide you through the process of installing and hosting different types of Umbraco projects. Here you will find details on Azure setups, our hosting service, how to upgrade Umbraco, and much more.
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’s 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 an account on GitHub.
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.
On the right side of the article title at the top of the page, click on the icon with 3 dots â‹®
Select "Edit on GitHub" from 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 Docs team.
We hope to review and resolve all incoming pull requests within a couple of weeks, depending on the extent of the changes.
The Umbraco backoffice itself can be customised and extended, this section is dedicated to getting started with these extension points.
The Umbraco backoffice itself can be customized and extended to fit the experience you want your editors to have when working with your website. This section is dedicated to getting started with these extension points.
Umbraco gives you the opportunity to create and customize packages, Property Editors, and content applications, and even create your own Dashboard. You can also extend things like the search functionality, Health Checks, and configurations.
In this section, you will find some routes to how to do so and some tutorials to create your own personal packages and content applications.
It is recommended that you have some knowledge and prior experience working with AngularJS, to follow the tutorials presented in this section.
To get you started here are some examples of what you can extend in Umbraco:
If you're in a creative mood then why not experiment with some of our tutorials:
Find all the resources you need when you're developing and customizing an Umbraco website - be it backend or extending the backoffice.
Umbraco is built on top of a Microsoft MVC framework. You can build upon this technology to work alongside and extend the functionality in Umbraco. It is also designed to be pluggable so that you can replace key components with your own custom implementations if prefer.
It is possible to build an Umbraco site without Visual Studio and the techniques on this page - see the Creating websites with Umbraco section.
This section is dedicated to introducing techniques that will help you get started with developing an Umbraco site. You'll find out how to develop the framework of an Umbraco project as well as how to extend and customize the Umbraco backoffice.
The concepts in this section go beyond standard templating methodologies and introduce some Umbraco-specific terms and helpers, such as SurfaceControllers and management service APIs. All of which is the technology that you can take advantage of when developing with Umbraco.
You will also find information regarding Umbraco's underlying dependency injection framework.
This will break into two sections: Extending the Umbraco backoffice and Developing custom websites.
The Umbraco backoffice can be extended using AngularJS and C#. Customizing the Umbraco backoffice and editing experience includes creating your own Property Editors, Dashboards, and packages. You will also find information about how to customize things like Health Checks and the built-in search functionality.
Check out the Extending section in the CMS docs for a good place to start.
From a frontend perspective, Umbraco does not dictate HTML, CSS, or JS in your website build. There is nothing Umbraco-specific about it.
Umbraco is highly customizable which means you can integrate it with anything and make it behave as you want. With Umbraco, you start out with a clean slate.
Umbraco uses ASP.NET and MVC patterns and you can extend and write your own controllers using the approach outlined in this section.
When you are customizing or extending your Umbraco website using C# we recommend using Visual Studio.
You can also use a simpler tool like Visual Studio Code or any other text editor you prefer working with. However, this is only recommended when you're not working directly with the C# files.
While you can use a text editor, put changes in the App_code
folder, and have it compiled on startup; we recommend using an IDE.
An IDE will give you a lot of support, as it's built for working with C# files, ASP.NET, and MVC frameworks.
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 GitBook, however, it is also a GitHub repository and is as open source as the Umbraco CMS.
You can contribute to the documentation if something is missing or outdated. All you need is a GitHub account and a fork of the UmbracoDocs GitHub repository.
In this section, you can learn about the different ways to contribute. You can also find guidelines for writing good documentation.
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/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.
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 an article where you can learn more about MarkDown.
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.
Learn more about how we handle the multiple version of our documentation in the documenting multiple versions and products article.
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.
If your Pull Request to any Umbraco repository gets merged, you will receive a Contributor badge on your profile on Our Umbraco:
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, as 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 couldn't 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.
Learn how to use Markdown to write articles for the Umbraco Documentation.
The Umbraco Documentation uses Markdown for all articles.
In this article you can learn how we Markdown for different elements on our documentation.
Images are linked using relative paths to .md
pages.
The following sample adds an image, img.png
, located in an images
folder:
Make sure to add a descriptive image text that presents the user with the same information as the image provides.
In the following you will find a few examples of different links.
Include either the complete URL, or link using the following syntax:
When linking between pages in the documentation, link using relative paths. The following are examples of linking to an article.
Link to an article in the same directory as the current article:
Link to an article in a different directory than the current article:
Use the title of the article that is linked to, as the link text. This is done in order to tell the reader what the will find on the other end.
Do not use here or link as the link text, as this provides little to no information about the destination.
It is possible to add a page link that spans the entire width of the page. This is generally used for linking to a new subject related to the article at hand.
The following is a page link that links to the "Submit Feedback" article:
Code formatting comes in 2 variants: inline code and code blocks.
Use inline code when referencing file names and paths as well as actual code the does not extend over multiple lines.
Inline code should be wrapped in ` (backtick) characters.
Four types of hints can be added to our documentation: info, success, warning and danger.
We follow to our articles.
.
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
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.
When you a contributing to the Umbraco documentation it can be useful to know how we structure directories, files and images.
In this article you will get an overview of the file structure as well as a few best-practices for naming files.
The overall structure of the Umbraco documentation is divided by product. Each Umbraco product has its own directories with articles and images.
Diving one step deeper, each individual topic is contained in its own directory.
Each directory must have a README.md
file which will act as a landing page for that directory. If images are used, these must be in an images
directory next to the .md
file referencing them using relative paths.
/topic
(directory)
README.md
another-page.md
/images
(directory)
images.png
/subtopic
(directory)
README.md
topic.md
another-topic.md
/images
(directory)
All file and directory names need to be small-caps in order to be synced properly with GitBook.
If an article is not a landing page, we recommend using the title of the article as the file name.
Images are stored and linked using relative paths to .md pages, and should by convention always be in an images
directory. To add an image to /documentation/reference/partials/renderviewpage.md
you link it like so:
And store the image as /documentation/reference/partials/images/img.png
Images can have a maximum width of 800px. Please always try to use the most efficient compression, gif
or png
. No bmp
, tiff
or swf
(Flash).
When adding code snippets to the Umbraco documentation, refer to this article for tips on how to improve the samples.
The articles in the Umbraco Documentation can in most cases benefit from relevant code samples to support the written text.
In this article, you will find guidelines that outline how we recommend formatting and using code samples. We provide definitions and examples of the most used types of code samples in the Umbraco Documentation.
To ensure quality and consistent code samples, we have outlined some good practices for you to follow when adding code snippets.
Add a clear description
Add a caption (file name)
Use code comments
Use real-life samples
Add correct syntax highlighting
Add only complete compilable samples (incl. using
statements)
Check for syntax errors
Each of these guidelines is explained in more detail below.
Code samples without explanations and instructions could make the reader run into issues when using the snippet.
Make sure to always add a clear description of what the code sample showcases before or after adding the snippet to the article. It should be clear where and when the snippet can be used.
In most cases, it is relevant to tell the reader which file or file type a code snippet should be added to.
Aside from mentioning this in the description of the code snippet, it is also recommended to add the file name as a caption.
Is the code snippet from a JSON file, add fileName.json
as the caption.
When adding code samples that contain more than a single feature or method, it is recommended that you add inline comments.
By adding inline comments you avoid having too much text surrounding the code sample, and you also help readers understand the code snippet in detail.
The use of code comments does not eliminate the need for a description of the code sample in the surrounding text.
The documentation often aims to explain complex scenarios and concepts within Umbraco. This means that code samples can be useful to further the understanding. It is important that these code samples are real-life examples. For example, using variables such as 'foo' and 'bar' can distract from the intent of the example. Aim to use an example that would make sense to add to a production environment.
It is a good idea to use placeholders for names, methods, etc., in order to keep the code samples as neutral and general as possible.
With Umbraco, often there is more than one way to achieve a result, depending on context and the skillset of the development team. Having multiple examples - for example, a Modelsbuilder version and a non-Modelsbuilder version - can help prevent readers from mixing techniques in their solution. It is fine to provide multiple examples.
When you add code blocks to an article, make sure that you add the correct syntax highlighting. This will "prettify" the code in the sample based on which language is used.
If you are adding a code sample using a language that isn't supported, it is recommended that you add a none
label instead.
using
statements)A reader of the Umbraco Documentation should be able to grab code samples in the articles and apply them to their own code solution. While there might be a need for some minor alterations, the code in the sample should compile.
Include any relevant Using
statements for namespaces that provide 'extension' methods or key functionality.
When reading any piece of text, there is nothing more frustrating than running into spelling and syntax errors. This also applies to code samples.
Any code that is added to articles in the documentation should be double-checked for syntax errors and typos.
The use of file-scoped namespaces improves, among other things, the readability of the code samples. Therefore, use file scoped namespaces in the examples. See below how to use file-scoped namespaces:
Instead of:
Code samples are relevant for most types of articles. Potentially, any topic covered could benefit from a real-life code sample to support the contents of the article.
You might want to base an entire article on one code sample. Alternately, if you're describing a flow or feature, you might want to add smaller code snippets to highlight specific points.
As a basis, we are working with 3 types of code samples in the Umbraco Documentation.
Use inline code when you are referencing methods, using the names of the elements or highlighting a certain value.
Example:
The markdown above will output the following:
As part of longer articles or tutorials, we recommend using smaller code snippets to highlight the bits of code that need to be implemented.
These snippets can be added between sections anywhere in an article without breaking focus from the main topic. Keep in mind that adding too many snippets in quick succession can be confusing to the flow of the article.
Example:
The Razor snippet above will output the following:
As part of tutorials and longer articles explaining a specific workflow, it might make sense to add a full code sample of the topic covered.
We recommend creating separate articles for these large code samples and using them as references, instead of adding them as part of the actual article. Having long snippets in an article that already contains multiple sections and steps can make the article confusing.
It is highly recommended to use line numbers in large code samples. This will make it easier to reference certain parts of the sample in the surrounding text.
Help us keep the Umbraco documentation accessible and readable by following our style guide which is defined in this article.
To ensure that the documentation is readable and has a similar style throughout we have defined a set of guidelines to follow. Most of the guidelines outlined here are set up with an automatic style linter called Vale. Additionally, we have a GitHub bot that will check PRs for broken rules and advise you on what to change.
Below you will find a description of each rule the Umbraco Documentation is currently being checked against.
Try to not use any kind of punctuation in headings and headlines. These should act as titles, and no punctuation is necessary.
For consistency, this rule will give a warning if you end headings with either of these punctuation symbols:
?
:
.
The words in the list below will cause a warning when they are included in your contribution.
Try not to use any of the mentioned words, as they are often opinionated. What may be 'easy' for you, might not be easy for another user reading the article.
In most cases, these words can be removed entirely whereas a rephrasing might be necessary in other cases.
Simple
Simply
Just
Easily
Actually
To ensure consistency with grammar and sentences, this rule will give an error if you have a list that starts with uncapitalized words.
An exception to this rule would be when listing items or names that use camelcase.
This rule will give a warning if you have a sentence with more than 25 words.
The rule is added in order to improve the readability of the documentation.
In order to ensure readability and consistency, this rule will warn you if you have more than 1 space in a row in your text.
This rule will give you a warning when using a term that we prefer to avoid in the documentation.
Example: The term blacklist
should be avoided and instead replaced with deny list
.
For a full list of terms please check the style rule.
This rule is added in order to ensure that Umbraco-specific terms and names are spelled consistently throughout the documentation.
The list of Umbraco Terms includes, but is not limited to Umbraco, backoffice, Document Type, and Umbraco Forms.
All first-time uses of an acronym in the documentation need to be accompanied by a definition of that acronym. If an acronym is not defined on its first use in an article, the checker will give a warning.
Acronyms should be defined using either a parenthesis or a colon followed by the definition.
Examples of the use of acronyms:
In order to ensure that markup languages and other names are capitalized correctly a rule has been added to check for this.
The rule will ensure that instances of HTML and CSS are always written using only capital letters. It will also check whether JavaScript is written in full.
In some cases, throughout our documentation, we refer to other software providers or brands. We have added a rule to ensure that the most commonly used brand names are spelled and capitalized correctly.
The rule will, as an example, ensure that the names Microsoft and Slack are always capitalized.
There are two types of commonly used lists in the Umbraco documentation: ordered lists and unordered lists.
We recommend using ordered lists for sequential task steps and unordered lists for sets of options, notes, criteria, and the like.
In order to keep lists short and to the point, we recommend that you follow these guidelines:
Start each item on the list with the action word.
Add a maximum of two actions per item list.
Keep each list item short and to the point.
Add additional information in one or more sub-list items.
One of the big strengths of Vale is that it is possible for a contributor to run the tests locally before you create a PR. Below are a couple of options on how to test the documentation.
There is an extension for Visual Studio Code that allows you to use Vale as you are writing documentation. It can also be used to run checks on existing articles and find where potential changes are needed.
The extension is called vale-vscode
and can be downloaded via the Visual Studio Code Marketplace in your editor.
To use it, you will still have to install a Vale Server
on your computer. For more information, see the official Vale installation article.
Once the tools have been installed, a check of the complete repository of articles can be done using the terminal within Visual Studio Code.
Run the following command:
vale --glob='*.md' .
The Vale extension will also run automatically when you are viewing Markdown files. It will present warnings directly in the document as you write, based on the style rules set for the project. It will look similar to this:
The first step to running Vale locally is to install it following Vale's Installation documentation.
Next, you can open a command line tool in the documentation repository and run the following command:
vale --glob='*.md' .
This tells Vale to test all markdown files (.md) in the current directory (.). The output will look something like this:
It will show you what file has issues. In the case above the v8documentation.md
the article broke the HeadingsPunctuation rule, and it did so in the following places:
Line 15, column 36
Line 59, column 15
Line 64, column 12
When the check has run you will get the total amount of errors, warnings, and suggestions including how many files have been checked.
Do not do this: "Members will only have access to CDN endpoints."
Do this: "Members will only have access to Content Delivery Network (CDN) endpoints."
Do not do this: YSOD (.Net error page)
Do this: YSOD: Yellow Screen of Death, .NET error page
Do not do this: "The next thing to do, is to navigate to the Content section"
Do this: "Navigate to the Content section"
Take a look at our collection of integrations that you can add to your Umbraco CMS website.
Overview of best practices that can be applied when developing digital experiences.
This section shows you some beginner tools and information to get your started with Umbraco. From making a local installation to extending the backoffice.
Looking to create a website with custom styling and tools? As a backend developer, you can follow our instructions to create a fully customizable website. You will learn things like how to set up your environments and how to implement your custom templates. You will find all the tools that you're going to need to install Umbraco and start developing immediately.
There are tutorials on how to inject dependencies, information about how the Umbraco pipeline works, and how you can customize it to fit your needs.
You can implement your own MVC controllers to work alongside Umbraco.
There are two concepts that are Umbraco specific which might prove useful to learn about:
Umbraco is composed of components. Programmatically you can add your own components and customize Umbraco at application startup.
When you're developing with Umbraco you might sometimes run into some errors and issues. Here are some guides to help you with the debugging:
Learn more about composing and components in the article.