Add a caution note for global user show rules on figures

README.md

@@ -51,9 +51,17 @@ After importing the package and before making any calls to `gls`,` print-glossar
 #show: make-glossary
 ```
 
-> *WHY DO WE NEED THAT ?* : In order to be able to create references to the terms in your glossary using typst ref syntax `@key` glossarium needs to setup some [show rules](https://typst.app/docs/tutorial/advanced-styling/) before any references exist. This is due to the way typst works, there is no workaround.
+> [!NOTE]
+> <h3 align="center">*WHY DO WE NEED THAT?*</h3>
 >
->Therefore I recommend that you always put the `#show: ...` statement on the line just below the `#import` statement.
+> In order to be able to create references to the terms in your glossary using typst [reference  syntax](https://typst.app/docs/reference/model/ref/) `@key` glossarium needs to setup some [show rules](https://typst.app/docs/tutorial/advanced-styling/) before any references exist.
+
+> [!CAUTION]
+> <h3 align="center">*SHOW RULES CONFLICTS*</h3>
+>
+> Prefer to use the [selector](https://typst.app/docs/reference/foundations/function/#definitions-where) `figure.where(kind: "image")` or other kinds to avoid conflicts with `glossarium_entry`.
+> `make-glossary` can conflict with _global_ figure show rules. Write the user figure show rule before `make-glossary` to avoid any conflicts.
+> ![image illustrating a show rule conflict when the user figure show rule is written after make-glossary making the glossary disappear but no effect when it is written before make-glossary.](.github/show_rule_conflict.png)
 
 ### Registering the glossary
 

tests/styling/styling.typ

@@ -1,6 +1,8 @@
 #import "../../themes/default.typ": *
+#import "@preview/codly:1.1.1": *
+#show: codly-init.with()
+#set page(height: auto, margin: 10pt)
 
-#show: make-glossary
 #show link: set text(fill: red)
 #let entry-list = (
   (
@@ -13,8 +15,42 @@
   ),
 )
 #register-glossary(entry-list)
-#show figure.caption.where(kind: "glossarium_entry"): it => {
-  align(center, it)
-}
 
-#print-glossary(entry-list, show-all: true)
+#rect(stroke: 1pt + green, fill: green.lighten(90%))[
+  = #sym.checkmark User figure show rule before make-glossary
+  #show figure: it => {
+    align(right, it.body)
+  }
+  #show: make-glossary
+
+  ```typc
+  show figure: it => {
+    align(right, it.body)
+  }
+  show: make-glossary
+  ```
+  #rect(width: 100%)[
+    #print-glossary(entry-list, show-all: true)
+    #figure[Figure Right]
+  ]
+]
+
+#rect(stroke: 1pt + red, fill: red.lighten(90%))[
+  = #sym.crossmark User figure show rule after make-glossary
+
+  #show: make-glossary
+  #show figure: it => {
+    align(right, it.body)
+  }
+
+  ```typc
+  show: make-glossary
+  show figure: it => {
+    align(right, it.body)
+  }
+  ```
+  #rect(width: 100%)[
+    #print-glossary(entry-list, show-all: true)
+    #figure[Figure Right]
+  ]
+]