From 6dcb5a788f9851e6ef3b94f484dcfac6c942e6aa Mon Sep 17 00:00:00 2001
From: Michael DuBelko <michael.dubelko@canonical.com>
Date: Mon, 2 Mar 2026 19:27:28 -0800
Subject: [PATCH 1/5] style: hints and tips

---
 styles/Canonical/026-hints-tips.yml | 12 ++++++++++++
 vale.ini                            |  1 +
 2 files changed, 13 insertions(+)
 create mode 100644 styles/Canonical/026-hints-tips.yml

diff --git a/styles/Canonical/026-hints-tips.yml b/styles/Canonical/026-hints-tips.yml
new file mode 100644
index 0000000..cc07e5e
--- /dev/null
+++ b/styles/Canonical/026-hints-tips.yml
@@ -0,0 +1,12 @@
+# 026 - Hint and tip blocks
+
+extends: existence
+message: "Avoid 'hint' and 'tip' admonitions. Use the 'admonition' directive with a description instead."
+scope: raw
+nonword: true
+level: suggestion
+tokens:
+  - '.. hint::'
+  - '.. tip::'
+  - '```{hint}'
+  - '```{tip}'
diff --git a/vale.ini b/vale.ini
index 72939ac..9289aa0 100644
--- a/vale.ini
+++ b/vale.ini
@@ -29,6 +29,7 @@ Canonical.019-no-google-drive-images = error
 Canonical.025a-latinisms-with-english-equivalents = suggestion
 Canonical.025b-latinisms-to-reconsider = suggestion
 Canonical.025c-latinisms-to-avoid = suggestion
+Canonical.026-hints-tips = suggestion
 Canonical.400-Enforce-inclusive-terms = error
 Canonical.500-Repeated-words = warning
 

From 2dc93fbea63b9c981aded8111c1db76c732f13b4 Mon Sep 17 00:00:00 2001
From: Michael DuBelko <michael.dubelko@canonical.com>
Date: Mon, 2 Mar 2026 19:27:44 -0800
Subject: [PATCH 2/5] test: rule for hints and tips

---
 tests/data/manifest.yml | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/tests/data/manifest.yml b/tests/data/manifest.yml
index ef7abc8..63fcfed 100644
--- a/tests/data/manifest.yml
+++ b/tests/data/manifest.yml
@@ -2050,3 +2050,25 @@ rules:
                  Line 35
                  Line 36
           severity: warning
+  026-hints-tips:
+    cases:
+      - id: valid
+        filetypes: [md, rst]
+        content: |
+          .. hint::
+              This is a reST hint.
+          .. tip::
+              This is a reST tip.
+          ```{hint}
+          This is a MyST hint.
+          ```
+          ```{tip}
+          This is a MyST tip.
+          ```
+        expect:
+          triggers:
+            - '.. hint::'
+            - '.. tip::'
+            - '```{hint}'
+            - '```{tip}'
+          severity: suggestion

From 6aab29ee895828af22a09257d1344c447f05a5de Mon Sep 17 00:00:00 2001
From: Michael DuBelko <michael.dubelko@canonical.com>
Date: Wed, 4 Mar 2026 17:55:50 -0800
Subject: [PATCH 3/5] style: incorporate @SecondSkoll's review

---
 styles/Canonical/026-hints-tips.yml |  4 ++--
 tests/data/manifest.yml             | 24 ++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/styles/Canonical/026-hints-tips.yml b/styles/Canonical/026-hints-tips.yml
index cc07e5e..2e44d9e 100644
--- a/styles/Canonical/026-hints-tips.yml
+++ b/styles/Canonical/026-hints-tips.yml
@@ -8,5 +8,5 @@ level: suggestion
 tokens:
   - '.. hint::'
   - '.. tip::'
-  - '```{hint}'
-  - '```{tip}'
+  - '(````*|::::*) *?{hint}'
+  - '(````*|::::*) *?{tip}'
diff --git a/tests/data/manifest.yml b/tests/data/manifest.yml
index 63fcfed..71798f0 100644
--- a/tests/data/manifest.yml
+++ b/tests/data/manifest.yml
@@ -2065,10 +2065,34 @@ rules:
           ```{tip}
           This is a MyST tip.
           ```
+          ````{hint}
+          This is a deeper MyST hint.
+          ````
+          ````{tip}
+          This is a deeper MyST tip.
+          ````
+          :::{hint}
+          This is a colon-fenced MyST hint.
+          :::
+          :::{tip}
+          This is a colon-fenced MyST tip.
+          :::
+          ::::{hint}
+          This is a deeper colon-fenced MyST hint.
+          ::::
+          ::::{tip}
+          This is a deeper colon-fenced MyST tip.
+          ::::
         expect:
           triggers:
             - '.. hint::'
             - '.. tip::'
             - '```{hint}'
             - '```{tip}'
+            - '````{hint}'
+            - '````{tip}'
+            - ':::{hint}'
+            - ':::{tip}'
+            - '::::{hint}'
+            - '::::{tip}'
           severity: suggestion

From 6d7c26bdfbbb53deb9dc912798f4687d42766d5a Mon Sep 17 00:00:00 2001
From: Michael DuBelko <michael.dubelko@canonical.com>
Date: Fri, 6 Mar 2026 10:03:42 -0800
Subject: [PATCH 4/5] style: incorporate @dwilding's review

---
 styles/Canonical/026-hints-tips.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/styles/Canonical/026-hints-tips.yml b/styles/Canonical/026-hints-tips.yml
index 2e44d9e..12e5bb9 100644
--- a/styles/Canonical/026-hints-tips.yml
+++ b/styles/Canonical/026-hints-tips.yml
@@ -1,7 +1,7 @@
 # 026 - Hint and tip blocks
 
 extends: existence
-message: "Avoid 'hint' and 'tip' admonitions. Use the 'admonition' directive with a description instead."
+message: "Avoid 'hint' and 'tip' admonitions. Use the 'admonition' directive with a descriptive title instead."
 scope: raw
 nonword: true
 level: suggestion

From 8befcc8b6b9993b4038631b952356cc01362e7c0 Mon Sep 17 00:00:00 2001
From: Michael DuBelko <michael.dubelko@canonical.com>
Date: Fri, 6 Mar 2026 10:16:20 -0800
Subject: [PATCH 5/5] style: encourage regular paragraphs

---
 styles/Canonical/026-hints-tips.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/styles/Canonical/026-hints-tips.yml b/styles/Canonical/026-hints-tips.yml
index 12e5bb9..7017291 100644
--- a/styles/Canonical/026-hints-tips.yml
+++ b/styles/Canonical/026-hints-tips.yml
@@ -1,7 +1,7 @@
 # 026 - Hint and tip blocks
 
 extends: existence
-message: "Avoid 'hint' and 'tip' admonitions. Use the 'admonition' directive with a descriptive title instead."
+message: "Avoid 'hint' and 'tip' admonitions. Instead, use a regular paragraph or the 'admonition' directive with a descriptive title."
 scope: raw
 nonword: true
 level: suggestion