docs(material/theming): Fix broken theme guide formatting (#28015)

Our docs site does not support the definition-list markdown, so I
switched to headers instead. I also added a link from the generated
schematic comment to the relevant documentation so users can learn more.

(cherry picked from commit 58ecb18)

Author: mmalerba

guides/theming.md

@@ -241,37 +241,43 @@ your project's `angular.json` file][adding-styles].
 
 #### Theming dimensions
 
-Angular Material themes are divided along several dimensions:
+Angular Material themes are divided along four dimensions: base, color, typography, and density.
 
-Base
-: Common base styles for the design system. These styles don't change based on your configured
+##### Base
+
+Common base styles for the design system. These styles don't change based on your configured
 colors, typography, or density, so they only need to be included once per application. These
 mixins include structural styles such as border-radius, border-width, etc. All components have a base
 mixin that can be used to include its base styles. (For example,
 `@include mat.checkbox-base($theme)`)
 
-Color
-: Styles related to the colors in your application. These style should be included at least once in
+##### Color
+
+Styles related to the colors in your application. These style should be included at least once in
 your application. Depending on your needs, you may need to include these styles multiple times
 with different configurations. (For example, if your app supports light and dark theme colors.)
 All components have a color mixin that can be used to include its color styles. (For example,
 `@include mat.checkbox-color($theme)`)
 
-Typography
-: Styles related to the fonts used in your application, including the font family, size, weight,
+##### Typography
+
+Styles related to the fonts used in your application, including the font family, size, weight,
 line-height, and letter-spacing. These style should be included at least once in your application.
 Depending on your needs, you may need to include these styles multiple times with different
 configurations. (For example, if your app supports reading content in either a serif or sans-serif
 font.) All components  have a typography mixin that can be used to include its typography
 styles. (For example, `@include mat.checkbox-typography($theme)`)
 
-Density
-: Styles related to the size and spacing of elements in your application. These style should be
+##### Density
+
+Styles related to the size and spacing of elements in your application. These style should be
 included at least once in your application. Depending on your needs, you may need to include these
 styles multiple times with different configurations. (For example, if your app supports both a
 normal and compact mode). All components have a density mixin that can be used to include its
 density styles. (For example, `@include mat.checkbox-density($theme)`)
 
+##### Theme mixin
+
 All components also support a theme mixin that can be used to include the component's styles for all
 theme dimensions at once. (For example, `@include mat.checkbox-theme($theme)`).
 

src/material/schematics/ng-update/migrations/theme-base-v17/migration.ts

@@ -17,6 +17,9 @@ const MISSING_MIXIN_PREAMBLE_LINES = `
 // Please note: you do not need to include the 'base' mixins, if you include the corresponding
 // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
 //
+// To learn more about "base" theme styles visit our theming guide:
+// https://material.angular.io/guide/theming#theming-dimensions
+//
 // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
 // your theme to them. This will ensure the correct values for your app are included.\
 `.split('\n');

src/material/schematics/ng-update/test-cases/theme-base.spec.ts

@@ -56,6 +56,9 @@ describe('theme base mixins migration', () => {
       // Please note: you do not need to include the 'base' mixins, if you include the corresponding
       // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
       //
+      // To learn more about "base" theme styles visit our theming guide:
+      // https://material.angular.io/guide/theming#theming-dimensions
+      //
       // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
       // your theme to them. This will ensure the correct values for your app are included.
       @include mat.button-base(/* TODO(v17): pass $your-theme here */);
@@ -91,6 +94,9 @@ describe('theme base mixins migration', () => {
       // Please note: you do not need to include the 'base' mixins, if you include the corresponding
       // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
       //
+      // To learn more about "base" theme styles visit our theming guide:
+      // https://material.angular.io/guide/theming#theming-dimensions
+      //
       // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
       // your theme to them. This will ensure the correct values for your app are included.
       @include material.all-component-bases(/* TODO(v17): pass $your-theme here */);
@@ -123,6 +129,9 @@ describe('theme base mixins migration', () => {
       // Please note: you do not need to include the 'base' mixins, if you include the corresponding
       // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
       //
+      // To learn more about "base" theme styles visit our theming guide:
+      // https://material.angular.io/guide/theming#theming-dimensions
+      //
       // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
       // your theme to them. This will ensure the correct values for your app are included.
       @include mat.card-base(/* TODO(v17): pass $your-theme here */);
@@ -160,6 +169,9 @@ describe('theme base mixins migration', () => {
       // Please note: you do not need to include the 'base' mixins, if you include the corresponding
       // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
       //
+      // To learn more about "base" theme styles visit our theming guide:
+      // https://material.angular.io/guide/theming#theming-dimensions
+      //
       // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
       // your theme to them. This will ensure the correct values for your app are included.
       @include mat.all-component-bases(/* TODO(v17): pass $your-theme here */);
@@ -225,6 +237,9 @@ describe('theme base mixins migration', () => {
         // Please note: you do not need to include the 'base' mixins, if you include the corresponding
         // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
         //
+        // To learn more about "base" theme styles visit our theming guide:
+        // https://material.angular.io/guide/theming#theming-dimensions
+        //
         // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
         // your theme to them. This will ensure the correct values for your app are included.
         @include mat.slider-base(/* TODO(v17): pass $your-theme here */);
@@ -244,6 +259,9 @@ describe('theme base mixins migration', () => {
         // Please note: you do not need to include the 'base' mixins, if you include the corresponding
         // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
         //
+        // To learn more about "base" theme styles visit our theming guide:
+        // https://material.angular.io/guide/theming#theming-dimensions
+        //
         // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
         // your theme to them. This will ensure the correct values for your app are included.
         @include mat.slider-base(/* TODO(v17): pass $your-theme here */);
@@ -296,6 +314,9 @@ describe('theme base mixins migration', () => {
       // Please note: you do not need to include the 'base' mixins, if you include the corresponding
       // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles.
       //
+      // To learn more about "base" theme styles visit our theming guide:
+      // https://material.angular.io/guide/theming#theming-dimensions
+      //
       // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass
       // your theme to them. This will ensure the correct values for your app are included.
       @include mat.form-field-base(/* TODO(v17): pass $your-theme here */);