Reference landing pages list their subpages

Author: AugustMiller

docs/5.x/development/twig.md

@@ -15,30 +15,35 @@ Let’s take a look at how it works.
 
 ## Types of Twig code
 
-Twig templates are HTML files that are sprinkled with bits of Twig code. When Twig loads a template, the first thing it will do is separate the raw HTML code from the Twig code. The raw HTML code will be output to the browser without any tampering.
+Twig templates are HTML files that are sprinkled with bits of logic. When Twig loads a template, the first thing it does is identify which parts of the file represent Twig code.
 
-All Twig code follows a basic pattern that separates it from the surrounding HTML. At its outer edges you will find left and right curly braces (`{` and `}`), coupled with another character that signifies what _type_ of Twig code it is. These sets of characters are called “delimiters”.
+All Twig code follows a basic pattern that separates it from the surrounding HTML. At its outer edges you will find left and right curly braces (`{` and `}`), coupled with another character that signifies what type of Twig expression it expects to be inside. These pairs of characters are called _delimiters_.
 
-There are three types of delimiters that Twig looks out for:
+There are three types of delimiters that Twig parses:
 
-- `{#` – [Comments](#comments)
-- `{%` – [Tags](#tags)
-- `{{` – [Print statements](#print-statements)
+- `{# ... #}` – [Comments](#comments)
+- `{% ... %}` – [Tags](#tags)
+- `{{ ... }}` – [Print statements](#print-statements)
 
 ### Comments
 
 Twig comments are wrapped in `{#` and `#}` delimiters. You can use them to leave little notes for yourself in the code.
 
-They are similar to HTML comments in that they won’t show up as rendered text in the browser. The difference is that they will never make it into the HTML source in the first place.
+They are similar to HTML comments in that they won’t show up as rendered text in the browser—but _Twig_ comments are stripped from the HTML output:
 
-```twig
-<!-- This will be visible in the HTML source -->
+::: code
+```twig Template
+<!-- This will be visible in the HTML source! -->
 {# This won’t! #}
 ```
+```html Output
+<!-- This will be visible in the HTML source! -->
+```
+:::
 
 ### Tags
 
-Twig tags are wrapped in `{%` and `%}` delimiters, and are used to define the _logic_ of your template, such as conditionals, loops, variable definitions, template includes, and other things.
+Twig tags are wrapped in `{%` and `%}` delimiters, and are used to define the _logic_ of your template, such as conditionals, loops, variable definitions, template includes, and other instructions.
 
 The syntax within the `{%` and `%}` delimiters varies from tag to tag, but they will always start with the same thing: the name of the tag.
 
@@ -68,17 +73,17 @@ Some tags can have nested tags _between_ the opening and closing tags:
 
 ```twig
 {% if currentUser %}
-  <a href="/logout">Logout</a>
+  <a href="{{ logoutUrl }}">Logout</a>
 {% else %}
-  <a href="/login">Login</a>
+  <a href="{{ loginUrl }}">Login</a>
 {% endif %}
 ```
 
 Refer to the [Tags](../reference/twig/tags.md) page for a full list of tags available to your Craft templates.
 
 ### Print Statements
 
-To output dynamic values, use a print statement. Print statements are opened and closed with `{{` and `}}` delimiters, respectively, can contain any valid Twig expression—so long as it produces something that can be treated as a [string](#strings).
+To output dynamic values, use a print statement. Print statements are opened and closed with `{{` and `}}` delimiters, respectively, and can contain any valid Twig expression—so long as it produces something that can be treated as a [string](#strings).
 
 ```twig
 <p>Hi, {{ currentUser.name }}</p>

docs/5.x/reference/README.md

@@ -2,8 +2,26 @@
 
 This section contains technical details for built-in Craft components like [element types](element-types/), [field types](field-types/), and the [Twig environment](twig/). It is intended primarily for developers charged with building or maintaining a Craft project who need frequent access to code-specific features.
 
-See the sidebar for a complete list of topics.
+[Element Types](element-types/README.md) →
+:   Deep-dives on each of Craft’s built-in [element types](../system/elements.md).
+
+[Field Types](field-types/README.md) →
+:   Discover Craft’s built-in [field types](../system/fields.md).
+
+[Configuration](config/README.md) →
+:   Descriptions for every [general](config/general.md) and [database](config/db.md) config setting, as well as help with [application config](config/app.md).
+
+[Twig](twig/README.md) →
+:   Lists of filters, functions, tags, tests, and variables that Craft provides to the [Twig templating environment](../development/twig.md).
+
+[Controller Actions](controller-actions.md) →
+:   Common HTTP endpoints for use with [forms](../development/forms.md).
+
+[Command-Line Interface](cli.md) →
+:   Special back-office features available via the command line.
 
 ## Additional Resources
 
-<See url="https://github.com/craftcms/cms" label="Craft CMS Source" description="Browse Craft’s source code on GitHub." />
+<See url="https://github.com/craftcms/cms" label="Craft CMS Source" description="Browse Craft’s source code, releases, issues, and discussions on GitHub." />
+
+<See url="https://docs.craftcms.com/api/v5" label="Class Reference" description="Auto-generated class reference for Craft CMS 5.x." />

docs/5.x/reference/cli.md

@@ -9,6 +9,10 @@ containsGeneratedContent: yes
 
 The complete list of available commands will include those from any plugins or custom modules you’ve added to your project. Only those that are present by default in all Craft installations are listed below.
 
+::: tip
+Run `ddev craft help` to see a list of commands your project supports.
+:::
+
 ### Global Options
 
 All commands support the following options:

docs/5.x/reference/config/README.md

@@ -1 +1,11 @@
 # Configuration Reference
+
+These pages contain comprehensive reference for Craft’s configuration files:
+
+<See path="general.md" />
+<See path="db.md" />
+
+Additional sections cover abstract configuration schemes:
+
+<See path="app.md" />
+<See path="bootstrap.md" />

docs/5.x/reference/config/app.md

@@ -1,4 +1,5 @@
 ---
+description: Customize and extend core application components.
 related:
   - uri: ../../configure.md
     label: Configuring Craft
@@ -26,6 +27,8 @@ Of course, this power comes with a greater risk of misconfiguration. Some compon
 Keep in mind that even when Craft doesn’t provide “defaults” explicitly in its own `app.php` config files (or config helper methods), the underlying component classes may have default property values—or even compute defaults based on other values.
 :::
 
+You may place configuration directly in `config/app.php`, or use `config/app.web.php` or `config/app.console.php` to apply it specifically to one app context. Defining options in the global space may cause errors for components that Craft itself only uses in one context or the other!
+
 ### Static
 
 Most components’ config can be provided as a plain array, which gets merged with the default config map prior to initialization. This style is mostly used for customizing individual properties on a component:

docs/5.x/reference/config/bootstrap.md

@@ -1,5 +1,5 @@
 ---
-description: Reference
+description: Customize your project’s directory structure and other low-level behaviors.
 related:
   - uri: ../../configure.md
     label: Configuring Craft

docs/5.x/reference/twig/README.md

@@ -1,5 +1,7 @@
 # Twig Reference
 
+This section covers features available in Twig, Craft’s template environment.
+
 <See path="../../development/twig.md" label="Twig Fundamentals" />
 
 <hr>

docs/5.x/reference/twig/functions.md

@@ -495,20 +495,38 @@ Creates and returns a new <yii2:yii\db\Expression> object, for use in database q
 
 ## `failMessageInput`
 
-Shortcut for typing `<input type="hidden" name="failMessage" value="{{ 'Custom fail message'|hash }}">`.
+Renders a hidden `input` element with a tamper-proof [failure](../../development/forms.md#failure) message.
 
-```twig
-{{ failMessageInput('Custom fail message') }}
+```twig{3}
+<form method="post">
+  {{ actionInput('users/save-user') }}
+  {{ failMessageInput('Something went wrong when updating your profile.') }}
+
+  {# ... #}
+</form>
 ```
 
-You can optionally set additional attributes on the tag by passing an `options` argument.
+You can set additional attributes on the `input` tag by passing an `options` argument:
 
 ```twig
-{{ failMessageInput('Custom fail message', {
-  id: 'fail-message-input'
+{{ failMessageInput('Something went wrong when updating your profile.', {
+  id: 'failure-message-input'
 }) }}
 ```
 
+The output is equivalent to this Twig:
+
+```twig
+<input
+  type="hidden"
+  name="failMessage"
+  value="{{ 'Something went wrong when updating your profile.'|hash }}">
+```
+
+Failure messages are stored in the session as [flashes](../../development/forms.md#flashes).
+
+<See path="../../development/forms.md" label="Working with Forms" />
+
 ## `fieldValueSql`
 
 Generates a platform-specific SQL expression to extract a value from elements’ JSON content column.
@@ -827,20 +845,38 @@ This works identically to Twig’s core [`source`](https://twig.symfony.com/doc/
 
 ## `successMessageInput`
 
-Shortcut for typing `<input type="hidden" name="successMessage" value="{{ 'Custom success message'|hash }}">`.
+Renders a hidden `input` element with a tamper-proof [success](../../development/forms.md#success) message.
 
-```twig
-{{ successMessageInput('Custom success message') }}
+```twig{3}
+<form method="post">
+  {{ actionInput('users/save-user') }}
+  {{ successMessageInput('Your profile has been updated!') }}
+
+  {# ... #}
+</form>
 ```
 
-You can optionally set additional attributes on the tag by passing an `options` argument.
+You can set additional attributes on the `input` tag by passing an `options` argument:
 
 ```twig
-{{ successMessageInput('Custom success message', {
+{{ successMessageInput('Your profile has been updated!', {
   id: 'success-message-input'
 }) }}
 ```
 
+The output is equivalent to this Twig:
+
+```twig
+<input
+  type="hidden"
+  name="successMessage"
+  value="{{ 'Your profile has been updated!'|hash }}">
+```
+
+Success messages are stored in the session as [flashes](../../development/forms.md#flashes).
+
+<See path="../../development/forms.md" label="Working with Forms" />
+
 ## `svg`
 
 Outputs an SVG document.