Lazy-loaded content, which is replacing the main caching mechanism
Upgrading existing sites and making sure everything still works on the frontend
If you have any custom routing or controllers in place, do they still work as expected
Block-level variants
Making sure all of your existing blocks work after an upgrade
If you have a large block-based site, it is interesting to see if the upgrade doesn't take too long
Once you have done a round of thorough testing, make sure to as usual.
Making it count for Hacktoberfest
We really appreciate your help in testing this release. Make sure to describe to us in a bit of detail what you've tried, let us know a bit about the scale of project you're testing on, etc.
If everything "just" worked (🤞) then describe that as well! Let us know exactly what you focused on that worked well.
You can do this by heading to the repository and adding your name to the list in the "Low code/no code" section.
An example of a participation entry is:
- 2024-10-04 - Paula Philips - Umbraco 15 Release Candidate testing - Details in the PR description
In the description of the pull request to get your name added, put your test results as described above and link to any issues you've created if things didn't work as expected.
This would be a great use of , so you can work on testing and keep updating the description with your test results until you're done and ready to submit your final PR.
Packages
Packages are back on the menu - and yes, they also count as a contribution to Umbraco!
Here are some specific details on this:
Only contributions made to open-source Umbraco packages added to the Hacktoberfest Package repo list counts
Follow the contribution guidelines provided by the package creator
Look for the "help wanted" label on the issue tracker associated with the package you want to help out with
Note: Package contributions eligibility for swag differ slightly from those used for all contributions. Read more on the to learn more about how a contribution is marked as "swag-eligible".
Creating a brand-new package
Publishing a brand new package to will also count towards both DigitalOcean's and Umbraco's Hacktoberfest contributions ⭐🤩
Packages for Umbraco 14 and up are eligible by default, even if the equivalent package already exists for older Umbraco versions.
Low-code / no-code contributions
Back, by popular demand, we will also be rewarding contributions that are either low-code and more importantly: no-code!
Eligible contributions according to include:
Verifying documentation
Copy editing
User experience testing
Talks or presentations
We for you to record your contributions that are not a pull request.
In order to record your journey of verifying documentation (like related blog post(s) in October, events organized), edit the README.md file and add your activity at the end in the recommended format and submit that as a pull request. We’ll take it from there!
The teams at and are always looking for new articles. Finish your application October to make it count! We'll ask the Skrift/24 days teams to verify your application to write an article.
Sponsor an Umbraco-related GitHub repository
To appreciate people who maintain open-source projects for the Umbraco ecosystem, an easy way to help contribute is to give them some money! We’d suggest you have a look at your favorite packages and see if their repo/maintainer is accepting sponsorship.
We suggest you scroll through the , and see if your favorite packages/authors are open to sponsorship. Look for the heart icon.
If you're in doubt if your chosen sponsorship would count, then feel free to first , or ask in the #contributing channel.
Umbraco HQ , at $100 per month. These are excellent projects that could always use more sponsorships, but make sure to also consider other repositories, there are many great ones out there!
And the good news is: yes, you will be able to earn Umbraco swag, proportionate to your sponsorship amount.
How we judge a Hacktoberfest-eligible contribution
We use to qualify, so any contributions that do not follow these standards will also not count towards Umbraco swag. These rules are to ensure we get quality contributions and that the right efforts get rewarded 🙌
If you’re contributing to one of the open-source Umbraco Packages, check to learn more about how a contribution is marked as "swag-eligible".
Any questions?
In order to help you succeed we at HQ are trying to be available as much as possible during the month of October on Discord in the channel.
Whether you need some inspiration, guidance, help getting things to build, and so on - we’re there to support and guide you, together with the .
So come join us and the other 1500+ people already on the !
Happy Hacktoberfest! 🎃
Other ways to contribute
This document covers contributing to the codebase of the CMS but
If you don't feel you'd like to make code changes here, you can visit our and use your experience to contribute to making the docs we have, even better.
We also encourage community members to feel free to comment on others' pull requests and issues - the expertise we have is not limited to the Core Collaborators and HQ. So, if you see something on the issue tracker or pull requests you feel you can add to, don't be shy.
Contributing to Umbraco
There are many ways to contribute to Umbraco. The Contribution Documentation will show you where and how.
Whether you're a seasoned developer, a creative designer, or a passionate user, there are countless ways to contribute to the Umbraco project. From coding and bug reporting to sharing your insights and creating tutorials, your input helps us shape a better experience for everyone.
Why contribute to an open-source project?
There are plenty of great reasons to get involved in open-source projects, and when it comes to Umbraco, the benefits are even greater! Here’s why you should consider contributing:
Submit Feedback
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.
Submit Feedback on an Article
On the right-hand side of every article, you'll find an option to submit feedback directly related to that article.
Screenshot that shows the Discord #contributing channel
Expand your skill set: Gain valuable experience and learn new technologies.
Boost your career: Enhance your public résumé.
Build your network: Connect with fellow Umbraco enthusiasts and team members.
Learn and unlearn: Discover new insights and challenge your existing knowledge.
Make an impact: Your contributions can help thousands of users. Imagine saying, "I helped fix that bug!" 😎
Impact the planet: We plant a tree for each accepted contribution 🌳
Support the community: Help the hundreds of thousands of Umbraco users benefit from your efforts.
Give back: Contribute to the software you love or tackle that feature you've always wished was different!
So, let’s get those contribution hats on!
Where to contribute
Discover where you can make an impact and start contributing.
Documentation
First off, there's a lot of documentation, and it's not always easy to keep it updated or know if we covered all the details you need to know to follow them. We would love your help to verify the documentation. That is, to follow the docs to the letter and see if you’re successful or missing anything.
Find detailed instructions on how to contribute to the docs directly on the documentation site. Here, we have outlined the steps involved with testing and checking the articles against our style guide. In the same article, you can also learn much more about the rules we’re checking the docs against.
Fill out the form, answering the questions to explain your suggestion or problem clearly.
Submit the issue.
Unwanted changes
While most changes are welcome, there are certain types of changes that are discouraged and might get your pull request refused. This will depend heavily on the specific change, but take the following examples in mind.
Breaking changes (code and/or behavioral) 💥 - sometimes it can be a bit hard to know if a change is breaking or not. If it relates to code, the build will fail and warn you.
Large refactors 🤯 - the larger the refactor, the larger the probability of introducing new bugs/issues.
Changes to obsolete code and/or property editors ✍️
Adding new config options 🦾 - while having more flexibility is (most of the times) better, having too many options can also become overwhelming/confusing, especially if there are other (good/simpler) ways to achieve it.
Whitespace changes 🫥 - while some of our files might not follow the formatting/whitespace rules (old ones), changing many of them in one go would cause major merge conflicts with open pull requests or other work in progress. Do feel free to fix these when you are working on another issue/feature and end up "touching" those files!
Adding new extension/helper methods ✋ - keep in mind that more code also means more to maintain, so if a helper is only meaningful for a few, it might not be worth adding it to the core.
Adding new dependencies 🔒 - if you are in need of adding a new dependency for Umbraco CMS to take on, this should be discussed first; dependencies need to be updated and can lead to unwanted security issues, so we only take on what is absolutely necessary.
While these are only a few examples, it is important to ask yourself these questions before making a pull request:
How many will benefit from this change?
Are there other ways to achieve this? And if so, how do they compare?
How maintainable is the change?
How to Contribute
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 . The documentation is also available as a and is open-source, just like the .
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.
How to Get Started
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.
Submit a Pull Request
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.
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 common scenarios where you might want to add a new article to the Umbraco Documentation:
You are to the documentation site.
This includes topics or tutorials not previously covered..
What would be the effort to test it properly?
Do the benefits outweigh the risks?
Documentation
Umbraco-CMS
UI Library
Request a quick/minor change to an article by submitting a Pull Request.
Consistency and readability are important when writing and reading documentation. When you contribute, follow the style guidelines and rules outlined in the Style Guide.
Learn how we structure and name files in the Umbraco documentation.
Writing documentation locally
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.
Multi-version documentation
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.
An overview of the file structure in the UmbracoDocs GitHub repository.
Umbraco Cloud and Umbraco Heartcore are not documented by version, which is why they are separate from this structure.
You need a GitHub account to create a Pull Request.
Option 1: Creating a PR directly on GitHub
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.
Highlighting the Edit on GitHub button.
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.
Are you working on a larger update that includes pictures and editing multiple files? Create a fork and follow the approach outlined in Option 2: Creating a PR through a fork.
Option 2: Creating a PR through a Fork
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.
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:
What type of article are you going to be writing?
It could be a tutorial, a guide on how to solve something specific, or an article detailing a specific concept or workflow.
The type of article you are writing will determine the content and sometimes also the structure of the material.
Who is the audience of the article?
C# developers, newcomers to Umbraco, and content editors each have different approaches and prerequisites to using Umbraco and reading the documentation.
Knowing your audience will enable you to write in a manner that fits that particular group. It will also give you some pointers on what types of content should be your focus.
Where does the article fit into the existing structure?
Depending on which product you are adding new material for, the structure of the existing documentation will differ. We recommend browsing the existing material to figure out which section will be the best fit for your new article.
If you have doubts about where to place your article, the team at Umbraco HQ can help you out. In this case, add a note in the description when submitting the PR, letting us know that you need help placing the article.
The steps to create, write, and add a new article to the Umbraco Documentation are outlined below:
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 SUMMARY.md file so it appears in the documentation navigation.
Commit and push your changes to your forked 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 follow the versioning strategy:
Umbraco CMS
Umbraco Forms
Umbraco Deploy
Umbraco Workflow
Umbraco Commerce
Umbraco UI Builder
Umbraco Engage
The documentation site for a new major version is publicly available around the Release Candidate (RC) phase. The structure is set up typically 3-4 weeks before the final release.
Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.
Learn how to structure files and images when working with the Umbraco Documentation.
When contributing to the Umbraco documentation, it is useful to know how to structure directories, files, and images.
In this article, you'll get an overview of the file structure and learn about the naming conventions used for elements in the structure.
File names
How files, directories, and images are named is important for consistency, but also for ensuring continuous compatibility with GitBook, where the Documentation sites are hosted.
All file and directory names must use lowercase.
Exception: Name all parent articles README.md, and name the surrounding directory using the title of the README.md file.
Use hyphens (-) instead of spaces.
Use the title of the article when naming the associated file.
Give images descriptive names matching the content associated with them.
File structure
The overall structure of the Umbraco documentation is divided by version and product. Each Umbraco version has its own directory, and in those, each 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 and a parent page to all other articles added within.
Images are stored in the .gitbook/assets/ directory at the root of the repository. This is the recommended location for all images.
.gitbook(directory)
/assets(directory)
Many existing articles still reference images from a local /images/ directory next to the .md file. This structure remains valid while the documentation is being migrated to use .gitbook/assets/ directory.
Documentation Navigation
Independent of how the files are structured in the directories, it is the SUMMARY.md file that ultimately determines how the documentation navigation is displayed.
Each product directory has a SUMMARY.md file wherein all articles related to that product are listed.
It is possible to add groups to separate the article into sections. This is done using two # symbols followed by the section name: ## Fundamentals .
An article is not available on the public documentation site unless it is listed within the SUMMARY.md file.
Structural Changes
These changes include moving an article to a different section, renaming or deleting an article as well as adding a new article.
When either of the actions above occurs, it needs to be tracked in two files: .gitbook.yaml and SUMMARY.md.
Moving an article
When an article is moved to a different section/directory, follow these steps:
Update the relative path to the file in the closest SUMMARY.md file.
Move the article link in the SUMMARY.md file to the correct section.
Add a redirect to the redirects section of the closest
Renaming an article
When an article is renamed, follow these steps to track the changes:
Update the Title and the relative path to the file in the closest SUMMARY.md file.
Add a redirect to the redirects section of the closest .gitbook.yaml file.
Deleting an article
When an article is deleted from the documentation, follow these steps to avoid broken links:
Remove the file from the closest SUMMARY.md file.
Add a redirect to the redirects section of the closest .gitbook.yaml file.
Adding a new article
When a new article is added, it must also be added to the SUMMARY.md file to show up in the published documentation:
Add the article to the SUMMARY.md file like this:
Example: * [Article Title](path/to/article.md)
Before you start
Code of Conduct
This project and everyone participating in it, is governed by the [our Code of Conduct][code of conduct].
What can I contribute?
We categorise pull requests (PRs) into two categories:
PR type
Definition
We’re usually able to handle small PRs pretty quickly. A community volunteer will do the initial review and flag it for Umbraco HQ as “community tested”. If everything looks good, it will be merged pretty quickly [as per the described process][review process].
We would love to follow the same process for larger PRs but this is not always possible due to time limitations and priorities that need to be aligned. We don’t want to put up any barriers, but this document should set the correct expectations.
Not all changes are wanted, so on occasion we might close a PR without merging it but if we do, we will give you feedback why we can't accept your changes. So make sure to , so we can ensure that you don't put all your hard work into something we would not be able to merge.
Making larger changes
Please make sure to describe your larger ideas in an or , it helps to put in mock up screenshots or videos. If the change makes sense for HQ to include in Umbraco CMS we will leave you some feedback on how we’d like to see it being implemented.
If a larger pull request is encouraged by Umbraco HQ, the process will be similar to what is described in the small PRs process above, we strive to feedback within 14 days. Finalizing and merging the PR might take longer though as it will likely need to be picked up by the development team to make sure everything is in order. We’ll keep you posted on the progress.
Pull request or package?
If you're unsure about whether your changes belong in the core Umbraco CMS or if you should turn your idea into a package instead, make sure to .
If it doesn’t fit in CMS right now, we will likely encourage you to make it into a package instead. A package is a great way to check out popularity of a feature, learn how people use it, validate good usability and fix bugs. Eventually, a package could "graduate" to be included in the CMS.
Ownership and copyright
It is your responsibility to make sure that you're allowed to share the code you're providing us. For example, you should have permission from your employer or customer to share code.
Similarly, if your contribution is copied or adapted from somewhere else, make sure that the license allows you to reuse that for a contribution to Umbraco-CMS.
If you're not sure, leave a note on your contribution and we will be happy to guide you.
When your contribution has been accepted, it will be from that time onwards.
Finding your first issue: Up for grabs
Finding your first issue: Up for grabs
Umbraco HQ will regularly mark newly created issues on the issue tracker with . This means that the proposed changes are wanted in Umbraco but the HQ does not have the time to make them at this time. We encourage anyone to pick them up and help out.
If you do start working on something, make sure to leave a small comment on the issue saying something like: "I'm working on this". That way other people stumbling upon the issue know they don't need to pick it up, someone already has.
How to contribute
👍🎉 First off, thanks for taking the time to contribute! 🎉👍
These contribution guidelines are mostly just that - guidelines, not rules. This is what we've found to work best over the years, but if you choose to ignore them, we still love you! 💖 Use your best judgement, and feel free to propose changes to this document in a pull request.
Getting Started
We have a guide on and more detailed guides at the end of this article.
Bug fixes and small improvements - can be recognized by seeing a small number of changes and possibly a small number of new files.
Large PRs
New features and large refactorings - can be recognized by seeing a large number of changes, plenty of new files, updates to package manager files (NuGet’s packages.config, NPM’s packages.json, etc.).
When GitHub has created your fork, you can clone it in your favorite Git tool
Clone the fork
Switch to the correct branch
Switch to the main branch
Build
Build your fork of Umbraco locally as described in the build documentation: you can or .
Branch
Create a new branch now and name it after the issue you're fixing, we usually follow the format: temp-12345. This means it's a temporary branch for the particular issue you're working on, in this case issue number 12345. Don't commit to main, create a new branch first.
Change
Make your changes, experiment, have fun, explore and learn, and don't be afraid. We welcome all contributions and will .
Commit and push
Done? Yay! 🎉
Remember to commit to your new temp branch, and don't commit to main. Then you can push the changes up to your fork on GitHub.
Keeping your Umbraco fork in sync with the main repository
Once you've already got a fork and cloned your fork locally, you can skip steps 1 and 2 going forward. Just remember to keep your fork up to date before making further changes.
To sync your fork with this original one, you'll have to add the upstream url. You only have to do this once:
Then when you want to get the changes from the main repository:
In this command we're syncing with the main branch, but you can choose another one if needed.
To be honest, we don't like rules very much. We trust you have the best of intentions and we encourage you to create working code. If it doesn't look perfect then we'll happily help clean it up.
That said, the Umbraco development team likes to follow the hints that ReSharper gives us (no problem if you don't have this installed) and we've added a .editorconfig file so that Visual Studio knows what to do with whitespace, line endings, etc.
Questions?
You can get in touch with [the core contributors team][core collabs] in multiple ways; we love open conversations and we are a friendly bunch. No question you have is stupid. Any question you have usually helps out multiple people with the same question. Ask away:
If there's an existing issue on the issue tracker then that's a good place to leave questions and discuss how to start or move forward.
If you want to ask questions on some code you've already written you can create a draft pull request, detailed in a GitHub blog post.
Unsure where to start? Did something not work as expected? Try leaving a note in the "Contributing to Umbraco" forum. The team monitors that one closely, so one of us will be on hand and ready to point you in the right direction.
Clone
When GitHub has created your fork, you can clone it in your favorite Git tool or on the command line with git clone https://github.com/[YourUsername]/Umbraco-CMS.
Clone the fork
Switch to the correct branch
Switch to the main branch
Build
Build your fork of Umbraco locally as shown in the video below. You can build with any IDE that supports dotnet or the command line.
Branch
Create a new branch now and name it after the issue you're fixing, we usually follow the format: temp/12345. This means it's a temporary branch for the particular issue you're working on, in this case issue number 12345. Don't commit to main, create a new branch first.
Change
Make your changes, experiment, have fun, explore and learn, and don't be afraid. We welcome all contributions and will happily give feedback.
Commit and push
Done? Yay! 🎉
Remember to commit to your new temp branch, and don't commit to main. Then you can push the changes up to your fork on GitHub.
Create pull request
On GitHub, in your forked repository (https://github.com/[YourUsername]/Umbraco-CMS) you will see a banner saying that you pushed a new branch and a button to make a pull request. Tap the button and follow the instructions.
Want to read further? .
If you encounter errors while building the project, make sure you're using the latest supported versions of Node.js and npm.
Please review this document to help to streamline the process and save everyone's precious time.
This repo uses nodejs, so you should install nodejs as the package manager. See installation guide.
Guidelines for contributions that we welcome
Not all changes are wanted, so on occasion we might close a PR without merging it. We will give you feedback why we can't accept your changes and we'll be nice about it, thanking you for spending your valuable time.
Remember, it is always worth working on an issue from the Up-for-grabs list or even asking for some feedback before you send us a PR. This way, your PR will not be closed as unwanted.
Feature requests or ideas should be submitted and may then later be converted into an issue.
Ownership and copyright
It is your responsibility to make sure that you're allowed to share the code you're providing us. For example, you should have permission from your employer or customer to share code.
Similarly, if your contribution is copied or adapted from somewhere else, make sure that the license allows you to reuse that for a contribution to Umbraco.UI and Umbraco-CMS.
If you're not sure, leave a note on your contribution and we will be happy to guide you.
When your contribution has been accepted, it will be from that time onwards.
What can I start with?
Unsure where to begin contributing to the Umbraco UI library? You can start by looking through
Pull Requests (PRs)
We welcome all contributions. There are many ways you can help us. This is few of those ways:
Before you submit a new PR, make sure you run npm run test. PR must pass all the tests before it can get merged.
Reviewing PRs
As a PR submitter, you should reference the issue if there is one, include a short description of what you contributed and, if it is a code change, instructions for how to manually test out the change.
Please follow the pull request template you get provided when creating a pull request.
NOTE: Although the latest released version of Umbraco UI corresponds to the main branch, then development happens in the dev branch. If you submit a PR, branch off dev and target your PR to dev.
Development Guide
The UI Library components are built with and Typescript. Lit is a light-weight base class that makes development of web components easier and handles all the necessary things, attaching shadow root, reactivity, attribute reflection etc. We strongly encourage you to take a look at Lit documentation before starting development.
Using Typescript is mandatory when contributing to this repository, although it is not necessary to use it when consuming the components.
How to get started
Make sure you have the recommended version of node.js and npm installed
Currently we use node.js v16 and npm v8
Run npm install
New component
You can create a new component and that way contribute to the UI library. But before you do that, go to the folder and check if it's not already there. You can also look at the for an inspiration, where you can check what component is in what stage.
Package anatomy
Each component is a separate npm package and has a fixed file structure that looks as follows:
packages
new-component-name
lib
To scaffold these files run:
tsconfig.json file is generated automatically when the postinstall script runs.
Properties and attributes
are what creates the component's public api API. They all have corresponding attribute, through which the property can be initialized when the custom element gets instantiated and connected to the DOM. By default the property is not reflected to the attribute, meaning if property value changes the attribute in the markup will keep its initial value, but it will stay observed - changing its value wil change the property. , and used for styling purposes for example.
Each property you create should be documented with a jsdoc snippet. You can see an example of a property below.
Best practices for contributing to this library
Properties should only use attr-reflection for styling - don’t map component-state to classes - use attr-reflection!
New dependencies can only be added by HQ-team and only after scrutinizing debate (to keep size down)
Components versions can only be bumped by HQ-team
Before a new element can me merged
Element name must be prefixed with “UUI-”.
Element must have tests and pass them.
Element must pass basic Accessibility tests.
Have A Question?
A feature suggestion? Or maybe you think we could do something in other way? Start by filing an issue.
/**
* Disables the button, changes the looks of it and prevents if from emitting the click event
* @type {boolean}
* @attr
* @default false
*/
@property({ type: Boolean, reflect: true })
disabled = false;
Learn how to use Markdown to write articles for the Umbraco Documentation.
The Umbraco Documentation is written in Markdown.
In this article, you can learn how Markdown is used for adding different elements to the articles.
Headings
To create a heading, add between one to four # symbols before your heading text. The number of # you use will determine the hierarchy level and size of the heading.
The Article Title (#) must be used only once. All other headings should follow the correct hierarchical order.
When two or more headings are used in an article, they will be used to generate a table of contents on the right side of the article. Heading 3 will not be shown in the table of contents.
Styling text
Style
Syntax
Example
Output
Links
In the following, you will find a few examples of different links.
External links
Include either the complete URL using the following syntax:
All external links open in a new browser tab.
Internal links
When linking between pages in the documentation, use relative paths.
Link to an article in the same directory as the current article:
Link to an article in a different directory than the current article:
Page Links
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:
Link Text
Use the title of the article that is linked to as the link text. This is done to tell the reader what they will find on the other end.
Do not use "here" or "link" as the link text, as this provides no information about the destination.
⛔ Learn more about Document Types .
✅ Learn more about Document Types in the article.
Images
Images used in documentation articles must always be added to the repository. Use relative paths when referencing images in an article.
Always provide alt text. Add a caption where it helps the reader understand the context.
Image Location
GitBook, the platform used to host the Umbraco Documentation, automatically places images uploaded through its web editor into a top-level .gitbook/assets/ directory. For more information, see the article.
Many existing articles still reference images from a local /images/ directory next to the article. Both locations are valid while the documentation is being cleaned up to use the .gitbook/assets/ directory.
Syntax
Use the full <figure> block to include both alt text and a visible caption:
Alt text (alt=""): is read by screen readers and displayed if the image fails to load. Describe what the image shows.
Caption (<figcaption>): is visible text rendered below the image. Use it to explain why the image is there or what the reader should notice.
For simple inline images where no visible caption is needed, the short Markdown syntax is acceptable:
Format
Use .png for screenshots and .svg for diagrams and icons. .svg ensures scalability. .png preserves sharp edges in UI captures. Avoid .jpeg for screenshots.
Best practices
Use clear and descriptive filenames. Example: dashboard-view.png instead of image1.png.
Avoid placing large amounts of text in images. Provide any necessary text in the article instead.
Crop screenshots tightly to the relevant UI area.
Write alt text that describes what the image shows and why it is there, not just "screenshot". Keep the text under 125 characters.
Images in lists
When a screenshot or diagram accompanies a step in a numbered or bulleted list, it must be added on a new line. A blank line after the image is required. GitBook will handle indentation automatically.
Notes and Warnings
Four types of hints can be added to our documentation: info, success, warning, and danger.
.
Advanced Blocks
It is possible to add more advanced elements such as Expandables and Tabs. These are created using specific GitBook syntax
Learn more about how to work with these elements on the official GitBook documentation:
Avoid editing the HTML used to generate on landing pages in the Umbraco Documentation.
To request changes, contact the Umbraco HQ Documentation Team.
Code Samples
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.
This article provides guidelines for formatting and using code samples in the Umbraco Documentation.. You will find definitions and examples of the most commonly used types of code samples.
Example
Building the codebase
Are you sure?
In order to use Umbraco as a CMS and build your website with it, you should not build it yourself. If you're reading this then you're trying to contribute to Umbraco or you're debugging a complex issue.
Are you about to ?
This is italic.
When using annotations (arrows, boxes), keep them simple and use consistent Umbraco Colors.
<figure>
<img src="images/content-dashboard.png" alt="The Content dashboard showing three published pages.">
<figcaption>
<p>The Content dashboard in the Umbraco backoffice.</p>
</figcaption>
</figure>
1. Open the **Content** section.
2. Click **Create**.
Markdown
Good practices
To ensure quality and consistent code samples, follow these best practices when adding code snippets:
Code samples without context, explanations, and instructions can lead to issues when used.
Always add a clear description of what the code sample showcases when adding a snippet to an article. It should be clear where and when the snippet can be used.
Add a Caption (file name)
Inform 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.
If the code snippet is from a .cs file, add fileName.cs as the caption.
Example:
Screenshots of a code snippet where the file name is defined using the caption.
Markdown example:
Use code comments
When adding code samples that contain more than a single feature or method, it is recommended to add inline comments.
By adding inline comments, you avoid having too much text surrounding the code sample. You also help readers understand the code snippet in detail.
Use real-life samples
The documentation often aims to explain complex scenarios and concepts within Umbraco. Code samples can be useful to improve understanding. The code samples should, where possible, be 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.
To keep the code sample as neutral and general as possible, make it a habit to use placeholders for names, methods, and the like.
With Umbraco, there are often more than one way to achieve a result. It depends on context and the skillset of the development team. Providing multiple examples can help prevent readers from mixing techniques in their solution. An example could be providing a Models Builder version and a non-Models Builder version when documenting Templates.
Add correct syntax highlighting
When you add code blocks to an article, make sure to add the correct syntax highlighting. This will "prettify" the code in the sample based on which language is used.
Syntax highlighting makes the code snippet easier to read, as it allows the reader to distinguish between the different code elements.
Example:
Example of a code snippet that uses the correct syntax highlighting.
Example of a code snippet that is missing syntax highlighting.
Markdown example:
If the language used in a snippet isn't supported, use none.
Add only complete compilable samples
A reader of the Umbraco Documentation should be able to grab code samples in the articles and apply them directly to their solution. The code in the sample should compile.
Include any relevant Using statements for namespaces that provide 'extension' methods and key functionality.
Check for syntax errors
When reading any piece of text, it can be frustrating to run 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.
Use File-Scoped Namespaces
The use of file-scoped namespaces improves the readability of the code samples. Use file-scoped namespaces in the examples. Below is an example of how to use file-scoped namespaces:
With File-Scoped Namespace
Without File-Scoped Namespace
Use line numbers only when relevant
It is recommended to use line numbers only when you will be adding text that references specific lines and elements in a larger code snippet.
Example:
An image of a code samples that uses line numbers.
Markdown example:
When to use code samples
Code samples are relevant for most types of articles. Potentially, any topic covered could benefit from a real-life code sample to support the article content.
In most cases, you will want to base an article on a single code sample. If you're describing a flow or feature, you will, however, want to add smaller code snippets to highlight specific points.
Types of samples
The Umbraco Documentation operates with three types of code samples.
Inline code
Use inline code when:
Referencing methods.
Using the names of certain code elements.
Highlighting a certain value.
Example:
The markdown above will output the following:
Example of inline code
Smaller code snippets
As part of longer articles or tutorials, use smaller code snippets to highlight what must 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 confuse the flow of the article.
Example:
The Razor snippet above will output the following:
Example of smaller code snippet
Large code samples
As part of tutorials and longer articles covering a specific workflow, it might make sense to add longer code snippets or even entire files.
It is recommended to add longer code snippets into Expandables using the file name as the title. When adding code snippets into expandables, the reader can expand the code only when they are ready.
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.
Are you trying to get to the bottom of a problem in your existing Umbraco installation?
If the answer is yes, read on. Otherwise, make sure to head on over to the download page and start using Umbraco CMS as intended.
Getting Started
To run Umbraco, initialize the client git submodule:
Execute git submodule update --init to get the files into \src\Umbraco.Web.UI.Client folder.
This can be executed in the root folder of your cloned repository.
If you are going to run Umbraco for testing, execute dotnet run inside the \src\Umbraco.Web.UI folder.
If you are going to work on the Backoffice, you can either go to the \src\Umbraco.Web.UI.Client folder and check out a new branch or set it up in your IDE, which will allow you to commit to each repository simultaneously:
Rider: Preferences -> Version Control -> Directory Mappings -> Click the '+' sign
If you get a white page, delete \src\Umbraco.Cms.StaticAssets\wwwroot\umbraco folder and run npm ci && npm run build:for:cms inside the src\Umbraco.Web.UI.Client folder to clear out any leftover files from older versions.
Latest version
If you want to get the latest changes from the client repository, run git submodule update again which will pull the latest main branch.
Open the root folder of the repository in Visual Studio Code.
To build the front end you'll need to open the command pallet (Ctrl + Shift + P) and run >Tasks: Run Task followed by Client Watch and then run the Client Build task in the same way.
You can also run the tasks manually on the command line:
If you just want to build the UI Client to Umbraco.Web.UI then instead of running dev, you can do: npm run build.
The login screen is a different frontend build, for that one you can run it as follows:
If you just want to build the Login screen to Umbraco.Web.UI then instead of running dev, you can do: npm run build.
The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.
To run the C# portion of the project, either hit F5 to begin debugging, or manually using the command line:
The initial C# build might take a _really_** long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a starter kit to ease your debugging.
Debugging with Visual Studio
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
The easiest way to get started is to open umbraco.sln in Visual Studio.
To build the front end, you'll first need to run cd src\Umbraco.Web.UI.Client && npm install in the command line (or cd src\Umbraco.Web.UI.Client; npm install in PowerShell). Then find the Task Runner Explorer (View → Other Windows → Task Runner Explorer) and run the build task under Gulpfile.js. You may need to refresh the Task Runner Explorer before the tasks load.
If you're working on the backoffice, you may wish to run the dev command instead while you're working with it, so changes are copied over to the appropriate directories and you can refresh your browser to view the results of your changes.
The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.
"The rest" is a C# based codebase, which is mostly ASP.NET Core MVC based. You can make changes, build them in Visual Studio, and hit F5 to see the result.
The initial C# build might take a _really_** long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a starter kit to ease your debugging.
Do note that this is only required if you want to test out your custom changes in a separate site (not the one in the Umbraco.Web.UI), if you just want to test your changes you can run the included test site using: dotnet run from src/Umbraco.Web.UI/
You may want to build a set of NuGet packages with your changes, this can be done using the dotnet pack command.
First enter the root of the project in a command line environment, and then use the following command to build the NuGet packages:
dotnet pack -c Release -o Build.Out
This will restore and build the project using the release configuration, and put all the outputted files in a folder called Build.Out
You can then add these as a local NuGet feed using the following command:
dotnet nuget add source <Path to Build.Out folder> -n MyLocalFeed
This will add a local nuget feed with the name "MyLocalFeed" and you'll now be able to use your custom built NuGet packages.
Cleaning up
Once the solution has been used to run a site, one may want to "reset" the solution in order to run a fresh new site again.
The easiest way to do this by deleting the following files and folders:
src/Umbraco.Web.UI/appsettings.json
src/Umbraco.Web.UI/umbraco/Data
You only have to remove the connection strings from the appsettings, but removing the data folder ensures that the sqlite database gets deleted too.
Next time you run a build the appsettings.json file will be re-created in its default state.
This will leave media files and views around, but in most cases, it will be enough.
To perform a more complete clear, you will want to also delete the content of the media, views, scripts... directories.
The following command will force remove all untracked files and directories, whether they are ignored by Git or not. Combined with git reset it can recreate a pristine working directory.
Umbraco uses Azure DevOps for continuous integration, nightly builds and release builds. The Umbraco CMS project on DevOps is available for anonymous users..
The produced artifacts are published in a container that can be downloaded from DevOps called "nupkg" which contains all the NuGet packages that got built.
Quirks
Git Quirks
Git might have issues dealing with long file paths during build. You may want/need to enable core.longpaths support (see this page for details).
Gulp Quirks
You may need to run the following commands to set up gulp properly:
Each item is treated as a standard `IPublishedElement` entity, which means you can use all the value converters you are used to using.
@{
// Perform an null-check on the field with alias 'pageTitle'
if (Model.HasValue("pageTitle")){
// Print the value of the field with alias 'pageTitle'
<p>@(Model.Value("pageTitle"))</p>
}
}
Keep the Umbraco documentation accessible, consistent, and readable by following the style guide defined in this article.
To ensure that the documentation is readable and has a similar style throughout, follow the guidelines outlined in this article. A GitHub bot will check PRs for broken rules and advise you on what to change.
Text Formatting
Below you will find a description of each rule the Umbraco Documentation follows.
Avoid Punctuation in Headings
Don't use 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:
?
:
.
Avoid Double spacing
To ensure readability and consistency, this rule will warn you if you have more than one space in a row in your text.
Use Lists when Listing more than 2 Items/Steps
There are two types of commonly used lists in the Umbraco documentation: ordered lists and unordered lists.
Use ordered lists for sequential task steps.
Use unordered lists for sets of options, notes, criteria, and the like.
Start lists with capital letters.
Ordered lists
To keep ordered lists short and to the point, follow these guidelines:
Start each item on the list with the action word.
⛔ The next thing to do, is to navigate to the Content section.
✅Navigate to the Content section.
Language
Write in the second person
Address the reader directly using "you".
⛔ The user should add the Document Type by clicking the Add button.
✅ You can add the Document Type by clicking…
Use the present tense and active voice
Use the present tense for statements that describe general behavior that's not associated with a particular time.
⛔ The Document Type was added…
✅ The Document Type is added...
Avoid Editorializing
The words in the list below will cause a warning when included in your contribution.
Avoid using the following 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
Avoid Long sentences
This rule flags any sentence longer than 25 words. Shorter sentences improve clarity and readability.
The rule is added to improve the readability of the documentation. When a sentence is longer than 25 words, the readability is degraded. This is especially true for technical content that is meant to be instructional.
Avoid using "it" or "this" as references
To avoid confusion, don't use "it" or "this" to refer to an action or item referenced at an earlier point. The only exception to this rule is when used within the same sentence.
⛔ This can now be configured.
✅ The Document Type can now be configured.
Terms and Names
Terms (general)
This rule flags any use of discouraged terms in the Umbraco Documentation.
Example: The term blacklist must be avoided and replaced with deny list.
For a full list of terms, check the .
Umbraco Terms
This rule is added to ensure that Umbraco-specific terms and names are spelled and used consistently throughout the documentation.
The list of Umbraco Terms includes, but is not limited to Umbraco, backoffice, Document Type, and Umbraco Forms.
Acronyms
All first-time uses of an acronym in an article 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 are defined using either a parenthesis or a colon followed by the definition.
Examples of the use of acronyms:
⛔ Members will only have access to CDN endpoints.
✅ Members will only have access to Content Delivery Network (CDN) endpoints.
⛔YSOD (.Net error page)
✅YSOD: Yellow Screen of Death, .NET error page
Names
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.
Brands
In some cases, throughout the documentation, other software providers or brands are referenced. This rule is added 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.
Test the documentation yourself
One of the big strengths of Vale is that it is possible for a contributor to run the tests locally before creating a PR. Below are a couple of options on how to test the documentation.
Visual Studio Code extension
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 article.
Use Vale locally
The first step to running Vale locally is to install it following Vale's .
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:
An exception to this rule would be when listing method names that use camelcase. In this case, highlight the names using in-line code formatting.
Add a maximum of two actions per list item.
Keep each list item short and to the point.
Add additional information in one or more sub-list items.
Actually
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:
It will show you what file has issues. In the case above the v8documentation.md the article broke the , 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.
