Layer Typography Attribute¶

class Typography¶

The border specification defines the behavior of rendering an outline around each character.

Seealso

This attribute shares the same border specification that is used by the supported Basic Shapes.

Important

If the border.color is not specified, then the typography.color is used.

A stroke around transparent characters¶

size: { width: 600, height: 110 }
layers:
- background: {color: "#4051b5"}
- typography:
    content: Fancy Text
    color: '#00000000' # a transparent color
    align: center
    border:
        width: 2
        color: white

content : str¶

The text to be displayed. This can be a Jinja syntax that has access to the card’s jinja contexts.

The text content is pre-processed (after parsed from Jinja syntax) to allow comprehensive wrapping of words. This is beneficial for long winded programmatic names.

Caution

Beware that leading and trailing whitespace is stripped from each line.

Long words Preserved line breaks

Using an API name as the page title¶

:title: sphinx_social_cards.validators.LayerTypographyDataclass._fg_color

Note

Line breaks are not supported when using Metadata.

Using a line break between words¶

layers:
  - background: { color: '#4051B2' }
  - size: { width: 1080, height: 360 }
    offset: { x: 60, y: 150 }
    typography:
      content: |
        Paragraph 1

            Line with leading spaces
      line: { amount: 3 }

align : Literal['start top', 'start center', 'start bottom', 'center top', 'center', 'center center', 'center bottom', 'end top', 'end center', 'end bottom']¶

The alignment of text used. This is a string in which the space-separated words respectively describe the horizontal and vertical alignment.

Alignment Options¶
`start top`	`center top`	`end top`
`start center`	`center` or `center center`	`end center`
`start bottom`	`center bottom`	`end bottom`

color : Color | Linear_Gradient | Radial_Gradient | Conical_Gradient | None¶: The color to be used for the displayed text. If not specified, then this defaults to cards_layout_options.color.

Seealso

Please review Choosing a color section for more detail.

line : Line¶: The line specification which sets the amount of lines and the height of each line. This is used to calculate the font’s size.

overflow : bool¶: Set this option to true to automatically shrink the font size enough to fit within the layer’s size. By default (false), text will be truncated when the layer’ capacity is reached, and an ellipsis will be added.

overflow: off overflow: on

font : Font | None¶: The specified font to use. If not specified, then this defaults to values in cards_layout_options.font.

Seealso

Please review Choosing the font section.

Typography Line specification¶

class Line¶

These properties are used to calculate the font’s size based on the layer’s absolute maximum size.

amount : Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])]¶: The maximum number of lines that can be used in the layer.

height : Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])]¶: The relative height allotted to each line. This has a direct affect on spacing between lines because each layer has an absolute maximum size.

height: 0.75 height: 1 height: 1.25 height: 2.0 height: 0.5

0.75 means each line can have 75% of the appropriately available line height. Text will be smaller, but the layer’s height will not be fully used.

1 means each line can have the full appropriately available line height. Text will be large enough to fit within of the appropriately available line height.

1.25 means each line can have 125% of the appropriately available line height. Text will be bigger but the space between lines will be smaller (can even be negative).

2.0 means each line can have 200% of the appropriately available line height. Text should never exceed the layer size, thus spacing between lines is adjusted accordingly.

0.5 means each line can have 50% of the appropriately available line height. Notice the line height is directly related to height of the layer.

Font specification¶

class Font¶

The specification that describes the font to be used.

Seealso

Please review the Choosing the font section.

family : str¶

This option specifies which font to use for rendering the social card, which can be any font hosted by Fontsource. Default is "Roboto" if not using the sphinx-immaterial theme. However, the sphinx-immaterial theme’s font option is used as a default if that theme is used.

If the font specified is not a Roboto font and cannot be fetched from Fontsource, then an exception is raised and the docs build is aborted.

style : str¶: The style of the font to be used. Typically, this can be italic or normal, but it depends on the styles available for the chosen family.

There is no inline style parsing.
Due to the way pillow loads fonts, there’s no way to embed syntactic inline styles for individual words or phrases in the text content. **bold** and *italic* will not render as bold and italic.

Instead, the layout customization could be used to individually layer stylized text.

weight : Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Gt(gt=0)])]¶: The weight of the font used. If this doesn’t match the weights available, then the first weight defined for the font is used and a warning is emitted. Default is 400.

subset : str | None¶: A subset type used for the font. If not specified, this will use the default defined for the font (eg. "latin").

path : str | None¶: The path to the TrueType font (*.ttf). If this is not specified, then it is set in accordance with the a cache corresponding to the family, style, weight, and subset options. If explicitly specified, then this value overrides the family, style, weight, and subset options.