Add message banners to every page

In some contexts, for example when a package is being deprecated, or to mark a specific version of package documentation as unsupported, you might want to add a fairly visible message banner to all pages to inform the users and possibly redirect them to other documentation.

Note

For more information about deprecated and obsolete feature messages to put in the banner, refer to the Unity Style Guide.

Principle

Add a dynamic placeholder (as an "Include" tag for reusable content targeting a single source file) under all H1 titles of a package documentation fileset, and manage the actual message content in one place (in the single source file).

Pre-requisites

This method assumes the following:

  • The documentation is Unity package documentation.
  • The documentation file format is markdown for use with DocFX pipeline.
  • The documentation file structure complies with Unity’s content model.
  • Your text editor is Visual Studio Code (although it might work with other Regex-capable text editors).

Add an "Include" below each H1 title

Use Regex in Visual Studio Code to:

  • Search and capture all H1 titles (formatted with a single #).
  • Replace them with themselves plus the required "Include" tag.

^# (.+)$

Regex element Description
^ and $ Represent line start and line end characters, to isolate a single line and cover it completely.
#   The reference characters to search, used as unique markers for a H1 title (single sharp character + space).
. Represents any single character (included in the title).
+ Repeats (with accumulation) the search of subsequent characters with the same criteria.
() Capture (memorize) the string in between. In this case, this is the full text of the title.

Replace

# $1\n\n[!INCLUDE [banner-message](snippets/banner-message.md)]

Characters Description
#   The H1 title identifiers to keep (single sharp character + space).
$1 Represents the string captured in search (i.e. the title we want to keep).
\n\n Adds two line breaks after the title.
[!INCLUDE [banner-message](snippets/banner-message.md)] Adds the required text string, an "Include" that calls reusable content from a single markdown file (to create) named banner-message.md and located in a subfolder named snippets.

Create a new file for the "Include" content

Create the file called from the "Include" added in all documentation pages.

File name

banner-message.md

Note

A common recommendation is to group reusable content files in a subfolder named snippets, like for the images.

File content

> [!IMPORTANT]
> This is the message.
Note

Don’t forget to end the file with an empty line.