Craft 5.6

docs/.vuepress/components/Indent.vue

@@ -0,0 +1,21 @@
+<template>
+    <div class="indent" :style="`width: ${level * 1.5}em;`">↳</div>
+</template>
+
+<script>
+    export default {
+        props: {
+            level: {
+                type: Number,
+                default: 1,
+            },
+        }
+    };
+</script>
+
+<style scoped>
+    .indent {
+        display: inline-block;
+        text-align: right;
+    }
+</style>

docs/4.x/addresses.md

@@ -115,7 +115,7 @@ $countries = Craft::$app->getAddresses()->getCountryRepository()->getAll();
 ```
 :::
 
-This returns an array of [Country](https://github.com/commerceguys/addressing/blob/master/src/Country/Country.php) objects, indexed by their two-letter code. You might use this to populate a drop-down menu:
+This returns an array of [Country](https://github.com/commerceguys/addressing/blob/master/src/Country/Country.php) objects, indexed by their two-letter code. You might use this to populate a dropdown menu:
 
 ```twig
 <select name="myCountry">

docs/4.x/dev/global-variables.md

@@ -44,6 +44,7 @@ Variable | Description
 [loginUrl](#loginurl) | The URL to the front-end Login page.
 [logoutUrl](#logouturl) | The URL to the front-end Logout page.
 [now](#now) | The current date/time.
+[primarySite](#primarysite) <Since ver="4.14.0" feature="Global Twig variable for the primary site" /> | In multi-site projects, the “primary” site.
 [setPasswordUrl](#setpasswordurl) | The URL to the front-end [Reset Password](kb:front-end-user-accounts#reset-password-forms) page.
 [siteName](#sitename) | The name of the current site.
 [siteUrl](#siteurl) | The base URL of the current site.
@@ -218,6 +219,23 @@ A [DateTime](http://php.net/manual/en/class.datetime.php) object set to the curr
 Today is {{ now|date('M j, Y') }}.
 ```
 
+### `primarySite` <Since ver="4.14.0" feature="Global Twig variable for the primary site" />
+
+The _primary_ site (as designated in <Journey path="Settings, Sites" />), as an instance of <craft4:craft\models\Site>.
+
+```twig
+{# Output the primary site’s name: #}
+We are a proud member of {{ primarySite.name }}
+
+{# Link to a page on the primary site: #}
+{{ tag('a', {
+  href: siteUrl('about/governance', siteId = primarySite.id),
+  text: 'Learn about our family of businesses',
+}) }}
+```
+
+`primarySite` will be a reference to the same object as [`currentSite`](#currentsite), when `currentSite.primary` is `true`. You can also retrieve the primary site via `craft.app.sites.primarySite`.
+
 ### `setPasswordUrl`
 
 The URL to [`setPasswordRequestPath`](config4:setPasswordRequestPath) if it’s set. (This wraps the path in [`siteUrl`](#siteurl).)

docs/5.x/reference/element-types/addresses.md

@@ -107,7 +107,7 @@ $countries = Craft::$app->getAddresses()->getCountryRepository()->getAll();
 ```
 :::
 
-This returns an array of [Country](repo:commerceguys/addressing/blob/master/src/Country/Country.php) objects, indexed by their two-letter code. You might use this to populate a drop-down menu:
+This returns an array of [Country](repo:commerceguys/addressing/blob/master/src/Country/Country.php) objects, indexed by their two-letter code. You might use this to populate a dropdown menu:
 
 ```twig
 <select name="myCountry">

docs/5.x/reference/element-types/entries.md

@@ -24,17 +24,18 @@ Craft uses _entry types_ to define atomic units of content, which are then expos
 
 <Block label="Global Entry Types">
 
-Entry types became a global resource in Craft 5. This means you can define a content type _once_, then use it in multiple sections, as a [nested](#nested-entries) block in a Matrix field, or some combination of the two. As a result, some settings have moved around!
+Entry types became a global resource in Craft 5. This means you can define a content type _once_, then use it in multiple sections, as a [nested](#nested-entries) block in a [Matrix](../field-types/matrix.md) field, or some combination of the two. As a result, some settings have moved around!
 
 Most importantly, you’ll manage entry types in the **Settings** &rarr; **Entry Types** screen—or create them on-the-fly when working on a section or Matrix field.
 
 </Block>
 
 <BrowserShot
-  url="https://my-craft-project.ddev.site/admin/settings/sections/1/entry-types/1"
+  url="https://my-craft-project.ddev.site/admin/settings/entry-types/1"
   :link="false"
+  :max-height="450"
   caption="Editing an entry type in the control panel.">
-  <img src="../../images/sections-and-entries-entry-types.png" alt="Screenshot of entry type settings">
+  <img src="../../images/entry-type-edit.png" alt="Screenshot of entry type settings">
 </BrowserShot>
 
 Entry types have the following settings:
@@ -49,6 +50,58 @@ Entry types have the following settings:
 - **Show the Status field** — Manually set each entry’s status, or allow it to be dictated by its usage.
 - **Field Layout** — Add and arrange [custom fields](../../system/fields.md) to suit your content model.
 
+### Aliases <Since ver="5.6.0" feature="Entry type aliases" />
+
+When attaching an entry type to a [section](#sections) or [field](../field-types/matrix.md), you can configure a local override for its **Name** and **Handle**. This affects labels in the control panel, but does _not_ change how you reference them in queries.
+
+As an example, an _Announcement_ entry type could be used in a _News_ section and a _Content_ Matrix or [CKEditor](plugin:ckeditor) field; in the _Content_ field context, the entry type is given a new **Name** (_Banner_) and handle (`banner`). Authors would then see _Banner_ when selecting **New entry** in the CKEditor toolbar, but developers would need to continue using the original, global handle to directly query those nested entries:
+
+```twig{3}
+{% set embeddedAnnouncements = craft.entries()
+  .field('pageContent')
+  .type('announcement')
+  .all() %}
+```
+
+However, when _accessing_ the entry type via those nested entries (or an entry within a section), the aliases are applied automatically:
+
+```twig{2,8}
+{% set announcements = craft.entries()
+  .type('announcement')
+  .all() %}
+
+{% for announcement in announcements %}
+  <article>
+    <h2>{{ announcement.title }}</h2>
+    <span class="type">{{ announcement.type.name }}</span>
+    {{ announcement.body|md }}
+  </article>
+{% endfor %}
+```
+
+In this example, `announcement.type.name` might resolve to _Critical Release_ in one section, but _New Face_ in another—even though we queried for them using the original, global handle. To access the global <craft5:craft\models\EntryType>, use `entry.type.original`.
+
+This can help improve the legibility of templates, wherein the generic `announcement` handle doesn’t describe how the entry type is actually used:
+
+```twig{2,8-11}
+{% for contentBlock in entry.myMatrixField %}
+  <div class="content-block content-block--type-{{ contentBlock.type.handle }}">
+    {% switch contentBlock.type.handle %}
+      {% case 'carousel'}
+        {# ... #}
+      {% case 'recommended'}
+        {# ... #}
+      {% case 'banner' %}
+        {# Perhaps “Banner” made more sense than “Announcement” in this context, when designing! #}
+        <h3>{{ contentBlock.title }}</h3>
+        {{ contentBlock.message|md }}
+      {% default %}
+        {{ contentBlock.render() }}
+    {% endswitch %}
+  </div>
+{% endfor %}
+```
+
 ### Dynamic Entry Titles
 
 The **Default Title Format** field accepts an [object template](../../system/object-templates.md) (just like the **Entry URI Format** and preview target **URL Format** we looked, above), and is evaluated whenever entries with this type are saved _without an explicitly-set title_. A title format may be rendered multiple times, depending on the selected **Title Translation Method**.
@@ -67,7 +120,7 @@ The available translation methods are covered in the [custom fields documentatio
 
 ## Sections
 
-Sections organize and expose entry types for content authors. In each section you can define the following:
+Sections organize and expose [entry types](#entry-types) for content authors. In each section you can define the following:
 
 - Whether entries in the section have URLs;
 - What the entries’ URLs should look like;
@@ -80,15 +133,15 @@ If your project has multiple [sites](../../system/sites.md), your section can de
 - Which sites entries in the section should target;
 - Which sites entries are created in, by default;
 
-To create a new section, go to **Settings** → **Sections** and choose **New Section**.
+To create a new section, go to <Journey path="Settings, Sections" /> and choose **New Section**.
 
 ### Section Types
 
 Craft has three different types of sections:
 
 #### Singles
 
-![Illustration of Entries layout with “Singles” selected, showing “About Us”, “Contact” and “Home” entries](../../images/entry-types-singles.png)
+![Illustration of Entries layout with “Singles” selected, showing “About Us”, “Contact” and “Home” entries](../../images/section-types-singles.png)
 
 Singles are used for one-off pages or content objects that have unique requirements, such as…
 
@@ -106,7 +159,7 @@ A single’s **Status** controls can be hidden with the **Show the Status field*
 
 #### Channels
 
-![Illustration of Entries layout with a “Press Releases” channel selected, showing three dated news entries](../../images/entry-types-channels.png)
+![Illustration of Entries layout with a “Press Releases” channel selected, showing three dated news entries](../../images/section-types-channels.png)
 
 Channels are used for lists or streams of similar content, such as…
 
@@ -121,11 +174,11 @@ Entries in channels are intended to be queried and displayed ordered by one or m
 
 Structures are an extension of channels that support explicit, hierarchical organization.
 
-![Illustration of Entries layout with a “Galleries” structure selected, showing nested building and gallery entries with drag-and-drop handles](../../images/entry-types-structures.png)
+![Illustration of Entries layout with a “Galleries” structure selected, showing nested building and gallery entries with drag-and-drop handles](../../images/section-types-structures.png)
 
 Unlike other section types, structure sections expose a **Structure** view option on their [element indexes](../../system/elements.md#indexes):
 
-![Illustration of an element index’s “View” options with “Structure” selected.](../../images/entry-types-structure-view-mode.png)
+![Illustration of an element index’s “View” options with “Structure” selected.](../../images/section-types-structure-view-mode.png)
 
 Types of content that might benefit from being defined as a structure include…
 
@@ -166,7 +219,7 @@ When Craft matches a request to an entry, its section’s designated **Template*
 
 Consider these tips for creating special URIs:
 
-- A URI that evaluates to `__home__` (and nothing more) will be available at your site’s base path;
+- A URI that evaluates to `__home__` (and nothing more) will be available at your site’s base path (this should only be used for [singles](#singles));
 - An empty URI means the entry does not get a route and will not have a public URL—unless you define one manually via `routes.php`;
 - Any Twig statement can be used to output values in a URI template—including ones that query for other elements, e.g. `{{ craft.entries().section('mySingle').one().slug }}/news` (see note below);
 - [Aliases](../../configure.md#aliases-and-environment-variables) can be evaluated with the [`alias()` function](../twig/functions.md#alias): `{{ alias('@basePressUri') }}/news`, `{{ alias('@mySectionUri') }}`.

docs/5.x/reference/element-types/users.md

@@ -92,6 +92,18 @@ By {{ collect(entry.authors).pluck('fullName').join(', ', ', and ') }}
 
 Unlike most other element types, users do _not_ have a “URI format” setting or support slugs, and are not factored into routing.
 
+### Affiliated Site <Since ver="5.6.0" feature="Affiliated sites for user elements" />
+
+[Multi-site](../../system/sites.md) projects capture the site a user [registers](../../system/user-management.md#affiliated-site) from (or is assigned to by an admin). Add the **Affiliated Site** [field layout element](#custom-fields) to manage this in the control panel.
+
+A user’s affiliated site can be accessed in a template via `user.affiliatedSite`:
+
+```twig
+{% if currentUser.affiliatedSite %}
+  You registered via {{ currentUser.affiliatedSite.name }}.
+{% endif %}
+```
+
 ## Querying Users
 
 You can fetch users in your templates or PHP code using **user queries**.

docs/5.x/reference/field-types/color.md

@@ -1,73 +1,102 @@
 # Color Fields
 
-Color fields give you a hexadecimal color input with a preview of the current color, and on browsers that support `<input type="color">`, clicking on the preview will open the browser’s color picker.
+Color fields provide a flexible way to store hexadecimal color values. You can define a [palette](#palette) to guide authors <Since ver="5.6.0" feature="Color field palettes" />, or use an [open-ended input](#custom-colors).
 
 <!-- more -->
 
+![Screenshot of a color field interface in the Craft control panel](../../images/fields-color-ui.png)
+
+## Settings
+
+<BrowserShot
+  url="https://my-craft-project.ddev.site/admin/settings/fields/new"
+  :link="false"
+  :max-height="500"
+  caption="Adding a new color field via the control panel.">
+<img src="../../images/fields-color-settings.png" alt="Color field settings screen in the Craft control panel">
+</BrowserShot>
+
+### Palette
+
+Each field contains a **Palette** of colors that authors can select from a dropdown menu.
+
+### Custom Colors
+
+Turn on **Allow custom colors** to display a compact input and color preview UI. When used in conjunction with a palette, an additional **Custom…** option is listed at the bottom of the dropdown menu.
+
+::: tip
+In [browsers that support `<input type="color">`](https://caniuse.com/input-color), clicking on the color preview “well” opens a native OS color picker.
+:::
+
 ## Development
 
-Calling a Color field in your templates will return a <craft5:craft\fields\data\ColorData> object, or `null` if no color was selected.
+Accessing a color field returns a <craft5:craft\fields\data\ColorData> object, or `null` if no color was selected.
 
-By default, the bare field handle will return a hexadecimal representation of that color:
+Casting a `ColorData` object to a string by outputting it directly produces a hexadecimal representation of the color:
 
 ::: code
 ```twig
-{% if entry.myFieldHandle %}
+{% if entry.myColorField %}
   <style type="text/css">
     .content a {
-      color: {{ entry.myFieldHandle }};
+      {# Directly outputting the value... #}
+      color: {{ entry.myColorField }};
     }
     .content b {
-      {# same thing #}
-      color: {{ entry.myFieldHandle.getHex() }};
+      {# ...is equivalent to: #}
+      color: {{ entry.myColorField.getHex() }};
     }
   </style>
 {% endif %}
 ```
 ```php
-if ($entry->myFieldHandle) {
-    echo $entry->myFieldHandle;
-    // same thing
-    echo $entry->myFieldHandle->getHex();
+if ($entry->myColorField) {
+    echo $entry->myColorField;
+    // …is equivalent to…
+    echo $entry->myColorField->getHex();
 }
 ```
 :::
 
-Here’s an impractical example illustrating each <craft5:craft\fields\data\ColorData> method:
+`ColorData` objects have a number of methods that streamline working with color values:
 
 ::: code
 ```twig
-{% if entry.myFieldHandle %}
-  {{ entry.myFieldHandle }}                 {# output: #e5422b #}
-  {{ entry.myFieldHandle.getHex() }}        {# output: #e5422b #}
-  {{ entry.myFieldHandle.getRgb() }}        {# output: rgb(229,66,43) #}
-  {{ entry.myFieldHandle.getHsl() }}        {# output: hsl(7,81%,90%) #}
-  {{ entry.myFieldHandle.getLuma() }}       {# output: 0.38820862745098 #}
-  {{ entry.myFieldHandle.getHue() }}        {# output: 7 #}
-  {{ entry.myFieldHandle.getLightness() }}  {# output: 90 #}
-  {{ entry.myFieldHandle.getSaturation() }} {# output: 81 #}
-  {{ entry.myFieldHandle.getRed() }}        {# output: 229 #}
-  {{ entry.myFieldHandle.getGreen() }}      {# output: 66 #}
-  {{ entry.myFieldHandle.getBlue() }}       {# output: 43 #}
+{% if entry.myColorField %}
+  {{ entry.myColorField }}                 {# output: #e5422b #}
+  {{ entry.myColorField.getHex() }}        {# output: #e5422b #}
+  {{ entry.myColorField.getRgb() }}        {# output: rgb(229,66,43) #}
+  {{ entry.myColorField.getHsl() }}        {# output: hsl(7,81%,90%) #}
+  {{ entry.myColorField.getLuma() }}       {# output: 0.38820862745098 #}
+  {{ entry.myColorField.getHue() }}        {# output: 7 #}
+  {{ entry.myColorField.getLightness() }}  {# output: 90 #}
+  {{ entry.myColorField.getSaturation() }} {# output: 81 #}
+  {{ entry.myColorField.getRed() }}        {# output: 229 #}
+  {{ entry.myColorField.getGreen() }}      {# output: 66 #}
+  {{ entry.myColorField.getBlue() }}       {# output: 43 #}
 {% endif %}
 ```
 ```php
-if ($entry->myFieldHandle) {
-    echo $entry->myFieldHandle;                  // output: #e5422b
-    echo $entry->myFieldHandle->getHex();        // output: #e5422b
-    echo $entry->myFieldHandle->getRgb();        // output: rgb(229,66,43)
-    echo $entry->myFieldHandle->getHsl();        // output: hsl(7,81%,90%)
-    echo $entry->myFieldHandle->getLuma();       // output: 0.38820862745098
-    echo $entry->myFieldHandle->getHue();        // output: 7
-    echo $entry->myFieldHandle->getLightness();  // output: 90
-    echo $entry->myFieldHandle->getSaturation(); // output: 81
-    echo $entry->myFieldHandle->getRed();        // output: 229
-    echo $entry->myFieldHandle->getGreen();      // output: 66
-    echo $entry->myFieldHandle->getBlue();       // output: 43
+if ($entry->myColorField) {
+    echo $entry->myColorField;                  // output: #e5422b
+    echo $entry->myColorField->getHex();        // output: #e5422b
+    echo $entry->myColorField->getRgb();        // output: rgb(229,66,43)
+    echo $entry->myColorField->getHsl();        // output: hsl(7,81%,90%)
+    echo $entry->myColorField->getLuma();       // output: 0.38820862745098
+    echo $entry->myColorField->getHue();        // output: 7
+    echo $entry->myColorField->getLightness();  // output: 90
+    echo $entry->myColorField->getSaturation(); // output: 81
+    echo $entry->myColorField->getRed();        // output: 229
+    echo $entry->myColorField->getGreen();      // output: 66
+    echo $entry->myColorField->getBlue();       // output: 43
 }
 ```
 :::
 
 ::: tip
-The example omits the `getL()`, `getS()`, `getR()`, `getG()`, and `getB()` methods, which are abbreviated forms of `getLuma()`, `getSaturation()`, `getRed()`, `getGreen()`, and `getBlue()` respectively.
+Refer to the [`ColorData`](craft5:craft\fields\data\ColorData) class reference for a complete list of methods!
 :::
+
+## Querying by Color
+
+There are no special query features for color fields; refer to the [plain text](plain-text.md) field for a list of standard string comparison syntaxes.

docs/5.x/reference/field-types/email.md

@@ -10,6 +10,10 @@ Email fields give you a normal text input that requires a valid email address.
 
 <!-- more -->
 
+::: tip
+The new [Link field](link.md) also supports email addresses.
+:::
+
 ## Settings
 
 Email fields have the following settings: