update docs for meta tags feature

vizro-core/changelog.d/20240102_064659_amward_update_docs_meta_tags.md

@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->

vizro-core/docs/pages/development/contributing.md

@@ -44,6 +44,14 @@ hatch run example from_dict
 
 If no example is specified (`hatch run example`) then the [default example](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/default/app.py) is used.
 
+## Documentation
+
+If you're modifying documentation, the following will do a hot-reloading build of the rendered docs:
+
+```console
+hatch run docs:serve
+```
+
 ## Debugging tips
 
 - [Dash dev tools](https://dash.plotly.com/devtools) are enabled in all the Hatch environments by setting environment variable `DASH_DEBUG = "true"`, and so there is no need to specify `debug=True` when calling `Vizro.run` to enable them. The reload functionality, callback graph and in-browser error messages are particularly useful.
@@ -124,7 +132,7 @@ Note that Hatch's `default` environment specifies `pre-commit` as a dependency b
 
 We use [gitleaks](https://github.com/gitleaks/gitleaks) for secret scanning. We do this via `pre-commit`, however there are a few things to note:
 
-1. Using `gitleaks` may require an installation of `go` on the developer machine. This is easy and explained [here](https://go.dev/doc/install).
+1. Using `gitleaks` may require an installation of `go` on the developer machine. This is easy and explained in the [Go documentation](https://go.dev/doc/install).
 2. For that reason `hatch run lint` skips the secret scans, to function on all machines.
 3. To run a secret-scan, simply run `hatch run secrets`.
 4. Secret scans will run on CI, but it is highly recommended to check for secrets **before pushing to the remote repository** and ideally also before even committing.

vizro-core/docs/pages/user_guides/assets.md

@@ -15,16 +15,17 @@ The user-provided `assets` folder thus always takes precedence.
 │   ├── images
 │       ├── icons
 │           ├── collections.svg
-├── favicon.ico
+│       ├── app.svg
+│   ├── favicon.ico
 ```
 
 ## Changing the favicon
 To change the default favicon (website icon appearing in the browser tab), add a file named `favicon.ico` to your `assets` folder.
-For more information, see [here](https://dash.plotly.com/external-resources#changing-the-favicon).
+For more information, see the [Dash documentation](https://dash.plotly.com/external-resources#changing-the-favicon).
 
 ## Overwriting global CSS properties
 To overwrite any global CSS properties of existing components, target the right CSS property and place your CSS files in the `assets` folder. This will overwrite any existing defaults for that CSS property.
-For reference, all Vizro CSS files can be found [here](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css).
+For reference, see the [Vizro CSS files](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css).
 
 !!! example "Customizing global CSS properties"
     === "my_css_file.css"
@@ -82,7 +83,7 @@ For reference, all Vizro CSS files can be found [here](https://github.com/mckins
 
 ## Overwriting CSS properties in selective components
 To overwrite CSS properties of selective components, provide an ID to the relevant component and target the right CSS property.
-For more information on how CSS selectors work, see [here](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure).
+For more information, see this [CSS selectors tutorial](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure).
 
 Let's say we want to change the background and font-color of one [`Card`][vizro.models.Card] instead of all existing Cards in the Dashboard.
 We can use the ID of the outermost Div to target the inner sub-components of the card. Note that all our components have an ID attached to the outermost Div,
@@ -169,4 +170,13 @@ app = Vizro(assets_folder="path/to/assets/folder").build(dashboard).run()
 ```
 
 Note that in the example above, you still need to configure your [`Page`][vizro.models.Page].
-A guide on how to do that you can find [here](pages.md).
+See more information in the [Pages User Guide](pages.md).
+
+
+## Meta tags image
+
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
+clients. To include an image in the preview, place an image file in the assets folder named `app.<extension>`  or
+`logo.<extension>`. Vizro searches the assets folder and uses the first one it finds.
+
+Image types of `apng`, `avif`, `gif`, `jpeg`, `jpg`, `png`, `svg`, and `webp` are supported.

vizro-core/docs/pages/user_guides/dashboard.md

@@ -191,7 +191,16 @@ After running the dashboard, you can access the dashboard via `localhost:8050`.
 
 ## Adding a dashboard title
 
-If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top left of every page. It is also combined with the `title` specified in [`Page`][vizro.models.Page] to set:
+If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top left of every page.
 
-- `<title>` HTML element that controls the text labeling a browser window;
-- `<meta>` elements that control how a preview is generated when sharing a link to your dashboard (e.g. on social media).
+
+## Browser title
+
+The [website icon](assets.md/#changing-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
+title bar.  For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
+
+## Meta tags for social media
+
+Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
+clients.  The preview includes the `URL`, `title`, plus an [image](assets.md/#meta-tags-image) and
+[Page `description`][vizro.models.Page] (if supplied).  To see an example, try sharing the [Vizro demo app](https://vizro.mckinsey.com/).

vizro-core/docs/pages/user_guides/pages.md

@@ -25,6 +25,7 @@ To create and add a page to your dashboard, do the following steps:
 2. Configure your `components`, see our guide on [Charts/Components](components.md)
 3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md)
 4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md)
+5. (optional) Provide a `description` of your `Page` for the app's [meta tags](https://metatags.io/)
 
 !!! example "Page"
     === "app.py"
@@ -37,6 +38,7 @@ To create and add a page to your dashboard, do the following steps:
 
         page = vm.Page(
             title="Page Title",
+            description="Longer description of the page content",
             components=[
                 vm.Graph(
                     id="sunburst", figure=px.sunburst(gapminder, path=["continent", "country"], values="pop", color="lifeExp")
@@ -79,6 +81,7 @@ To create and add a page to your dashboard, do the following steps:
               - sunburst.color
             type: parameter
           title: Page Title
+          description: "Longer description of the page content"
         ```
     === "Result"
         [![Page]][Page]