Custom named colors

Custom named colors#

This page reuses MIT licensed content from TeachBooks (2024). Find out more here.

User types

This section is useful for user type 3-5.

Sphinx Extension

Introduction#

This extensions provides a simple solution to use CSS named colors and custom named colors in:

\(\LaTeX\);
MarkDown text;
Admonitions.

What does it do?#

This extension defines, based on the CSS named color and custom named colors (provided by the user), several new

\(\LaTeX\) commands;
Sphinx roles;
Sphinx admonitions;
Sphinx admonition classes;

that are styled by a generated CSS file.

If specified, each color will have a different value in the light and dark data-theme.

Installation#

To use this extenstion, follow these steps:

Step 1: Install the Package

Install the sphinx-named-colors package using pip:

pip install sphinx-named-colors

Step 2: Add to requirements.txt

Make sure that the package is included in your project’s requirements.txt to track the dependency:

sphinx-named-colors

Step 3: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions (important: underscore, not dash this time):

sphinx: 
    extra_extensions:
        .
        .
        .
        - sphinx_named_colors
        .
        .
        .

Configuration#

This extension provides some configuration values, which can be added to:

sphinx: 
    config:
        .
        .
        .
        named_colors_include_CSS: true # default value
        named_colors_dark_and_light: true # default value
        named_colors_saturation: 1.5 # default value
        named_colors_custom_colors: None
        .
        .
        .

named_colors_include_CSS: true # default value

If set to true all CSS named colors will be included in the extension.
If set to false no CSS named colors will be included in the extension. If no custom named colors are defined, this extension will do nothing.

named_colors_dark_and_light: true # default value

true: for all CSS named colors and all custom named colors a secondary value will be generated for use in the dark data-theme, unless otherwise specifed for custom colors. The generated colors emulate the same as the CSS filter invert(1) hue_rotate(180) saturate(<val>); where <val> is the value set by named_colors_saturation. This filter is also used in the Sphinx Image Inverter
false: This disables the use of different colors in the dark data-theme, even if specified for custom colors.

named_colors_saturation: 1.5 # default value

number: The saturation value used in the generation of the dark data-theme colors.

named_colors_custom_colors: None

None: No custom named colors will be included.
dictionary: A Python dictionary where each key defines a custom name and the value is a list of 3 or 6 integers, with each integer at minimum 0 and at maximum 255.
- If 3 integers are provided, these are the RGB values of the custom named color and, if specified, the dark data-theme color will be generated.
- If 6 integers are provided, the first set of 3 integers form the RGB values of the custom named color and the second set of 3 integers form the RGB values of the dark data-theme color.
- Each key should contain only characters from the ranges a-z. Hyphens (-) are allowed, however this is not recommended.
- An example value:
  - {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110]}

Provided code#

Note

In the next part, replace namedcolor by the name of the CSS/custom named color.

\(\LaTeX\) elements#

Named colors without hyphens

\namedcolor{...}

Only use in \(\LaTeX\) code.
This will typeset ... in the color namedcolor.

Named colors with hyphens

\class{namedcolor}{...}

Only use in \(\LaTeX\) code.
This will typeset ... in the color namedcolor.

MarkDown elements#

{namedcolor}`...`

Only use in MarkDown code.
This will typeset ... in the color namedcolor.

To provide the use of strong and/or emphasis colored text, we als provide the next three roles:

{namedcolor_strong}`...`

{namedcolor_emphasis}`...`

{namedcolor_strong_emphasis}`...`

These extra roles have been created using the extension sphinxnotes-comboroles.

Admonitions#

Colored admonitions can be generated in two ways, explained below.

1. By adding a class to an existing admonition

::::{type} Title (optional or required, depending on type)
:class: namedcolor
Content
::::

2. By using a new admonition

::::{namedcolor} Title (optional)
Content
::::

If the title is omitted in the new admonition, the title bar will not be displayed.

In both cases extra classes can be added to the admonition to apply other styling.

A special new class for existing admonitions is also introduced: no-title. This suppresses printing of the title bar, even if the title is given. For the named color admonitions this happens automatically if no title is given.

For the named color admonitions the class show-bar is introduced for titleless admonitions. This forces printing of the title bar. If a title is given, the title will be printed too and adding the class show-bar is redundant.

Warning

Note that, because of the use of CSS, sometimes results may differ from the expected result.

Examples & details#

Overview of chosen options for the examples#

sphinx:
  config:
    named_colors_dark_and_light: true # default value
    named_colors_saturation: 1.5 # default value
    named_colors_include_CSS: true # default value
    named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160]}

\(\LaTeX\) colors#

Some examples of CSS named colors and the custom named colors used within LaTeX code. Do not forget to check out the colors in the darklight data-theme!

All of the \(\LaTeX\) commands can be used in all components that already support \(\LaTeX\).

MarkDown text colors#

The defined roles can be used in regular MarkDown code, similar to other roles such as numref and code.

Color	Style	Markdown Code	Result
olive	regular	{olive}`regular`	regular
hotpink	strong	{hotpink_strong}`strong`	emphasis
onlylight	emphasis	{onlylight_emphasis}`emphasis`	emphasis
lightanddark	strong emphasis	{lightanddark_strong_emphasis}`strong emphasis`	*strong emphasis*
hyphen-color	regular	{hyphen-color}`regular`	regular

Colored admonitions#

Any existing admonition supporting the class option, whether provided by Sphinx or by a Sphinx extension, can be given a different color by adding a CSS/custom named color to the list of classes.

An alternative option is to use an admonition with the name of the CSS/custom named color and add the type of admonition to the list of classes. In that case and for admonitions without the title argumentbut an automatic title (such as wanring), a title has to be set explicitly. This alternative approach does take over numbering (if any) of the oringinal admonition type (if any).

Following are some examples with different colors, with the two code options next to each other, followed by the two results.

A special feature is a new class for existing admonitions: no-title. This suppresses printing of the title, even if the title is given. For the named color admonitions this happens automatically if no title is given.

General admonition

::::{admonition} General admonition with title
:class: olive
Content of general admonition.
::::

::::{olive} General admonition with title
Content of general admonition.
::::

General admonition with title

Content of general admonition.

General admonition with title

Content of general admonition.

Dropwdown admonition

::::{admonition} Dropdown admonition with title
:class: hotpink, dropdown
Content of general admonition.
::::

::::{hotpink} Dropdown admonition with title
:class: dropdown
Content of general admonition.
::::

Dropdown admonition with title

Content of general admonition.

Dropdown admonition with title

Content of general admonition.

Common admonitions

::::{warning}
:class: darkturquoise
Content of warning.
::::

::::{darkturquoise} Warning
:class: warning
Content of warning.
::::

Warning

Content of warning.

Warning

Content of warning.

Admonitions from Sphinx-Proof

::::{prf:defintion}
:class: onlylight
Content of definition.
::::

::::{onlylight} Definition
:class: definition
Content of definition.
::::

Definition 1

Content of definition.

Definition

Content of definition.

Titleless admonitions

::::{admonition} This title will not be shown
:class: lightanddark, no-title
Content of admonition.
::::

::::{lightanddark}
Content of admonition.
::::

This title will not be shown

Content of admonition.

Titleless admonitions with dropdown

In case a dropdown admonition is required without a title, only the new CSS/custum named color admonitions can safely be used.

::::{lightcoral}
:class: dropdown, warning
Content of admonition.
::::

Content of admonition.

Titleless admonitions with title bar

In case an admonition is required without a title but with a title bar, only the new CSS/custum named color admonitions can safely be used. In that case add the class show-bar.

::::{gold}
:class: show-bar, warning
Content of admonition.
::::

Content of admonition.

Contribute#

This tool’s repository is stored on GitHub. If you’d like to contribute, you can create a fork and open a pull request on the GitHub repository.

The README.md of the branch manual is also part of the TeachBooks manual as a submodule.

Custom named colors

Contents

Custom named colors#

Introduction#

What does it do?#

Installation#

Configuration#

Provided code#

\(\LaTeX\) elements#

MarkDown elements#

Admonitions#

Examples & details#

Overview of chosen options for the examples#

\(\LaTeX\) colors#

MarkDown text colors#

Colored admonitions#

Contribute#