Merge branch 'main' into 15/formsLaunchPrep

Author: sofietoft

14/umbraco-cms/SUMMARY.md

@@ -136,7 +136,7 @@
   * [Circular Dependencies](implementation/services/circular-dependencies.md)
 * [Unit Testing](implementation/unit-testing.md)
 
-## Customize the Backoffice
+## Customizing
 
 * [Extend and customize the editing experience](customizing/overview.md)
 * [Project Bellissima](customizing/project-bellissima.md)

15/umbraco-cms/README.md

@@ -23,3 +23,29 @@ Umbraco CMS is a flexible and editor-friendly Content Management System (CMS) th
 Learn more about Umbraco CMS and get an overview of the top features on [Umbraco.com](https://umbraco.com/products/umbraco-cms/).
 
 <table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Fundamentals</strong></td><td>Learn the basics of working with Umbraco CMS. How to install and setup your first site is also included in this section.</td><td><a href=".gitbook/assets/rocket-hero.png">rocket-hero.png</a></td><td><a href="fundamentals/get-to-know-umbraco.md">get-to-know-umbraco.md</a></td></tr><tr><td><strong>Install Umbraco CMS</strong></td><td>Ready to get started with Umbraco? Head over to the Setup section to learn how to install Umbraco CMS.</td><td><a href=".gitbook/assets/docs-style-hero.png">docs-style-hero.png</a></td><td><a href="fundamentals/setup/install/">install</a></td></tr><tr><td><strong>Tutorials</strong></td><td>Find detailed step-by-step guides on everything from building a site from scratch to implementing a custom maintenance page.</td><td><a href=".gitbook/assets/reversed-heart-hero.png">reversed-heart-hero.png</a></td><td><a href="tutorials/overview.md">overview.md</a></td></tr></tbody></table>
+
+The documentation for Umbraco CMS provides information for experienced Umbraco and .NET developers. It also offers guides and high-level articles for people starting out with the CMS.
+
+{% content-ref url="tutorials/creating-a-basic-website/" %}
+[creating-a-basic-website](tutorials/creating-a-basic-website/)
+{% endcontent-ref %}
+
+{% content-ref url="reference/configuration/" %}
+[configuration](reference/configuration/)
+{% endcontent-ref %}
+
+{% content-ref url="fundamentals/setup/requirements.md" %}
+[requirements.md](fundamentals/setup/requirements.md)
+{% endcontent-ref %}
+
+{% content-ref url="reference/notifications/" %}
+[notifications](reference/notifications/)
+{% endcontent-ref %}
+
+***
+
+## Umbraco Training
+
+Umbraco HQ offers a full-day training course covering the basic concepts and features needed for building an Umbraco CMS website. The course targets frontend and backend developers, designers, and technical users who want to build a website from scratch in Umbraco,
+
+[Explore the Fundamentals Training Course](https://umbraco.com/training/course-details/fundamentals-details/) to learn more about the topics covered and how it can enhance your Umbraco development skills.

15/umbraco-cms/SUMMARY.md

@@ -0,0 +1,68 @@
+---
+description: An intro to achieving content variance at block level.
+---
+
+# Block Level Variance
+
+In a variant context, a Block Editor behaves like any other Umbraco property editor by default. The Blocks contained within the editor "belong" to the Document variant, and there is no connection between Blocks across variants.
+
+In other words, both Block content and structure can vary between each Document variant.
+
+![Default Block Editor behavior in the backoffice](images/block-level-variance-1.png)
+
+This is the desired behavior for many cases. However, in some cases it is preferable to have a shared Block structure across all variants, where only the Block content varies.
+
+This is known as Block Level Variance:
+
+![Block Level Variance in the backoffice](images/block-level-variance-2.png)
+
+Block Level Variance is achieved when:
+
+* The [Document Type](../../../../data/defining-content/default-document-types#document-type) is configured for variance, and
+* The Block Editor property is _not_ configured for variance, and
+* The Block Editor property editor is configured to use [Element Types](../../../../data/defining-content/default-document-types#element-type) that _do_ vary.
+
+## The "unexposed" Block state
+
+When adding a new _variant_ Block to one Document variant, it is automatically added to all variants of the Document.
+
+The Block will start out in an "unexposed" state for all other Document variants than the one where it was added. It will remain like that for each variant until it is edited in that variant.
+
+The "unexposed" state is visualized by a dimmed-down icon and title (or likely a missing title, if [Umbraco Flavored Markdown](../../../../../reference/umbraco-flavored-markdown.md) is used):
+
+![Block Level Variance in the backoffice - with an unexposed block](images/block-level-variance-3.png)
+
+{% hint style="info" %}
+"Unexposed" Blocks are omitted from the published Document output. So, you do not need to worry about defensive coding to avoid rendering these Blocks.
+{% endhint %}
+
+## Invariance vs. Block Level Variance
+
+It is entirely possible to mix and match variance and invariance within the scope of Block Level Variance. Invariance is fully supported, both at Block level and at Block property level.
+
+Invariance within Block Level Variance follows the same rules as invariance at Document level:
+
+- Invariant content is added to and updated across all Document variants.
+- Invariant content is explicitly published for all published Document variants when one or more variants are published.
+
+### Examples
+
+Consider a Document with English and Danish language variants, which is published in both languages.
+
+- An editor opens the English variant.
+- They add an invariant Block, and
+- They re-publish the English variant.
+
+**Result:** The new block will appear in both the English and Danish published content.
+
+- An editor opens the Danish variant.
+- They update an invariant property value in a variant Block, and
+- They re-publish the Danish variant.
+
+**Result:** The updated property value appears in both the English and Danish published content.
+
+## Structure vs. Block Level Variance
+
+The Block Editor structure is _invariant_ for Block Level Variance. This means that the structure follows the same rules for invariance as outlined in the section above.
+
+In other words: If an editor changes the order of the Blocks in one Document variant, it changes for all Document variants. The change is applied to all published Document variants, as soon as one or more variants are published.

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/block-level-variance.md

@@ -4,6 +4,6 @@ description: Information on how to work with TinyMCE plugins in the rich text ed
 
 # Plugins
 
-Are plugins available with Tiptap?
-
-Will this be available from version 15?
+{% hint style="info" %}
+This article is currently being written.
+{% endhint %}