diff --git a/docs/source/socialcards.md b/docs/source/socialcards.md index 497d08e..2e01ca2 100644 --- a/docs/source/socialcards.md +++ b/docs/source/socialcards.md @@ -23,13 +23,31 @@ ogp_social_cards = { } ``` +## Update the top-right image + +By default the top-right image will use the image specified by `html_logo` if it exists. +To update it, specify another path in the **`image`** key like so: + +```{code-block} python +:caption: conf.py + +ogp_social_cards = { + "image": "path/to/image.png", +} +``` + +```{admonition} The image cannot be an SVG +:class: warning + +Matplotlib does not support easy plotting of SVG images, so ensure that your image is a PNG or JPEG file, not SVG. +``` + ## Customize the card There are several customization options to change the text and look of the social media preview card. Below is a summary of these options. - **`site_url`**: Set a custom site URL. -- **`image`**: Over-ride the top-right image (by default, `html_logo` is used). - **`line_color`**: Color of the border line at the bottom of the card, in hex format. % TODO: add an over-ride for each part of the card. diff --git a/sphinxext/opengraph/socialcards.py b/sphinxext/opengraph/socialcards.py index 798d497..ab15502 100644 --- a/sphinxext/opengraph/socialcards.py +++ b/sphinxext/opengraph/socialcards.py @@ -4,10 +4,11 @@ import matplotlib from matplotlib import pyplot as plt import matplotlib.image as mpimg +from sphinx.util import logging matplotlib.use("agg") - +LOGGER = logging.getLogger(__name__) HERE = Path(__file__).parent MAX_CHAR_PAGE_TITLE = 75 MAX_CHAR_DESCRIPTION = 175 @@ -91,6 +92,22 @@ def create_social_card( Path(__file__).parent / "_static/sphinx-logo-shadow.png" ) + # Validation on the images + for img in ["image_mini", "image"]: + impath = kwargs_fig.get(img) + if not impath: + continue + + # If image is an SVG replace it with None + if impath.suffix.lower() == ".svg": + LOGGER.warn(f"[Social card] {img} cannot be an SVG image, skipping...") + kwargs_fig[img] = None + + # If image doesn't exist, throw a warning and replace with none + if not impath.exists(): + LOGGER.warn(f"[Social card]: {img} file doesn't exist, skipping...") + kwargs_fig[img] = None + # These are passed directly from the user configuration to our plotting function pass_through_config = ["text_color", "line_color", "background_color", "font"] for config in pass_through_config: @@ -265,12 +282,12 @@ def create_social_card_objects( c=site_url_color, ) - if image_mini: + if isinstance(image_mini, Path): img = mpimg.imread(image_mini) axim_mini.imshow(img) # Put the logo in the top right if it exists - if image: + if isinstance(image, Path): img = mpimg.imread(image) yw, xw = img.shape[:2] diff --git a/tests/roots/test-social-cards-svg/conf.py b/tests/roots/test-social-cards-svg/conf.py new file mode 100644 index 0000000..8582158 --- /dev/null +++ b/tests/roots/test-social-cards-svg/conf.py @@ -0,0 +1,12 @@ +extensions = ["sphinxext.opengraph"] + +master_doc = "index" +exclude_patterns = ["_build"] + +html_theme = "basic" +ogp_site_url = "http://example.org/en/latest/" + +# The image is an SVG, and so it should not be included in the social cards +ogp_social_cards = { + "image": "foo.svg", +} diff --git a/tests/roots/test-social-cards-svg/index.rst b/tests/roots/test-social-cards-svg/index.rst new file mode 100644 index 0000000..a33871d --- /dev/null +++ b/tests/roots/test-social-cards-svg/index.rst @@ -0,0 +1 @@ +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse at lorem ornare, fringilla massa nec, venenatis mi. Donec erat sapien, tincidunt nec rhoncus nec, scelerisque id diam. Orci varius natoque penatibus et magnis dis parturient mauris. \ No newline at end of file diff --git a/tests/test_options.py b/tests/test_options.py index 195cb00..443e5d8 100644 --- a/tests/test_options.py +++ b/tests/test_options.py @@ -87,6 +87,12 @@ def test_local_image(og_meta_tags): ) +@pytest.mark.sphinx("html", testroot="social-cards-svg") +def test_social_cards_svg(app: Sphinx, og_meta_tags): + """If the social cards image is an SVG, it should not be in the social card.""" + assert app.statuscode == 0 + + @pytest.mark.sphinx("html", testroot="image") def test_image_alt(og_meta_tags): assert get_tag_content(og_meta_tags, "image:alt") == "Example's Docs!"