diff --git a/src/content/docs/workflow.mdx b/src/content/docs/workflow.mdx
index 094aac76b4..9e5b6de9e5 100644
--- a/src/content/docs/workflow.mdx
+++ b/src/content/docs/workflow.mdx
@@ -1,30 +1,84 @@
---
title: Workflow Automation
-description: An overview of Mergify Workflow Automation and its capabilities to automate your pull request process.
+description: Automate the routine work on your pull requests with rules that react to a pull request's state to label, comment, assign, rebase, merge, and more.
+hubAccent: true
---
-Mergify Workflow Automation is a rule-based system that automates pull request
-tasks using `pull_request_rules` in your Mergify configuration file.
+import Docset from '~/components/DocsetGrid/Docset.astro';
+import DocsetGrid from '~/components/DocsetGrid/DocsetGrid.astro';
-## How It Works
+Workflow Automation handles the routine work on your pull requests. You write
+rules in your Mergify configuration file, and Mergify carries them out: labeling,
+commenting, assigning, rebasing, merging, and more. Your team spends less time on
+pull request housekeeping.
-Mergify evaluates the state of a pull request rather than individual events.
-This means it checks the current status of a pull request and acts based on
-defined conditions. This behavior is known as "edge triggering."
+## Anatomy of a Rule
-An action will only be re-triggered for a pull request if the state flips back
-from being unmatched to matched.
+Every rule lives under `pull_request_rules` and pairs a set of **conditions**
+with the **actions** to run when a pull request matches them:
+
+```yaml
+pull_request_rules:
+ - name: add "WIP" label when the title contains "WIP"
+ conditions:
+ - title ~= WIP
+ actions:
+ label:
+ toggle:
+ - WIP
+```
+
+Here, any pull request whose title contains `WIP` gets the `WIP` label. Once the
+title no longer matches, Mergify removes it.
+
+## How Rules Are Evaluated
+
+Mergify evaluates the *state* of a pull request rather than individual events. It
+checks the current status of a pull request and acts based on the conditions you
+defined. This behavior is known as "edge triggering": an action only re-runs for
+a pull request when its state flips back from unmatched to matched.
:::note
Mergify never evaluates rules for pull request drafts it creates while
processing the [merge queue](/merge-queue).
:::
-## Reference
+## Building Blocks
-- [Rule Syntax](/workflow/rule-syntax) for the `pull_request_rules` format
+
+
+ The `pull_request_rules` format and how to structure a rule.
+
+
+ Match pull requests on title, labels, CI status, files, authorship, and more.
+
+
+ The full catalog of tasks Mergify can run when a rule matches.
+
+
+ Where rules live and how the overall config file is structured.
+
+
-- [Actions](/workflow/actions) for the full list of available actions
+## Popular Actions
-- [Configuration File](/configuration/file-format) for the overall config
- structure
+
+
+ Automate the merging of your pull requests.
+
+
+ Add the pull request to the merge queue.
+
+
+ Add, remove, or toggle labels on a pull request.
+
+
+ Post a comment on a pull request.
+
+
+ Copy a pull request to another branch once it is merged.
+
+
+ Rebase the pull request on top of its base branch.
+
+
diff --git a/src/content/docs/workflow/rule-syntax.mdx b/src/content/docs/workflow/rule-syntax.mdx
index 8246998af1..b2f107f6cb 100644
--- a/src/content/docs/workflow/rule-syntax.mdx
+++ b/src/content/docs/workflow/rule-syntax.mdx
@@ -1,13 +1,103 @@
---
title: Rule Syntax
-description: Overview of the syntax used in Mergify rules for Workflow Automation and Merge Queue.
+description: How to write a Mergify workflow rule, from the structure of pull_request_rules to its conditions and actions.
---
-This page is a placeholder stub to consolidate references to configuration file
-format, conditions, data types, and sharing configuration.
+import OptionsTable from '~/components/Tables/OptionsTable';
-Use the existing reference pages for full details:
-- [Configuration File Format](/configuration/file-format)
-- [Conditions](/configuration/conditions)
-- [Data Types](/configuration/data-types)
-- [Sharing Configuration](/configuration/sharing)
+Workflow Automation rules live under the `pull_request_rules` key in your
+[configuration file](/configuration/file-format), where each rule pairs a set of
+conditions with the actions Mergify runs when a pull request matches them. For a
+gentle introduction, see the [Workflow Automation overview](/workflow). This
+page is the field-by-field reference.
+
+## Fields
+
+`pull_request_rules` is a list, and each entry is a single rule: a YAML
+dictionary where `name`, `conditions`, and `actions` are required, while
+`description` and `disabled` are optional.
+
+
+
+## Conditions
+
+`conditions` is a list of expressions describing which pull requests the rule
+applies to. A pull request must satisfy **every** condition in the list for the
+rule to match:
+
+```yaml
+conditions:
+ - base = main
+ - label = ready-to-merge
+```
+
+Each condition is built from an attribute (such as `base`, `label`, or
+`#approved-reviews-by`), an operator (such as `=`, `>=`, or `~=`), and usually a
+value. See the [attributes list](/configuration/conditions#attributes-list) and
+[operators list](/configuration/conditions#operators-list) for the full set.
+
+To express "any of" or "none of" instead of "all of", group conditions with the
+[`and`, `or`, and `not` operators](/configuration/conditions#combining-conditions-using-logical-operators).
+The same condition syntax also powers [Merge Queue](/merge-queue) and
+[Merge Protections](/merge-protections), so what you learn here carries over.
+
+## Actions
+
+`actions` is a dictionary that maps an action name to its parameters. A single
+rule can run several actions, and Mergify runs them all when the conditions
+match:
+
+```yaml
+pull_request_rules:
+ - name: warn and label pull requests in conflict
+ conditions:
+ - conflict
+ actions:
+ comment:
+ message: "@{{author}} this pull request is now in conflict 😩"
+ label:
+ toggle:
+ - conflict
+```
+
+The `{{author}}` placeholder is a [template](/configuration/data-types#template)
+that Mergify fills in with the pull request's data. Browse every available
+action and its parameters in the [Actions catalog](/workflow/actions).
+
+## Combining Rules
+
+Rules are evaluated independently: Mergify checks each one against the pull
+request, and every rule whose conditions match runs its actions. Order the rules
+however reads best, since matching does not stop at the first hit. For when an
+action re-runs versus stays put, see
+[how rules are evaluated](/workflow#how-rules-are-evaluated).
+
+## Disabling a Rule
+
+Set `disabled` with a `reason` to keep a rule in the file but stop it from
+running. The reason is shown in the configuration check so others know why:
+
+```yaml
+pull_request_rules:
+ - name: automatic merge
+ disabled:
+ reason: paused during the release freeze
+ conditions:
+ - "#approved-reviews-by >= 1"
+ actions:
+ merge: # merge with default options
+```
+
+## Validating Your Rules
+
+Mergify validates your configuration on every push and reports problems in the
+"Checks" tab of your pull request. To catch mistakes earlier, validate and
+simulate rules locally with the [Mergify CLI](/cli/config):
+
+```bash
+mergify config validate
+mergify config simulate https://github.com/owner/repo/pull/142
+```
+
+See [Validation and Troubleshooting](/configuration/file-format#validation-and-troubleshooting)
+for the full workflow.
diff --git a/src/content/navItems.tsx b/src/content/navItems.tsx
index a6373101d2..9c613809ce 100644
--- a/src/content/navItems.tsx
+++ b/src/content/navItems.tsx
@@ -233,7 +233,7 @@ const navItems: NavItem[] = [
icon: 'lucide:zap',
path: '/workflow',
children: [
- { title: 'Workflow Automation', path: '/workflow/', icon: 'lucide:zap' },
+ { title: 'Overview', path: '/workflow', icon: 'lucide:lightbulb' },
{ title: 'Rule Syntax', path: '/workflow/rule-syntax', icon: 'lucide:badge-question-mark' },
{
title: 'Actions',
@@ -244,7 +244,7 @@ const navItems: NavItem[] = [
{ title: 'Backport', path: '/workflow/actions/backport', icon: 'lucide:git-branch' },
{ title: 'Close', path: '/workflow/actions/close', icon: 'lucide:circle-x' },
{ title: 'Copy', path: '/workflow/actions/copy', icon: 'lucide:share-2' },
- { title: 'Comment', path: '/workflow/actions/comment', icon: 'lucide:list' },
+ { title: 'Comment', path: '/workflow/actions/comment', icon: 'lucide:message-square' },
{
title: 'Delete Head Branch (Deprecated)',
path: '/workflow/actions/delete_head_branch',
@@ -255,7 +255,11 @@ const navItems: NavItem[] = [
path: '/workflow/actions/dismiss_reviews',
icon: 'lucide:message-square-x',
},
- { title: 'Edit', path: '/workflow/actions/edit', icon: 'lucide:type' },
+ {
+ title: 'Edit',
+ path: '/workflow/actions/edit',
+ icon: 'octicon:git-pull-request-draft-16',
+ },
{
title: 'GitHub Actions',
path: '/workflow/actions/github_actions',