Improve how-to indexing and titles (#567)

philippjfr · web-flow · commit 72755fca4095 · 2026-02-02T18:40:06.000+01:00
diff --git a/doc/how_to/bokeh_holoviews.md b/doc/how_to/bokeh_holoviews.md
@@ -1,4 +1,4 @@
-# Bokeh, hvPlot, and HoloViews
+# Theme Bokeh, hvPlot, and HoloViews
 
 Panel Material UI has integrated theming support for Bokeh, hvPlot, and HoloViews. This means that the plots will automatically adapt to the active theme, including respecting the primary color, the font family, and toggling between dark and light mode.
 
diff --git a/doc/how_to/branding.md b/doc/how_to/branding.md
@@ -1,4 +1,4 @@
-# How to Brand Your Panel Material-UI Application
+# Apply Branding
 
 This guide demonstrates how to create a cohesive brand experience in your Panel Material-UI applications using the "Orbitron" brand example. You'll learn how to structure your brand assets, configure consistent theming, and apply your brand across all components.
 
diff --git a/doc/how_to/color.md b/doc/how_to/color.md
@@ -1,4 +1,4 @@
-# Color
+# Pick Colors
 
 Convey meaning through color. By default, `panel-material-ui` provides access to the [Material Design color system](https://m2.material.io/design/color/the-color-system.html#color-usage-and-palettes), allowing you to choose from a broad set of hues and shade combinations.
 
diff --git a/doc/how_to/components.md b/doc/how_to/components.md
@@ -1,4 +1,4 @@
-# Themed Components
+# Theme Components
 
 You can customize `panel-material-ui` components—changing default props, styles, or adding new variants—by defining a `components` key within your `theme_config`. This approach is ideal for ensuring a consistent look and feel across your entire application. If your customizations are extensive, however, consider creating new component classes for maintainability.
 
diff --git a/doc/how_to/custom.md b/doc/how_to/custom.md
@@ -1,4 +1,4 @@
-# Custom Components
+# Build Custom Components
 
 The `panel-material-ui` package ships with a number of custom Material UI components that are built on top of the Material UI library. However, in some cases, you may need to create your own custom components.
 
diff --git a/doc/how_to/customize.md b/doc/how_to/customize.md
@@ -1,4 +1,4 @@
-# How to Customize
+# Customize Themes & Styles
 
 Customization of Panel Mui components inherits all the benefits of having a consistent design language that Mui provides. Styling can be applied using the `sx` parameter, while theming is achieved through the inheritable `theme_config`. Let us walk through these two different approaches through a series of examples.
 
diff --git a/doc/how_to/dark_mode.md b/doc/how_to/dark_mode.md
@@ -1,4 +1,4 @@
-# Dark Mode
+# Control Dark Mode
 
 The `panel-material-ui` components automatically integrate with Panel’s dark mode configuration and allow you to force dark mode by setting `dark_theme=True` at the component level or in your Panel extension.
 
diff --git a/doc/how_to/icons.md b/doc/how_to/icons.md
@@ -1,4 +1,4 @@
-# Icons
+# Use Icons
 
 **panel-material-ui** ships with the Material UI icon library. This means that you can use any of the icons defined in the [Material UI icon library](https://mui.com/material-ui/material-icons/) by default and also include them in `Markdown` and `HTML` components.
 
diff --git a/doc/how_to/index.md b/doc/how_to/index.md
@@ -12,17 +12,17 @@ Welcome to the **Panel Material UI** how-to guides. These guides walk you throug
 ::::{grid} 1 2 2 3
 :gutter: 1 1 1 2
 
-:::{grid-item-card} {octicon}`tools;2.5em;sd-mr-1` How to Customize
+:::{grid-item-card} {octicon}`tools;2.5em;sd-mr-1` Customize Themes & Styles
 :link: customize
 :link-type: doc
 
 Explore the fundamentals of customizing **panel-material-ui** components. Learn one-off styling with `sx`, overriding nested elements, global CSS overrides, and theme inheritance.
 
 +++
-[Learn more »](how_to_customize)
+[Learn more »](customize)
 :::
 
-:::{grid-item-card} {octicon}`list-unordered;2.5em;sd-mr-1` Palette
+:::{grid-item-card} {octicon}`list-unordered;2.5em;sd-mr-1` Configure Color Palettes
 :link: palette
 :link-type: doc
 
@@ -32,7 +32,7 @@ Customize the default primary, secondary, and intent-based colors. Set up advanc
 [Learn more »](palette)
 :::
 
-:::{grid-item-card} {octicon}`typography;2.5em;sd-mr-1` Typography
+:::{grid-item-card} {octicon}`typography;2.5em;sd-mr-1` Configure Typography
 :link: typography
 :link-type: doc
 
@@ -42,17 +42,17 @@ Learn how to customize fonts, sizes, and text styles.
 [Learn more »](typography)
 :::
 
-:::{grid-item-card} {octicon}`apps;2.5em;sd-mr-1` Themed Components
+:::{grid-item-card} {octicon}`apps;2.5em;sd-mr-1` Theme Components
 :link: components
 :link-type: doc
 
-Customize components changing default props, styles, or adding new variants—by defining a `components` key within your `theme_config`..
+Customize components changing default props, styles, or adding new variants—by defining a `components` key within your `theme_config`.
 
 +++
 [Learn more »](components)
 :::
 
-:::{grid-item-card} {octicon}`moon;2.5em;sd-mr-1` Dark Mode
+:::{grid-item-card} {octicon}`moon;2.5em;sd-mr-1` Control Dark Mode
 :link: dark_mode
 :link-type: doc
 
@@ -62,7 +62,7 @@ Seamlessly toggle between light and dark palettes, or enforce one mode across yo
 [Learn more »](dark_mode)
 :::
 
-:::{grid-item-card} {octicon}`paintbrush;2.5em;sd-mr-1` Color
+:::{grid-item-card} {octicon}`paintbrush;2.5em;sd-mr-1` Pick Colors
 :link: color
 :link-type: doc
 
@@ -72,7 +72,7 @@ Dive into the Material Design color system. Create harmonious palettes, pick acc
 [Learn more »](color)
 :::
 
-:::{grid-item-card} {octicon}`image;2.5em;sd-mr-1` Icons
+:::{grid-item-card} {octicon}`image;2.5em;sd-mr-1` Use Icons
 :link: icons
 :link-type: doc
 
@@ -82,24 +82,24 @@ Learn how to use icons in **panel-material-ui**.
 [Learn more »](icons)
 :::
 
-:::{grid-item-card} {octicon}`code;2.5em;sd-mr-1` Custom Components
+:::{grid-item-card} {octicon}`code;2.5em;sd-mr-1` Build Custom Components
 :link: custom
 :link-type: doc
 
 Learn how to build custom components extending **panel-material-ui**.
 
 +++
-[Learn more »](branding)
+[Learn more »](custom)
 :::
 
-:::{grid-item-card} {octicon}`paintbrush;2.5em;sd-mr-1` Branding
+:::{grid-item-card} {octicon}`paintbrush;2.5em;sd-mr-1` Apply Branding
 :link: branding
 :link-type: doc
 
 Learn how to brand your **panel-material-ui** apps.
 
 +++
-[Learn more »](custom)
+[Learn more »](branding)
 :::
 
 ::::
@@ -151,6 +151,7 @@ components
 dark_mode
 color
 icons
+custom
 branding
 bokeh_holoviews
 plotly
diff --git a/doc/how_to/palette.md b/doc/how_to/palette.md
@@ -1,4 +1,4 @@
-# Palette
+# Customize Color Palettes
 
 The `panel-material-ui` palette system allows you to customize component colors to suit your brand. Colors are grouped into default categories (primary, secondary, error, warning, info, success) or custom categories that you define yourself.
 
diff --git a/doc/how_to/plotly.md b/doc/how_to/plotly.md
@@ -1,4 +1,4 @@
-# Plotly Theming
+# Theme Plotly
 
 Panel Material UI provides integrated theming support for Plotly, which is applied automatically.
 
diff --git a/doc/how_to/typography.md b/doc/how_to/typography.md
@@ -1,4 +1,4 @@
-# Typography
+# Configure Typography
 
 `panel_material_ui` provides a robust typography system inspired by Material UI. Fonts and sizes can be customized globally with a `theme_config`, or overridden at the component level.
 

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Bokeh, hvPlot, and HoloViews`
	`1`	`+# Theme Bokeh, hvPlot, and HoloViews`
`2`	`2`
`3`	`3`	`Panel Material UI has integrated theming support for Bokeh, hvPlot, and HoloViews. This means that the plots will automatically adapt to the active theme, including respecting the primary color, the font family, and toggling between dark and light mode.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# How to Brand Your Panel Material-UI Application`
	`1`	`+# Apply Branding`
`2`	`2`
`3`	`3`	`This guide demonstrates how to create a cohesive brand experience in your Panel Material-UI applications using the "Orbitron" brand example. You'll learn how to structure your brand assets, configure consistent theming, and apply your brand across all components.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Color`
	`1`	`+# Pick Colors`
`2`	`2`
`3`	`3`	Convey meaning through color. By default, `panel-material-ui` provides access to the [Material Design color system](https://m2.material.io/design/color/the-color-system.html#color-usage-and-palettes), allowing you to choose from a broad set of hues and shade combinations.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Themed Components`
	`1`	`+# Theme Components`
`2`	`2`
`3`	`3`	You can customize `panel-material-ui` components—changing default props, styles, or adding new variants—by defining a `components` key within your `theme_config`. This approach is ideal for ensuring a consistent look and feel across your entire application. If your customizations are extensive, however, consider creating new component classes for maintainability.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Custom Components`
	`1`	`+# Build Custom Components`
`2`	`2`
`3`	`3`	The `panel-material-ui` package ships with a number of custom Material UI components that are built on top of the Material UI library. However, in some cases, you may need to create your own custom components.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# How to Customize`
	`1`	`+# Customize Themes & Styles`
`2`	`2`
`3`	`3`	Customization of Panel Mui components inherits all the benefits of having a consistent design language that Mui provides. Styling can be applied using the `sx` parameter, while theming is achieved through the inheritable `theme_config`. Let us walk through these two different approaches through a series of examples.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Dark Mode`
	`1`	`+# Control Dark Mode`
`2`	`2`
`3`	`3`	The `panel-material-ui` components automatically integrate with Panel’s dark mode configuration and allow you to force dark mode by setting `dark_theme=True` at the component level or in your Panel extension.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Icons`
	`1`	`+# Use Icons`
`2`	`2`
`3`	`3`	panel-material-ui ships with the Material UI icon library. This means that you can use any of the icons defined in the [Material UI icon library](https://mui.com/material-ui/material-icons/) by default and also include them in `Markdown` and `HTML` components.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Palette`
	`1`	`+# Customize Color Palettes`
`2`	`2`
`3`	`3`	The `panel-material-ui` palette system allows you to customize component colors to suit your brand. Colors are grouped into default categories (primary, secondary, error, warning, info, success) or custom categories that you define yourself.
`4`	`4`