canonical / canonical/vanilla-framework
[New component]: Pro callouts in docs (Sphynx)
- Dominant language
- HTML
- Stars
- 983
- Forks
- 216
- Avg merge
- 3d 13h
- Merged PRs (30d)
- 3
Description
## Visual

## Context
We have several documentation sets in which Pro-specific content appears on particular pages. Examples include real-time Ubuntu, ADSys and Ubuntu on WSL, but there are probably more.
Here's a screenshot of the Ubuntu on WSL docs (only some of the pages for WSL relate to Pro content):

In this page, there are several admonitions/callouts, including one for info, a warning and a note. These admonition styles are provided by default through the theme that we use for our documentation.
Ignore for now that the Note should probably be an Info, to keep in line with the Vanilla framework. As technical authors, we usually use admonitions for technical information ("you may need to install x dependency...", "you may need to backup your y...", "as of version z, you need to foo...").
My intuition is that while it's important to find some way of highlighting Pro features, using callouts normally used for general technical asides is not the best solution.
In the case above, we would have an info block used to highlight a Pro feature but also one to explain how we use prompts in this docs set.
I would propose we use a custom callout like this:


This would help frame Pro-content more positively and make it distinct from the more mundane uses of callouts in our docs.
It requires a small CSS file that creates a custom style for a callout that authors would use just like other callouts in the docs (same syntax).
For this demonstration, I cleaned up an SVG of the Ubuntu logo, combined it into a path, and embedded that in the CSS file.
If we had something like this, it would also help us standardise how we refer to Pro-specific content in docs, which currently varies depending on the team.
___
This was proposed by @edibotopic
Contributor guide
Research direction
Start by reviewing the existing admonition and callout styles used across the documentation sets, then identify how a custom style can preserve the current callout syntax. Done means a distinct Pro callout is available through a small CSS addition and visually separates Pro-specific content from ordinary technical admonitions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- css
- Domain
- design, documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100