Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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:
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!
Discover where you can make an impact and start contributing.
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 . 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.
Head on over to for the full details.
There are plenty of to look at - a great starting point if you’re not quite sure where to start.
We're also happy for you to work on translations or other problems you might know of that are not on the issue tracker yet.
Head on over to for the full details.
The UI library contains all the UI elements for the backoffice. These are self-contained components that can be used in any project that needs a UI.
Head on over to for the full details.
We have general contribution guidelines available for Umbraco-CMS, the backoffice project, the UI library and documentation.
Specificially for Hacktoberfest, we have a lot more things you can get involved in!
One of our main focus areas for 2024 is to deeply test out the major new features of Umbraco v15. The release candidate for the upcoming Umbraco v15 is available now and we encourage you to test the main new features, namely:
The new Rich Text Editor (RTE)
Migrating existing RTEs to the new RTE datatype
Working with the new RTE
Extending the new RTE
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
Try out the new ISeedKeyProvider, IDocumentServices
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
Add variants to your existing or new blocks and start using them: edit, save, publish, etc
Once you have done a round of thorough testing, make sure to as usual.
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.
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
Read much more about how this works, and guidelines on adding your own package repo to .
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".
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.
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!
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.
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".
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! 🎃
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.
On the right-hand side of every article, you'll find an option to submit feedback directly related to that article.
IDistributedCachePodcasts
Case studies
Organizing Hacktoberfest events
Sharing your feedback helps the team at Umbraco HQ provide better material across the products.
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 contributors.
Here are a few examples of when to create an issue:
You are looking for a specific piece of information, but can't find it.
You've found a broken link in one of the articles, but don't know how to fix it.
An article contains outdated or incorrect information, and you don't have time or knowledge to submit a PR.
You would like to propose a new section or discuss improvements to existing documentation.
Go to the Issue Tracker on GitHub.
Select New Issue.
Fill out the form, answering the questions to explain your suggestion or problem clearly.
Submit the issue.
This document covers contributing to the codebase of the CMS but the community site has plenty of inspiration for other ways to get involved.
If you don't feel you'd like to make code changes here, you can visit our documentation repository 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.
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.
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 or 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.
Consistency and readability are important when writing and reading documentation. When you contribute, follow the style guidelines and rules outlined in the Style Guide.
The Umbraco Documentation is written using the Markdown markup language.
Learn how we structure and name files in the Umbraco documentation.
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.
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.
Umbraco Cloud and Umbraco Heartcore are not documented by version, which is why they are separate from this structure.
Learn more about how versioning is managed in the Documenting multiple versions and products article.
On both Issues and Pull Requests, labels are used to categorize the requests and submissions.
Here's a quick explanation of the labels (colors):
Category
category/missing-documentation
category/umbraco-cloud
category/pending-release
Community
community/pr
help wanted
State
state/hq-discussion
Status
status/awaiting-feedback
status/idea
Type
type/bug
Internal Review
review/docsteam
review/developer
Labels are added during the initial review of your pull request or issue.
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?
What would be the effort to test it properly?
Do the benefits outweigh the risks?
Small PRs
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.).
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 talk to us before making large changes, so we can ensure that you don't put all your hard work into something we would not be able to merge.
Please make sure to describe your larger ideas in an issue (bugs) or discussion (new features), 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.
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 talk to us.
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.
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 MIT licensed from that time onwards.
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.
You can submit a PR directly from our . 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.
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.
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.
There are a lot of great tutorials available online on .
Ensure Git is installed on your machine.
Go to the .
Select Fork in the top-right corner to create a personal copy of the repository.
Once the fork is created:
Clone your fork to your local machine.
Make your changes in a local branch.
If you add a new article, update the SUMMARY.md file to include it in the documentation navigation.
Sync your changes back to your fork.
To sync via command line:
Set the original repository (UmbracoDocs) as an upstream to sync from.
Fetch the updates.
Update your own fork.
To sync via GitHub:
Use the Sync fork option when your fork is behind the original repository.
Once you have made changes and are happy with the result, you can create a PR.
Navigate to the Code section of your fork.
Select Contribute > Open pull request.
Add a title and description explaining your changes.
Select Create pull request to submit a PR to the original repository.
Your PR will be reviewed by the documentation team at Umbraco HQ.
Review times can vary based on the size and complexity of the contribution—from a few minutes to several weeks.
Umbraco HQ will regularly mark newly created issues on the issue tracker with the community/up-for-grabs tag. 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.
Great question! The short version goes like this:
Fork
Create a fork of
Clone
When GitHub has created your fork, you can clone it in your favorite Git tool
Switch to the correct branch
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.
Style guide
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, .
Unsure where to start? Did something not work as expected? Try leaving a note in the forum. The team monitors that one closely, so one of us will be on hand and ready to point you in the right direction.
👍🎉 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.
We have a guide on what to consider before you start and more detailed guides at the end of this article.
The following steps are a quick-start guide:
Fork
Create a fork of
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.
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 .
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.
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.
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.
When images are used, they must be in an images directory next to the .md file referencing them using relative paths.
/topic (directory)
README.md (landing page/parent article)
another-article.md
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.
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.
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 .gitbook.yaml file.
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.
Example: path/to/current-name: path/to/new-name.md
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.
Point to either the article's replacement or to the parent 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)
/images (directory)
images.png
/subtopic (directory)
README.md (landing page/parent article)
article.md
another-article.md
/images (directory)
Example: relative/path/to/current/location: relative/path/to/new/location.md
Example: path/to/article: path/to/new-article-or-parent.md
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.
Switch to the main branch
Build
Build your fork of Umbraco locally as described in the build documentation: you can debug with Visual Studio Code or with Visual Studio.
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.
git remote add upstream https://github.com/umbraco/UmbracoDocs/
git fetch upstream
git rebase upstream/maingit remote add upstream https://github.com/umbraco/Umbraco-CMS.gitgit fetch upstream
git rebase upstream/mainDone? 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? Creating a pull request and what happens next.
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.
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.
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.
To ensure quality and consistent code samples, follow these best practices when adding code snippets:
Each guideline is explained in more detail below.
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.
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:
Markdown example:
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.
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.
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:
Markdown example:
If the language used in a snippet isn't supported, use none.
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.
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.
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:
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:
Markdown example:
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.
The Umbraco Documentation operates with three types of code samples.
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:
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:
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.
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.
Bold
** ** or __ __
This is **bold**.
This is bold.
Italic
* * or _ _
This is *italic*.
This is italic.
In the following, you will find a few examples of different links.
Include either the complete URL using the following syntax:
All external links open in a new browser tab.
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:
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:
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 here.
✅ Learn more about Document Types in the Defining Content article.
Images used in documentation articles must always be added to the repository as well. Learn more about where to add the images in the File Names and Structure article.
Use relative paths when referencing images in an article.
Use descriptive alt text and captions to enhance accessibility and Search Engine Optimization (SEO) benefits.
Use clear and relevant filenames. Example: dashboard-view.png instead of image1.png.
Avoid placing large amounts of text in images. If text is required, provide it in the article instead.
Use SVG format for diagrams and icons where possible to ensure scalability.
Four types of hints can be added to our documentation: info, success, warning, and danger.
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 Cards on landing pages in the Umbraco Documentation.
To request changes, contact the Umbraco HQ Documentation Team.
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 as a discussion first and may then later be converted into an issue.
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 MIT licensed from that time onwards.
Unsure where to begin contributing to the Umbraco UI library? You can start by looking through these Up-for-grabs issues
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.
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
mainbranch, then development happens in thedevbranch. If you submit a PR, branch offdevand target your PR todev.
The UI Library components are web components built with Lit 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.
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
Run npm run storybook to start the storybook server, which we also use for development
You can create a new component and that way contribute to the UI library. But before you do that, go to the packages folder and check if it's not already there. You can also look at the Components list 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
index.ts
new-component-name.element.ts
new-component-name.test.ts
new-component-name.story.ts
package.json
README.md
rollup.config.js
tsconfig.json
To scaffold these files run:
tsconfig.json file is generated automatically when the postinstall script runs.
Reactive properties 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. Attributes can also be reflected, 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.
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
Components can’t assume Umbraco context
Elements shouldn’t depend on TagNames - their own or children - instead use :host or this and use classes/id’s for selection
Elements always use a shadow-root (shadowDOM - for encapsulation)
Styles should have as simple rules as possible
UI-events should be unique types that extend from our UUIEvent (see uui-base package) (for typing reasons)
When applicable, elements should follow
Element name must be prefixed with “UUI-”.
Element must have tests and pass them.
Element must pass basic Accessibility tests.
Element must have a storybook setup.
Source-code must follow the ES-lint rules.
A feature suggestion? Or maybe you think we could do something in other way? Start by filing an issue.
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.
Below you will find a description of each rule the Umbraco Documentation follows.
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:
?
:
.
To ensure readability and consistency, this rule will warn you if you have more than one space in a row in your text.
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.
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.
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.
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 for statements that describe general behavior that's not associated with a particular time.
⛔ The Document Type was added…
✅ The Document Type is added...
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
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.
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.
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 .
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.
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
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 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.
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.
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 create a pull request for Umbraco?
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 and start using Umbraco CMS as intended.
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 want to get the latest changes from the client repository, run git submodule update again which will pull the latest main branch.
Did you read ?
If you want to run a build without debugging, see below. This runs the build in the same way it is run on our build servers.
In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
npm v7+ (installed with Node.js)
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.
You might run into .
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to to help you to see the changes you're making.
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 to ease your debugging.
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
( for you to use to contribute to Open Source projects)
npm v7+ (installed with Node.js)
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.
You might run into .
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to to help you to see the changes you're making.
"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 to ease your debugging.
Did you read ?
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.
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.
For git documentation see:
git
git
Umbraco uses Azure DevOps for continuous integration, nightly builds and release builds. The Umbraco CMS project on DevOps ..
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.
Git might have issues dealing with long file paths during build. You may want/need to enable core.longpaths support (see for details).
You may need to run the following commands to set up gulp properly:
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 adding new material to the documentation site.
This includes topics or tutorials not previously covered..
You are updating an existing article for an Upcoming major version of a product.
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 new article to the Umbraco Documentation are outlined below:
Access the repository.
Fork the repository.
Clone your fork to your local machine.
Create a new branch using the following naming convention: productname/topic
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 following sections of the Umbraco Documentation follow the versioning strategy:
Umbraco CMS
Umbraco Forms
Umbraco Deploy
Umbraco Workflow
Once the RC is released, you can find the associated documentation using the version drop-down on the Documentation site.
Access the repository.
Fork the repository.
Clone your fork to your local machine.
Create a new branch using the following naming convention: productnameXX/topic
@if (Model.ColorTheme != null)
{
var value = Model.ColorTheme;
<p>@value</p>
}{% code caption="HomePageTemplate.cshtml %}
```csharp
@if (Model.HasValue("colorTheme"))
{
var value = Model.Value("colorTheme");
<p>@value</p>
}
```
{% endcode %}{% code caption="ErrorController.cs" %}
```csharp
...
```
{% endcode %}{% code caption="ErrorController.cs" %}
```csharp
using Microsoft.AspNetCore.Mvc;
namespace YourProjectNamespace.Controllers;
...
```
{% endcode %}namespace MyProject;
public class Umbraco
{
}namespace MyProject
{
public class Umbraco
{
}
}{% code title="UmbracoAppAuthenticatorComposer.cs" lineNumbers="true" %}
```csharp
namespace My.Website;
...
```
{% endcode %}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>
}
}# Article Title
## Heading 1
### Heading 2
#### Heading 3[yahoo something](https://yahoo.com/something)[Article Title](article.md)[Article Title](../../reference/article.md){% content-ref url="issues.md" %}
[Article Title](issues.md)
{% endcontent-ref %}// Block with Caption
// Block with Alt text
<figure><img src="images/sample.png" alt="This is a sample Alt text"></figure>
// Block with Caption and Alt text
<figure>
<img src="images/sample.png" alt="This is a sample Alt text">
<figcaption>
<p>This is a sample Caption</p>
</figcaption>
</figure>npm run new-package
npm i /**
* 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;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.
Umbraco UI Builder
Umbraco Engage
Branch name example: cms15/configuration
Locate the article you need to make changes to.
Make the necessary changes to the article.
Add and commit the changes.
Push the branch to your forked repository.
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.
cd src\Umbraco.Web.UI.Client
npm i
npm run devcd src\Umbraco.Web.UI.Login
npm i
npm run devdotnet watch --project .\src\Umbraco.Web.UI\Umbraco.Web.UI.csprojgit clean -xdf .npm cache clean --force
npm ci
npm run buildKeep each list item short and to the point.
Add additional information in one or more sub-list items.
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:
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.
