[libadwaita/wip/exalm/style-docs: 3/7] doc: Link to style classes and named colors

[Alexander Mikhaylenko <alexm src gnome org>]

commit a16d8e4acc08bce2ec57a77ba3f9c2b80064ffdf
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Wed Dec 15 18:01:50 2021 +0500

    doc: Link to style classes and named colors

 doc/migrating-between-development-versions.md | 59 ++++++++++++++----------
 doc/migrating-libhandy-1-4-to-libadwaita.md   | 66 +++++++++++++++------------
 src/adw-flap.c                                |  8 ++--
 src/adw-status-page.c                         |  5 +-
 4 files changed, 80 insertions(+), 58 deletions(-)
---
diff --git a/doc/migrating-between-development-versions.md b/doc/migrating-between-development-versions.md
index 4491d3f7..08fcd9f4 100644
--- a/doc/migrating-between-development-versions.md
+++ b/doc/migrating-between-development-versions.md
@@ -24,9 +24,11 @@ You should stop using [property@Gtk.Stack:transition-type] and
 
 ### Adapt to Stylesheet Changes
 
-If you were using `@theme_selected_bg_color` as a text color, use
-`@accent_color` instead to make sure the text is readable. You can also use the
-`.accent` style class to apply the correct color.
+If you were using
+[`@theme_selected_bg_color`](named-colors.html#compatibility-colors) as a text
+color, use [`@accent_color`](named-colors.html#accent-colors) instead to make
+sure the text is readable. You can also use the
+[`.accent`](style-classes.html#colors) style class to apply the correct color.
 
 ## Migrating From alpha 2 to alpha 3
 
@@ -118,15 +120,17 @@ The following buttons get flat appearance:
 * Buttons with an icon and a label (using [class@Adw.ButtonContent]);
 * Menu buttons containing an arrow;
 * [class@Adw.SplitButton];
-* Any other button with the `.flat` style class.
+* Any other button with the [`.flat`](style-classes.html#flat) style class.
 
 The following buttons keep default appearance:
 
 * Text-only buttons;
 * Buttons with other content;
-* Buttons within widgets containing the `.linked` style class;
-* Buttons with the `.suggested-action` or `.destructive-action` style classes.
-* Buttons with the `.raised` style class.
+* Buttons within widgets containing the
+  [`.linked`](style-classes.html#linked-controls) class;
+* Buttons with the [`.suggested-action`](style-classes.html#suggested-action) or
+  [`.destructive-action`](style-classes.html#destructive-action) style classes.
+* Buttons with the [`.raised`](style-classes.html#raised) style class.
 
 It's important to avoid ambiguous layouts, for example text-only buttons with
 no icon, since such a button would be indistinguishable from the window title
@@ -135,8 +139,8 @@ without hovering it.
 In rare cases, the existing layout may need a redesign to work with the new
 style.
 
-The same rules are also used for the `.toolbar` style class now, instead of
-making every button appear flat.
+The same rules are also used for the [`.toolbar`](style-classes.html#toolbars)
+style class now, instead of making every button appear flat.
 
 #### Adjusting Icon+Arrow Menu Buttons
 
@@ -175,8 +179,9 @@ One exception are the two primary buttons in a dialog, for example, "Cancel" and
 
 #### Adjusting Split Buttons
 
-If you had split buttons implemented via a `GtkBox` with the `.linked` style
-class and two buttons packed inside, use `AdwSplitButton` as follows:
+If you had split buttons implemented via a `GtkBox` with the
+[`.linked`](style-classes.html#linked-controls) style class and two buttons
+packed inside, use [class@Adw.SplitButton] as follows:
 
 ```xml
 <object class="AdwSplitButton">
@@ -202,8 +207,9 @@ insert extra spacing as follows:
 
 #### Custom Adjustments
 
-The `.flat` and `.raised` style classes can always be used to override the
-default appearance.
+The [`.flat`](style-classes.html#flat) and
+[`.raised`](style-classes.html#raised) style classes can always be used to
+override the default appearance.
 
 Important: the [property@Gtk.Button:has-frame] property will **not** be set to
 `FALSE` when a button gets the flat appearance automatically. It also cannot be
@@ -234,24 +240,27 @@ If you're using the `object-select-symbolic` icon in a header bar button
 
 ### Stop Using the `.sidebar` Style Class
 
-The `.sidebar` style class is now deprecated, although still works for
-compatibility reasons. The main use case - adjusting the background color of
-[class@Gtk.ListBox] and [class@Gtk.ListView] - can now be done with the
-`.navigation-sidebar` style class on those widgets instead, along with adjusting
-the item selection style. The border can be replicated by manually adding a
-[class@Gtk.Separator].
+The [`.sidebar`](style-classes.html#sidebar) style class is now deprecated,
+although still works for compatibility reasons. The main use case - adjusting
+the background color of [class@Gtk.ListBox] and [class@Gtk.ListView] - can now
+be done with the [`.navigation-sidebar`](style-classes.html#sidebars) style
+class on those widgets instead, along with adjusting the item selection style.
+The border can be replicated by manually adding a [class@Gtk.Separator].
 
 #### Adapt to the `popover.combo` Style Removal
 
-The `.combo` popover style class has been removed. Use `.menu` instead. You may
-need to remove manually added margins, padding or minimum height from the list
-items inside while doing it.
+The `.combo` popover style class has been removed. Use
+[`.menu`](style-classes.html#menu-popovers) instead. You may need to remove
+manually added margins, padding or minimum height from the list items inside
+while doing it.
 
 #### Adapt to List Style Changes
 
-For boxed lists we now have the `.boxed-list` style class that matches
-the name of the design pattern. If you were using the `.content` style
-class, you should use `.boxed-list` instead.
+For boxed lists we now have the
+[`.boxed-list`](style-classes.html#boxed-lists-cards) style class that matches
+the name of the design pattern. If you were using the
+[`.content`](style-classes.html#content) style class, you should use
+`.boxed-list` instead.
 
 The `.content` style class currently remains for compatibility purposes.
 
diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.md b/doc/migrating-libhandy-1-4-to-libadwaita.md
index c1e5c4e0..ad2c2032 100644
--- a/doc/migrating-libhandy-1-4-to-libadwaita.md
+++ b/doc/migrating-libhandy-1-4-to-libadwaita.md
@@ -391,24 +391,27 @@ The `hdy_ease_out_cubic()` function has been removed. Instead,
 
 ### Adapt to Stylesheet Changes
 
-If you were using `@theme_selected_bg_color` as a text color, use
-`@accent_color` instead to make sure the text is readable. You can also use the
-`.accent` style class to apply the correct color.
+If you were using
+[`@theme_selected_bg_color`](named-colors.html#compatibility-colors) as a text
+color, use [`@accent_color`](named-colors.html#accent-colors) instead to make
+sure the text is readable. You can also use the
+[`.accent`](style-classes.html#colors) style class to apply the correct color.
 
 ### Stop Using the `.sidebar` Style Class
 
-The `.sidebar` style class is now deprecated, although still works for
-compatibility reasons. The main use case - adjusting the background color of
-[class@Gtk.ListBox] and [class@Gtk.ListView] - can now be done with the
-`.navigation-sidebar` style class on those widgets instead, along with adjusting
-the item selection style. The border can be replicated by manually adding a
-[class@Gtk.Separator].
+The [`.sidebar`](style-classes.html#sidebar) style class is now deprecated,
+although still works for compatibility reasons. The main use case - adjusting
+the background color of [class@Gtk.ListBox] and [class@Gtk.ListView] - can now
+be done with the [`.navigation-sidebar`](style-classes.html#sidebars) style
+class on those widgets instead, along with adjusting the item selection style.
+The border can be replicated by manually adding a [class@Gtk.Separator].
 
 ### Adapt to the `popover.combo` Style Removal
 
-The `.combo` popover style class has been removed. Use `.menu` instead. You may
-need to remove manually added margins, padding or minimum height from the list
-items inside while doing it.
+The `.combo` popover style class has been removed. Use
+[`.menu`](style-classes.html#menu-popovers) instead. You may need to remove
+manually added margins, padding or minimum height from the list items inside
+while doing it.
 
 ### Adapt to the `button.list-button` Style Removal
 
@@ -419,9 +422,10 @@ button style should be used instead.
 
 The `.content-view` style class has been removed. The selection mode
 [class@Gtk.CheckButton] style had inside content views has been split out into a
-separate style class `.selection-mode` that can be applied directly onto check
-buttons instead of the view. The unique background color has no replacement and
-the default background should be used instead.
+separate style class
+[`.selection-mode`](style-classes.html#selection-mode-check-buttons) that can be
+applied directly onto check buttons instead of the view. The unique background
+color has no replacement and the default background should be used instead.
 
 #### Adapt to Header Bar, Action Bar, Search Bar and Toolbar Style Changes
 
@@ -436,15 +440,17 @@ The following buttons get flat appearance:
 * Buttons with an icon and a label (using [class@Adw.ButtonContent]);
 * Menu buttons containing an arrow;
 * [class@Adw.SplitButton];
-* Any other button with the `.flat` style class.
+* Any other button with the [`.flat`](style-classes.html#flat) style class.
 
 The following buttons keep default appearance:
 
 * Text-only buttons;
 * Buttons with other content;
-* Buttons within widgets containing the `.linked` style class;
-* Buttons with the `.suggested-action` or `.destructive-action` style classes.
-* Buttons with the `.raised` style class.
+* Buttons within widgets containing the
+  [`.linked`](style-classes.html#linked-controls) class;
+* Buttons with the [`.suggested-action`](style-classes.html#suggested-action) or
+  [`.destructive-action`](style-classes.html#destructive-action) style classes.
+* Buttons with the [`.raised`](style-classes.html#raised) style class.
 
 It's important to avoid ambiguous layouts, for example text-only buttons with
 no icon, since such a button would be indistinguishable from the window title
@@ -453,14 +459,16 @@ without hovering it.
 In rare cases, the existing layout may need a redesign to work with the new
 style.
 
-The same rules are also used for the `.toolbar` style class now, instead of
-making every button appear flat.
+The same rules are also used for the [`.toolbar`](style-classes.html#toolbars)
+style class now, instead of making every button appear flat.
 
 #### Adapt to List Style Changes
 
-For boxed lists we now have the `.boxed-list` style class that matches
-the name of the design pattern. If you were using the `.content` style
-class, you should use `.boxed-list` instead.
+For boxed lists we now have the
+[`.boxed-list`](style-classes.html#boxed-lists-cards) style class that matches
+the name of the design pattern. If you were using the
+[`.content`](style-classes.html#content) style class, you should use
+`.boxed-list` instead.
 
 The `.content` style class currently remains for compatibility purposes.
 
@@ -510,8 +518,9 @@ One exception are the two primary buttons in a dialog, for example, "Cancel" and
 
 #### Adjusting Split Buttons
 
-If you had split buttons implemented via a `GtkBox` with the `.linked` style
-class and two buttons packed inside, use `AdwSplitButton` as follows:
+If you had split buttons implemented via a `GtkBox` with the
+[`.linked`](style-classes.html#linked-controls) style class and two buttons
+packed inside, use [class@Adw.SplitButton] as follows:
 
 ```xml
 <object class="AdwSplitButton">
@@ -537,8 +546,9 @@ insert extra spacing as follows:
 
 #### Custom Adjustments
 
-The `.flat` and `.raised` style classes can always be used to override the
-default appearance.
+The [`.flat`](style-classes.html#flat) and
+[`.raised`](style-classes.html#raised) style classes can always be used to
+override the default appearance.
 
 Important: the [property@Gtk.Button:has-frame] property will **not** be set to
 `FALSE` when a button gets the flat appearance automatically. It also cannot be
diff --git a/src/adw-flap.c b/src/adw-flap.c
index 7cebb3d5..13e454a3 100644
--- a/src/adw-flap.c
+++ b/src/adw-flap.c
@@ -41,8 +41,9 @@
  * the content and the flap when there's no shadow to separate them, depending
  * on the transition type.
  *
- * [property Adw Flap:flap] is transparent by default; add the `.background`
- * style class to it if this is unwanted.
+ * [property Adw Flap:flap] is transparent by default; add the
+ * [`.background`](style-classes.html#background) style class to it if this is
+ * unwanted.
  *
  * If [property Adw Flap:modal] is set to `TRUE`, content becomes completely
  * inaccessible when the flap is revealed while folded.
@@ -1468,7 +1469,8 @@ adw_flap_class_init (AdwFlapClass *klass)
    *
    * [property Adw Flap:flap] is transparent by default, which means the content
    * will be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions;
-   * add the `.background` style class to it if this is unwanted.
+   * add the [`.background`](style-classes.html#background) style class to it if
+   * this is unwanted.
    *
    * Since: 1.0
    */
diff --git a/src/adw-status-page.c b/src/adw-status-page.c
index d4df7b6a..b142a4be 100644
--- a/src/adw-status-page.c
+++ b/src/adw-status-page.c
@@ -23,8 +23,9 @@
  *
  * `AdwStatusPage` has a main CSS node with name `statuspage`.
  *
- * `AdwStatusPage` can use the `.compact` style class for when it needs to fit
- * into a small space such a sidebar or a popover.
+ * `AdwStatusPage` can use the
+ * [`.compact`](style-classes.html#compact-status-page) style class for when it
+ * needs to fit into a small space such a sidebar or a popover.
  *
  * Since: 1.0
  */